^GB - Graphic Box

^GB draws an axis-aligned rectangle from the current field origin. It also draws straight lines and solid blocks. A box narrower than its own border thickness collapses into a line, and a box whose thickness reaches half its shorter side fills solid. ZPL has no separate line or fill command.

Syntax

^GBw,h,t,c,r

Support

Supportedparsed: full · state: full · rendered: full

Every documented parameter renders the same output Labelary produces.

Labelary renders this command.

Parameters

wBox widthoptional · dots

Width of the box in dots, measured from the field origin. The guide's minimum is the border thickness, not 1, because a box cannot be narrower than its border.

Default: the value of t, which draws a vertical line
Accepted range: the value of t to 32000 dots
Invalid value: discarded, and the default applies. A non-numeric or zero width defaults to the thickness, so ^GB,,3 is a 3-dot line rather than nothing. The renderer raises a width below the thickness to it, and reports that as an invalid argument.
Test coverage: Bounds pinned: below the minimum (5). No test at the minimum or maximum. The invalid-value rule is pinned by 1 test.

hBox heightoptional · dots

Height of the box in dots, measured downwards from the field origin. As with the width, the guide's minimum is the border thickness.

Default: the value of t, which draws a horizontal line
Accepted range: the value of t to 32000 dots
Invalid value: discarded, and the default applies. A non-numeric or zero height defaults to the thickness. The renderer raises a height below the thickness to it, with the same invalid-argument report as the width.
Test coverage: No test at the minimum, maximum or one step outside the range. The invalid-value rule is pinned by 2 tests.

tBorder thicknessoptional · dots

Thickness of the border, drawn inwards from the outline. A thickness at least half the width or height fills the box solid.

Default: 1
Accepted range: 1 to 32000 dots
Invalid value: discarded, and the default applies
Test coverage: Bounds pinned: below the minimum (0), above the maximum (32001), past what the shape can hold (105). No test at the minimum or maximum. The invalid-value rule is pinned by 1 test.

cLine colouroptional · one of a set

Color of the border and fill.

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

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

rCorner roundingoptional · integer

Degree of corner rounding, from 0 (square corners) to 8 (heaviest rounding).

Default: 0
Accepted range: 0 to 8
Invalid value: discarded, and the default applies. Values above 8 reset to the default of 0, square corners, rather than clamp to 8. Labelary reports the same: "Value 9 is greater than maximum value 8; used 0 instead". This is an index, not a radius in dots; the radius scales with the shorter side of the box.
Test coverage: Bounds pinned: maximum (8), above the maximum (9). No test at the minimum. The invalid-value rule is not pinned by a test.

Behavior

The preceding ^FO or ^FT positions the box, and ^FS ends it, as for any other field. ^FO places the top-left corner. ^FT places the baseline, which for a box is the bottom-left corner.

The border draws inwards from that outline, so the box never grows past the w by h rectangle, whatever the border thickness. The degenerate cases follow from this:

omit w for a vertical line t dots wide and h dots tall;
omit h for a horizontal line;
set t to at least half of the shorter side, and the border meets itself in the middle to give a solid block.

Color W does not draw white ink, because a printer has none. The box draws white over what is already on the label, and punches a gap in a filled area. Fields draw in the order they appear, so a white box hides only what precedes it in the format.

The corner argument is an index from 0 to 8, not a radius in dots. The guide gives the radius it draws as (r / 8) * (shorter side / 2), so one r gives visibly different corners on a small box and a large one. A value above 8 clamps to 8, and the renderer does not reject it.

Tested behavior

Example

A 400 by 200 outlined box, a horizontal rule, and a solid block:

^XA
^FO50,50^GB400,200,4^FS
^FO50,300^GB400,,3^FS
^FO50,350^GB120,60,30^FS
^FO50,450^GB200,100,4,B,6^FS
^XZ

Open in viewer

^GC Graphic CircleDraws a circle.
^GD Graphic Diagonal LineDraws a diagonal line across a bounding box.
^GE Graphic EllipseDraws an ellipse.
^FO Field OriginSets the top-left corner of the next field.
^FR Field Reverse PrintInverts the field where it overlaps what is already on the label.