^GC - Graphic Circle

^GC draws a circle, or a filled disc, at the current field origin. It takes one diameter and not a width and a height, so it draws true circles only. For an oval use ^GE, whose bounding box takes both.

Syntax

^GCd,t,c

Support

Supportedparsed: full · state: full · rendered: full

Every documented parameter renders the same output Labelary produces.

Labelary renders this command.

Parameters

dCircle diameteroptional · dots

Outer diameter of the circle in dots. The field origin is the top-left of the circle's bounding box, not its center.

Default: 3
Accepted range: 3 to 4095 dots
Invalid value: clamped to the nearest allowed value. The renderer clamps diameters below 3 and above 4095 to the nearest bound.
Test coverage: Bounds pinned: below the minimum (2), above the maximum (4096). No test at the minimum or maximum. The invalid-value rule is pinned by 2 tests.

tBorder thicknessoptional · dots

Thickness of the ring, drawn inwards from the outer diameter. A thickness of at least half the diameter fills the circle solid.

Default: 1
Accepted range: 1 to 4095 dots
Invalid value: clamped to the nearest allowed value. The real minimum is 1, not the 2 the guide documents: ^GC100,1 draws a single-dot ring and the renderer reports only values below 1. We measured this against live Labelary on 2026-07-12, and the parser matches it.
Test coverage: Bounds pinned: minimum (1), above the maximum (4096), past what the shape can hold (300). No test at the maximum. The invalid-value rule is pinned by 2 tests.

cLine colouroptional · one of a set

Color of the ring and fill.

Default: B
Invalid value: discarded, and the default applies. Any value other than B or W draws black.
Test coverage: Values exercised: W. Not exercised: B. The invalid-value rule is not pinned by a test.

B: Black (default)
W: White, which erases whatever the circle covers

Behavior

The preceding ^FO or ^FT positions the circle, and ^FS ends it. ^FO places the top-left corner of the circle's bounding box, not the center. A ^FO100,100^GC80 circle fills the square from (100, 100) to (180, 180), and its center lands at (140, 140).

The thickness draws inwards from the outer diameter, so the circle never grows past the requested diameter, whatever the thickness of its ring. At half the diameter the ring meets itself in the middle and the circle is solid: ^GC80,40 is a filled disc, and every value above 40 gives the same disc.

The guide contradicts itself on the thinnest ring it draws: the accepted range starts at 2, and the default is 1. Measurement settles it. The renderer accepts a thickness of 1 and draws a single-dot outline, and reports only a value below 1 as invalid.

Color W draws white over what is already on the label and does not print white ink, so a circle punches a hole in a filled area. Fields draw in the order they appear, so the circle hides only what precedes it.

Tested behavior

Differences from the specification

Labelary against the ZPL II guide

Where Labelary — our compatibility target — behaves differently from the printed specification.

The guide contradicts itself: minimum 2, default 1, for the border thickness. Labelary's real minimum is 1, and it reports only values below that. We measured this on 2026-07-12. — pinned by test_gc_thickness_one_is_silent

Example

A thin ring, a solid disc, and a ring thick enough to leave only a small hole:

^XA
^FO50,50^GC120,1^FS
^FO250,50^GC120,60^FS
^FO450,50^GC120,45^FS
^XZ

Open in viewer

^GB Graphic BoxDraws a rectangle, a line or a filled block.
^GE Graphic EllipseDraws an ellipse.
^GD Graphic Diagonal LineDraws a diagonal line across a bounding box.
^FO Field OriginSets the top-left corner of the next field.

^GC - Graphic Circle

On this page