Text Properties

Text Properties

Up to nine independent text groups can be configured using options prefixed with text1 through text9. The old option names are retained as aliases: alttext = text1, extratext = text2, textfont = text1font, extratextfont = text2font, and so on for the remaining properties.

Note: Some encoders (e.g. EAN/UPC, ISBN, ISSN, ISMN) provide directly-positioned text where each character is placed by the encoder at a specific location. The font, size and color options apply to encoder-positioned text. The subspace, split, linegaps and gaps options do not apply unless the text content is overridden using text1 (or alttext), which switches to the general text layout engine.

includetext

Enable display of the encoder's default text for the symbol. This activates the encoder-positioned text for text1. There is no equivalent for other text groups.

Setting content directly (e.g. text1=HELLO or alttext=HELLO) activates text1 without requiring includetext. When both includetext and text1 content are set, the explicit content takes precedence. For text2 through text9, setting content (e.g. text3=LABEL) is sufficient to activate the group.

Notes

• If a character in the data does not have a printable representation then it is not displayed.

Example

Data:    SEE ME
Options: includetext
Encoder: code39

text{1-9}font

The PostScript font name for a text group.

Aliases: textfont = text1font, extratextfont = text2font

Notes

• The font name must be the literal name of a PostScript font that is available to the system.
• The PostScript font name for a font file can be determined with the following command from the fontconfig library:
  • fc-scan --format "%{postscriptname}\n" /usr/share/fonts/truetype/somefont.ttf

Example

Data:    FONT
Options: includetext textfont=Times-Roman
Encoder: code39

text{1-9}size

The font size of a text group in points.

Aliases: textsize = text1size, extratextsize = text2size

Example

Data:    SIZE
Options: includetext textsize=20 textyoffset=-12
Encoder: code39

text{1-9}gaps

The inter-character spacing of a text group.

Aliases: textgaps = text1gaps, extratextgaps = text2gaps

Note

• This option requires a text alignment to be set (e.g. textxalign).

Example

Data:    HELLO
Options: includetext textxalign=center textgaps=10
Encoder: code128

text{1-9} (content)

Specify the text content to display for a text group. For text1, this overrides the encoder's default text. For text2 through text9, setting the content activates the text group.

Aliases: alttext = text1, extratext = text2

Notes

• Text1 defaults to centered below the symbol (or encoder-positioned when using includetext).
• Text2 through text9 default to left-aligned above the symbol.

Example: text1 content

Data:    ABC123
Options: includetext alttext=CUSTOM-TEXT
Encoder: code128

Example: text2 content

Data:    Hello
Options: version=8 includetext alttext=Hello extratext=SCAN~ME
         extratextsubspace=~ extratextfont=Helvetica-Bold
         extratextsize=8 extratextyoffset=6
Encoder: qrcode

Example: multiple text groups

Data:    Hello
Options: version=8 text2=SCAN~ME text2subspace=~ text2font=Helvetica-Bold
         text2size=8 text2yalign=above
         text3=ID:~12345 text3subspace=~ text3size=6 text3yalign=below
Encoder: qrcode

text{1-9}subspace

Specify a set of characters that will be replaced with spaces within the text content.

Aliases: alttextsubspace = text1subspace, extratextsubspace = text2subspace

Note

• Applies to text content set via textN (or alttext/extratext), not to encoder-positioned text.

Example

Data:    ABC123
Options: includetext alttext=WITH~SPACES alttextsubspace=~
Encoder: code128

text{1-9}split

Specify a character by which to split the text content into separate lines.

Aliases: alttextsplit = text1split, extratextsplit = text2split

Note

• Applies to text content set via textN (or alttext/extratext), not to encoder-positioned text.

Example

Data:    ABC123
Options: includetext alttext=LINE~ONE|LINE~TWO alttextsubspace=~ alttextsplit=|
Encoder: code128

text{1-9}linegaps

Specify the gap between consecutive text lines for a text group.

Aliases: textlinegaps = text1linegaps, extratextlinegaps = text2linegaps

Note

• This option should be used in combination with textNsplit (or alttextsplit/extratextsplit).

Example

Data:    ABC123
Options: includetext alttext=LINE~ONE|LINE~TWO alttextsubspace=~
         alttextsplit=| textlinegaps=10
Encoder: code128