Using Fonts

Every TextItem and BarcodeItem has a Font property (BarcodeItem also has TextFont for the human-readable text). This topic explains which kinds of fonts you can use, what each one supports, and how they behave when you print versus when you export a label to PDF or an image.

Note

This topic applies to TextItem, BarcodeItem and any other item that exposes a Font. For the full list of Font, FontManager and TextItem members, see the API Reference.

Which font should I use?

I need... Use Printed as
The fastest printing, simple single-line text, any ZPL / EPL / Fingerprint/Direct Protocol printer Native Printer Fonts Printer's built-in font (text commands)
A scalable font, multiline text and alignments, still fast ZPL Font 0 Printer's built-in font (text commands) on ZPL and Fingerprint/Direct Protocol. Graphics on EPL
Rich text features (Unicode, RTL, stretching, rounded borders, etc.) with a standard font Installed Windows TTF fonts Graphics, or text if uploaded to the printer (TTF optimization)
A font that is not installed on the machine (dingbats, corporate fonts) Custom TTF font files Same as above
Fast printing with a TTF font on ZPL or Fingerprint/Direct Protocol Upload the TTF to the printer Text commands using the printer storage

As a rule of thumb: use an NPF whenever your text does not need special formatting, and fall back to TTF fonts only when you need more.

The Font class

Neodynamic.SDK.Printing.Font encapsulates all font settings. Do not confuse it with System.Drawing.Font; use the full name if your code also imports System.Drawing.

var txt = new TextItem(0.25, 0.25, 3.5, 0.5, "Hello");
txt.Font.Name = "Arial";
txt.Font.Size = 12;
txt.Font.Bold = true;
Property Description Default
Name Font name. Use the constants Font.NativePrinterFontA, Font.NativePrinterFontB and Font.NativePrinterFontS for the NPF. NativePrinterFontA
Size Font size, measured in Unit. 10
Unit FontUnit.Point (default) or any other value of the FontUnit enum. Point
Bold, Italic, Underline, Strikeout Font styles. false
CustomFontFile Path of a TTF file or the Base64 content of the TTF. See Custom TTF font files. Empty
CustomFontFileFamilyName Font family name of the custom TTF file, when it differs from Name. Empty
NameAtPrinterStorage Short name of a TTF previously uploaded to the printer. See TTF optimization. Empty
CodePage Code page used to encode text sent to the printer when using NPF or built-in fonts: CP850, CP1250 to CP1255 and UTF8. CP850
IsBitmapFont, Threshold Bitmap-font rendering options. Threshold is the black/white cut-off (0 to 255) used when the text is converted to a monochrome image. false, 90

A Font can be created with its constructors, for example new Font("Arial", 12), or modified through the Font property of the item.

Native Printer Fonts (NPF)

The NPF is an abstraction that hides the complexity of dealing with different built-in printer fonts when you target several kinds of printers (ZPL, EPL and Fingerprint/Direct Protocol). It provides three fonts: NativePrinterFontA, NativePrinterFontB and NativePrinterFontS.

Each NPF is available in two forms:

  • When printing, the SDK sends the built-in ZPL, EPL or Fingerprint/Direct Protocol resident font that is internally associated with each NPF. The TrueType file is not used.
  • When exporting to PDF or image files, or when displaying the label in the ThermalLabel editor components, the SDK uses a TrueType (.ttf) font that simulates the printer font. These TrueType files are embedded in the SDK, so you don't have to install them on the machine.
Note

NPF has some limitations compared to non built-in fonts, but you should use it whenever possible to boost printing performance. If your text does not require special formatting, use an NPF.

The following table summarizes the features of each NPF.

FEATURE NativePrinterFontA NativePrinterFontB NativePrinterFontS
Font type Monospaced Scalable for ZPL and Fingerprint/Direct Protocol, monospaced for EPL Monospaced
Fixed sizes (in pts) 5, 10, 15, 20 and 25 7, 14, 21, 28 and 35 3 (the only size allowed; intended for very small text)
Font style Normal Bold Normal
Character set ASCII chars from 32 to 124, excluding 92, 94 and 123 ASCII chars from 32 to 124, excluding 92, 94 and 123 Upper-case letters (65 to 90) and digits (48 to 57)
Characters outside the set Sent with the code page of Font.CodePage (CP850 by default) using escape notation. No Unicode. Same as A Same as A
Unicode support NO NO NO
Text stretching NO NO NO
Rotation 0, 90, 180 and 270 degrees only 0, 90, 180 and 270 degrees only 0, 90, 180 and 270 degrees only
Rounded borders NO NO NO
Multiline text NO NO NO
TrueType file matching Glyphs are almost a perfect match to ZPL, EPL and Fingerprint/Direct Protocol. Almost a perfect match to ZPL and Fingerprint/Direct Protocol. On EPL the printer font is very different; test it first. Almost a perfect match to ZPL, EPL and Fingerprint/Direct Protocol.
Glyph appearance NativePrinterFontA NativePrinterFontB NativePrinterFontS

If any of the unsupported features is set on the item (multiline, sizing effects, right-to-left, rounded corners, justified text, stroke, char/line spacing, etc.), the TextItem is automatically printed as a graphic instead of as a text command. See Text vs Graphics Output.

Tip

Use Font.GetNearestSizeForNativePrinterFonts(...) to get the closest valid size when you work with arbitrary sizes. See the API Reference.

Screen/File rendering vs. printing output

Keep in mind the differences between what you get on screen or in a file and what you get from the printer:

  • NativePrinterFontA
    • NativePrinterFontA.ttf has glyphs almost identical to the built-in fonts of ZPL, EPL and Fingerprint/Direct Protocol. It is used when you export a label to PDF or image files.
    • On 203 dpi printers, the printed output of the three languages is almost identical. For EPL, the output at 300 or 600 dpi is identical to 203 dpi. For ZPL and Fingerprint/Direct Protocol, the output at 300 or 600 dpi differs a bit: the strokes look thinner than at 203 dpi. In all cases, the height and width of the characters are very close.
  • NativePrinterFontB
    • NativePrinterFontB.ttf matches the built-in font of ZPL and Fingerprint/Direct Protocol only. The EPL built-in font is very different. The TrueType font is used when exporting to PDF or images.
    • This is the "bold" NPF. In ZPL and Fingerprint/Direct Protocol the chosen font is scalable, while in EPL it is bitmapped, so the printed results are very different. We matched both fonts in character height. If you target only ZPL printers there is no problem. If you target EPL or both (EPL and ZPL), test it before going forward. On screen or file, the TrueType file matches the ZPL font, not the EPL one.
  • NativePrinterFontS
    • NativePrinterFontS.ttf has glyphs almost identical to the built-in fonts of ZPL, EPL and Fingerprint/Direct Protocol, and the printed outputs are almost identical too.

ZPL Font 0

"ZPL Font 0" is a scalable font shipped with every ZPL printer (Fingerprint/Direct Protocol printers have an equivalent built-in font with a different name). It is based on the CG Triumvirate Condensed Bold font. It improves printing performance and, unlike the NPF, supports multiline text and alignments.

As with the NPF, the SDK embeds a TrueType version of this font that is used only for PDF/image export and for the editor components. For printing, the SDK uses the ZPL or Fingerprint/Direct Protocol resident font.

Note

In EPL printers, a text using "ZPL Font 0" is rendered as graphics commands.

Note

In Fingerprint/Direct Protocol printers, "ZPL Font 0" is printed with the built-in font only when the text does not contain the - (hyphen) character. Otherwise the text is rendered as a graphic.

Installed Windows TTF fonts

Any TrueType font installed on the machine can be used in the Font property of TextItem and BarcodeItem objects. With these fonts you get all the rich text features: full Unicode support, RTL languages, text stretching, alignments, etc.

To check whether a font is installed, use FontManager.IsFontInstalled:

if (FontManager.IsFontInstalled("Arial"))
{
    txt.Font.Name = "Arial";
}
Note

Installed fonts must exist on the machine where the label is rendered (the machine running your application or web server), not necessarily on the machine of the end user.

Custom TTF font files (non-installed fonts)

The custom TTF approach has the same text features as installed fonts but does not require installing the font on the system. Deploy the TTF file with your application and set either the file path or the Base64 content of the TTF to Font.CustomFontFile. It is useful, for example, for dingbats fonts you don't want to install on every machine.

var txt = new TextItem(0.25, 0.25, 3.5, 0.5, "Hello");
txt.Font.Name = "Recycle It";
txt.Font.CustomFontFile = @"C:\MyApp\Fonts\RecycleIt.ttf";   // a path, or the Base64 content of the file
txt.Font.Size = 24;

FontManager for custom TTF font files

The FontManager class registers custom TTF fonts in the SDK's internal font cache, so they are available everywhere from the beginning of your project lifecycle and you don't need to set CustomFontFile on every item. It is also useful to deal with font families such as Arial, which has other flavors like Narrow or Black. Register the fonts once, in the startup code of your application.

Method Description
Add(Font font) Adds a font whose CustomFontFile is a file path or Base64 content.
AddFromFile(string fontFilePath, string fontName = "") Adds a font from a TTF file.
AddFromBase64(string fontFileBase64, string fontName = "") Adds a font from the Base64 content of a TTF.
AddFromBuffer(byte[] fontFileBuffer, string fontName = "") Adds a font from the binary content of a TTF.
IsFontInstalled(string fontName) Returns whether a font is installed on the machine.

For all other members see the API Reference.

The following code adds the Arial Black and Arial Narrow families.

VB.NET

' Adding Arial Black
Dim arialBlack As New Neodynamic.SDK.Printing.Font()
arialBlack.Name = "Arial Black"
arialBlack.CustomFontFile = "C:\Windows\Fonts\ariblk.ttf"
FontManager.Add(arialBlack)

' Adding Arial Narrow
Dim arialNarrow As New Neodynamic.SDK.Printing.Font()
arialNarrow.Name = "Arial Narrow"
arialNarrow.CustomFontFile = "C:\Windows\Fonts\ARIALN.TTF"
FontManager.Add(arialNarrow)

' Adding Arial Narrow Bold
Dim arialNarrowBold As New Neodynamic.SDK.Printing.Font()
arialNarrowBold.Name = "Arial Narrow"
arialNarrowBold.CustomFontFile = "C:\Windows\Fonts\ARIALNB.TTF"
arialNarrowBold.Bold = True
FontManager.Add(arialNarrowBold)

C#

// Adding Arial Black
FontManager.Add(new Neodynamic.SDK.Printing.Font()
{
    Name = "Arial Black",
    CustomFontFile = @"C:\Windows\Fonts\ariblk.ttf"
});

// Adding Arial Narrow
FontManager.Add(new Neodynamic.SDK.Printing.Font()
{
    Name = "Arial Narrow",
    CustomFontFile = @"C:\Windows\Fonts\ARIALN.TTF"
});

// Adding Arial Narrow Bold
FontManager.Add(new Neodynamic.SDK.Printing.Font()
{
    Name = "Arial Narrow",
    CustomFontFile = @"C:\Windows\Fonts\ARIALNB.TTF",
    Bold = true
});

Once registered, use the font by name:

txt.Font.Name = "Arial Narrow";
txt.Font.Bold = true;

TTF optimization on ZPL and Fingerprint printers

By default, a text item that uses a TTF font (installed or custom) is converted to graphics commands at rendering time. If you target ZPL or Fingerprint/Direct Protocol printers you can instead upload the TTF to the printer's internal storage, assigning it a short name. The text is then printed as text commands, which is faster and produces smaller print jobs, especially with large amounts of text.

Note

This feature is available for ZPL and Fingerprint/Direct Protocol only. The printer name must be short: for ZPL it is a drive letter followed by up to 8 alphanumeric chars, e.g. B:ARIAL.

The steps are:

  1. Get the printer commands that upload the TTF with PrintJob.GetTrueTypeFontPrinterCommands(...) and send them to the printer once.
  2. In the TextItem, set Font.Name to the TTF font and Font.NameAtPrinterStorage to the short name used in the upload.
// 1. Commands that upload the TTF to the printer storage (ZPL)
//    There is also an overload that takes the binary content of the TTF (byte[]).
var uploadCmds = PrintJob.GetTrueTypeFontPrinterCommands(
    @"C:\Windows\Fonts\arial.ttf", "B:ARIAL", ProgrammingLanguage.ZPL);

// 2. Use the uploaded font
var txt = new TextItem(0.25, 0.25, 3.5, 0.5, "Printed with the font stored in the printer");
txt.Font.Name = "Arial";
txt.Font.NameAtPrinterStorage = "B:ARIAL";

The Visual Label Editor sample application uses this feature.

Built-in printer fonts

Each printer language comes with a set of built-in fonts. Depending on the language you target, the SDK can take advantage of the following ones:

  • ZPL: ZPL Font 0 (based on CG Triumvirate Condensed Bold) and Swiss 721 BT.
  • Fingerprint/Direct Protocol: ZPL Font 0, Swiss 721 BT, Andale Mono, CG Times, Century Schoolbook BT, Dutch 801 Roman BT, Futura Light BT and Monospace 821 BT.
  • EPL: no additional built-in fonts other than the Native Printer Fonts.

The SDK also ships OCR A and OCR B as reserved fonts. Reserved fonts are always available and never embedded in a label file.

Font names are matched ignoring spaces (e.g. Swiss 721 BT and Swiss721BT).