ThermalLabel SDK: Why Is My ZPL Full of ^GFA? Native Commands vs. Graphic Mode
A question we often get from ThermalLabel SDK for .NET users: "I printed to my ZPL printer and the output is all ^GFA commands. Can I get plain ZPL instead?" In most cases, yes. This post explains why it happens and what you can change. All the details are in the new help topic Native Commands vs. Graphic Mode.
Two ways to print an item
When the SDK generates printer commands, it decides item by item how to send each one to the printer:
- Native mode. The item uses the printer language's own commands: resident fonts, boxes, lines, ellipses and barcode commands. The output is small, readable and fast to print.
- Graphic mode. The SDK renders the item as a monochrome bitmap and sends it as an image (
^GFAin ZPL,GWin EPL,PRBUFin Fingerprint). What prints matches the on-screen preview pixel for pixel, but the output is larger.
The SDK uses native mode whenever the printer can reproduce the item exactly. When the item uses a feature the printer can't draw on its own, the SDK switches it to graphic mode so the label still matches your design.
See the commands the SDK generates
Call PrintJob.GetNativePrinterCommands() to get the raw commands as a string without sending anything to the printer:
var pj = new PrintJob();
pj.ProgrammingLanguage = ProgrammingLanguage.ZPL;
pj.Dpi = 203;
pj.ThermalLabel = myLabel;
string zpl = pj.GetNativePrinterCommands();
System.IO.File.WriteAllText("label.zpl", zpl);
Use GetBinaryNativePrinterCommands() if you need a byte[] instead.
The most common reasons an item becomes a graphic
- TrueType fonts. Text in Arial, Calibri or any other TrueType font is always a graphic, because the printer doesn't have that font. For native ZPL text, use
NativePrinterFontA,NativePrinterFontBorNativePrinterFontS,ZPL Font 0orSwiss 721, or a font already stored on the printer throughFont.NameAtPrinterStorage. - Text effects. Rich text (BBCode, HTML or RTF), any
Sizingother thanNone, middle vertical alignment, scaling, stroke, character spacing, right-to-left text and rounded corners all force graphic mode. - Barcode settings. Examples include a human-readable font that isn't a
NativePrinterFont, artistic (Art*) settings, an extraTextcaption and rounded corners. - Shapes. Shapes with dashed or dotted strokes, rounded corners, or a rotation that isn't a multiple of 90° become graphics. In ZPL and EPL, diagonal lines do too.
PrintAsGraphic = trueorUseCache = trueon any item.- Images are always graphics. The exception is an
ImageItemwithNameAtPrinterStorageset, which only recalls a graphic already stored on the printer.
Note also that ESC/POS and PCL always send the whole label as a single image.
A note on resident barcodes
In ZPL, you can set BarcodeItem.PrintAsResidentElement = true to print barcodes with the printer's own commands (^BC, ^BQ, ^BX, ...). The printer firmware then encodes the symbol with its own encoder. As a result, a QR Code, a Data Matrix or a GS1-128 barcode may look different from the preview or from the exported image, PDF or HTML, although it decodes to exactly the same data. If you need the printed label to match the preview exactly, keep the default mode. By default, the SDK encodes the symbol itself and draws it with native ^GB boxes.
Printers that emulate ZPL
Many non-Zebra printers emulate ZPL. If a label prints correctly on a Zebra printer but not on an emulating one, check the following:
- Size of the
^GFAdata. The SDK sends^GFAdata uncompressed, so jobs with many graphic items can be large. Reducing the number of graphic items usually helps. - The
Swiss 721font.Swiss 721maps to Zebra's resident font fileTT0003M_, which may not exist on other brands. - Supported commands. Compare the output of
GetNativePrinterCommands()against the list of commands your printer vendor says the emulation supports.
More information
- Full help topic: Native Commands vs. Graphic Mode
- Quick Start and API reference: ThermalLabel SDK for .NET
Product page & Quick Start
| Tweet |
|