ZPLRenderer: Difference between revisions

From Commander4j
← Older edit
No edit summary
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
ZPL Renderer is a program intended to show you on screen what ZPL would look like if printed on a physical zebra printer. You can read ZPL commands from a text file or you can get the program to listen on a network port and send data to it over a network connection. If you can send a print stream over the network you can see the output on screen as a virtual printer. Not all ZPL commands are supported at this stage but more will be added.
ZPL Renderer is a desktop application that interprets ZPL (Zebra Programming Language) commands and renders them as a visual preview of what a label will look like when printed on a physical Zebra printer. It is a companion tool to Commander4j, LabelServer4j, and AutoLab4j.


[[File:ZPLRenderer1.png|link=|border|800px]]
== Purpose ==


The image above shows a pallet label (a5) being previewed on screen. The red border around the label shows the edge of the label/paper. You can zoom in and out and preview multiple labels.
ZPL is a text-based command language used to define label layouts, text, graphics, and barcodes for Zebra label printers. The commands are sent directly to the printer as a stream of characters and are not human-readable. ZPL Renderer allows you to:


[[File:ZPLRenderer2.png|link=|border|800px]]
* Load a ZPL file and see what the label will look like before sending it to a printer
* Listen on a network socket so that any application sending ZPL to that port renders the label on screen in real time
* Zoom in and out to examine label detail
* Preview multiple labels from a single ZPL stream
* Export the rendered label to PDF
* Print the rendered label directly from the application


Real physical Zebra printers have a combination of built in fonts and the ability to have alternative font uploaded to them. To provide an extra degree of compatibility the program allows you to define your own fonts as shown here.
[[File:ZPLRenderer.jpg|800px]]
 
== Running ZPL Renderer ==
 
Native install packages for Windows, macOS, and Linux are available from the [[Downloads]] page and are the preferred installation method.
 
Alternatively, ZPL Renderer can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application:
 
java -jar zplrenderer.jar
 
On first launch it reads its configuration from <code>xml/config/config.xml</code>.
 
== Loading a ZPL File ==
 
Use the '''Open''' toolbar button to load a <code>.zpl</code> text file from disk. The label is rendered immediately. Use '''Refresh''' to reload the file after editing it externally.
 
Several example ZPL files are included in the <code>examples/</code> directory:
 
{| class="wikitable"
|-
! File !! Contents
|-
| example1.zpl || Shipping label with QR code, text, and graphics
|-
| example2.zpl || Complex layout with boxes, barcodes, and logo
|-
| barcodes.zpl || Showcase of all supported barcode types
|-
| pallet_labels.zpl || Pallet label examples typical of Commander4j output
|-
| fonts.zpl || Font size and style demonstration
|-
| shipping.zpl || Shipping label sample
|-
| character.zpl || Character set reference
|-
| grid.zpl || Layout grid for alignment reference
|}
 
== Network Socket Mode ==
 
ZPL Renderer can listen on a TCP/IP port and render any ZPL label stream sent to it. This allows Commander4j, LabelServer4j, or any other application to use ZPL Renderer as a virtual printer — sending ZPL to the socket and seeing the result on screen instead of printing to paper.
 
The default port is '''9100''' (the standard Zebra raw print port). The IP address and port are configured in <code>config.xml</code>. Enable listening using the '''Network''' button in the toolbar.
 
ZPL Renderer extracts complete label blocks from the stream, identified by the standard <code>^XA</code> (start of label) and <code>^XZ</code> (end of label) delimiters.
 
== Zoom ==
 
Use the zoom controls in the toolbar to scale the rendered label between 0.10× and 2.00×. The default zoom is configured in <code>config.xml</code> (default: 0.5×). This is useful for examining barcode detail or checking overall label proportions.
 
== Multiple Labels ==
 
When a ZPL file or network stream contains multiple labels, ZPL Renderer displays them as pages. Navigation controls allow stepping through each label. The maximum number of pages displayed is configurable (default: 3).
 
== Export and Print ==
 
* '''PDF Export''' — saves the rendered label as a vector PDF using Apache PDFBox
* '''Print''' — sends the rendered label to a system printer
 
== Supported ZPL Commands ==
 
ZPL Renderer supports over 100 ZPL commands. Key categories:
 
=== Label Setup ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^XA || Start of label
|-
| ^XZ || End of label
|-
| ^LL || Label length
|-
| ^LH || Label home (origin offset)
|-
| ^LT || Label top offset
|-
| ^PQ || Print quantity
|-
| ^CD || Change delimiter character
|-
| ^CC || Change caret character
|}
 
=== Text and Fields ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^FO || Field origin (X,Y position from top-left)
|-
| ^FT || Field typeset (X,Y position from bottom-left)
|-
| ^FD || Field data (the text content)
|-
| ^FS || Field separator
|-
| ^FR || Field reverse (inverted colours)
|-
| ^FW || Field orientation/rotation
|-
| ^FX || Comment (ignored in output)
|}
 
=== Fonts ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^A0–^AZ || Select font by ID
|-
| ^CF || Change default alphanumeric font
|-
| ^CI || Change international character set/encoding
|}
 
=== Graphics ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^GB || Graphic box (rectangle)
|-
| ^GC || Graphic circle
|-
| ^GD || Graphic diagonal line
|-
| ^GE || Graphic ellipse
|-
| ^GF || Graphic field (embedded image data)
|-
| ^GS || Graphic symbol
|}
 
=== Barcodes ===
{| class="wikitable"
|-
! Command !! Description
|-
| ^BC || Code 128 / GS1-128 (EAN-128)
|-
| ^BE || EAN-13
|-
| ^B8 || EAN-8
|-
| ^B3 || Code 39
|-
| ^B2 || Interleaved 2 of 5
|-
| ^B1 || Code 11
|-
| ^BQ || QR Code
|-
| ^B7 || PDF417
|-
| ^B0 / ^BO || Aztec
|-
| ^BY || Bar code field defaults (width, ratio, height)
|}
 
Barcode rendering uses the OkapiBarcode library. GS1 application identifiers are interpreted from <code>xml/config/gs1_app_defs.xml</code>.
 
== Configuration ==
 
=== config.xml ===
 
Located at <code>xml/config/config.xml</code>:
 
{| class="wikitable"
|-
! Setting !! Description
|-
| Input folder || Default directory for ZPL file loading (default: <code>./examples</code>)
|-
| Port || Network socket port to listen on (default: 9100)
|-
| Default magnification || Starting zoom level (default: 0.5)
|-
| Max pages || Maximum number of label pages to display (default: 3)
|}
 
=== fonts.xml ===
 
Located at <code>xml/config/fonts.xml</code>, this file maps ZPL font IDs (0, A–Z) to TrueType font files and defines their pixel dimensions. This allows ZPL Renderer to simulate the fonts installed in a physical Zebra printer.
 
Included fonts: Bitstream Vera, Anonymous Pro, ATTriumvirate.
 
If your labels use fonts that differ from the defaults, edit <code>fonts.xml</code> to match the font metrics of your target printer.
 
== Relationship to Commander4j ==
 
Commander4j generates ZPL label streams for pallet and case labels. ZPL Renderer allows you to preview these labels before deploying them to production printers, and to verify that label templates produce the correct output after making changes to the template syntax. See [[Label Template Syntax]] and [[Zebra ZPL Label]] for information on ZPL label authoring within Commander4j.
 
See also: [[Zebra ZPL Label]], [[Label Template Syntax]], [[Printer Queues]], [[Production Lines & Labellers]]
 
[[Category:Commander4j]]

Latest revision as of 18:34, 24 April 2026

ZPL Renderer is a desktop application that interprets ZPL (Zebra Programming Language) commands and renders them as a visual preview of what a label will look like when printed on a physical Zebra printer. It is a companion tool to Commander4j, LabelServer4j, and AutoLab4j.

Purpose

ZPL is a text-based command language used to define label layouts, text, graphics, and barcodes for Zebra label printers. The commands are sent directly to the printer as a stream of characters and are not human-readable. ZPL Renderer allows you to:

  • Load a ZPL file and see what the label will look like before sending it to a printer
  • Listen on a network socket so that any application sending ZPL to that port renders the label on screen in real time
  • Zoom in and out to examine label detail
  • Preview multiple labels from a single ZPL stream
  • Export the rendered label to PDF
  • Print the rendered label directly from the application

Running ZPL Renderer

Native install packages for Windows, macOS, and Linux are available from the Downloads page and are the preferred installation method.

Alternatively, ZPL Renderer can be run directly from the distribution archive. It is a Java 21 desktop (Swing) application: 

java -jar zplrenderer.jar

On first launch it reads its configuration from xml/config/config.xml.

Loading a ZPL File

Use the Open toolbar button to load a .zpl text file from disk. The label is rendered immediately. Use Refresh to reload the file after editing it externally.

Several example ZPL files are included in the examples/ directory:

File Contents
example1.zpl Shipping label with QR code, text, and graphics
example2.zpl Complex layout with boxes, barcodes, and logo
barcodes.zpl Showcase of all supported barcode types
pallet_labels.zpl Pallet label examples typical of Commander4j output
fonts.zpl Font size and style demonstration
shipping.zpl Shipping label sample
character.zpl Character set reference
grid.zpl Layout grid for alignment reference

Network Socket Mode

ZPL Renderer can listen on a TCP/IP port and render any ZPL label stream sent to it. This allows Commander4j, LabelServer4j, or any other application to use ZPL Renderer as a virtual printer — sending ZPL to the socket and seeing the result on screen instead of printing to paper.

The default port is 9100 (the standard Zebra raw print port). The IP address and port are configured in config.xml. Enable listening using the Network button in the toolbar.

ZPL Renderer extracts complete label blocks from the stream, identified by the standard ^XA (start of label) and ^XZ (end of label) delimiters.

Zoom

Use the zoom controls in the toolbar to scale the rendered label between 0.10× and 2.00×. The default zoom is configured in config.xml (default: 0.5×). This is useful for examining barcode detail or checking overall label proportions.

Multiple Labels

When a ZPL file or network stream contains multiple labels, ZPL Renderer displays them as pages. Navigation controls allow stepping through each label. The maximum number of pages displayed is configurable (default: 3).

Export and Print

  • PDF Export — saves the rendered label as a vector PDF using Apache PDFBox
  • Print — sends the rendered label to a system printer

Supported ZPL Commands

ZPL Renderer supports over 100 ZPL commands. Key categories:

Label Setup

Command Description
^XA Start of label
^XZ End of label
^LL Label length
^LH Label home (origin offset)
^LT Label top offset
^PQ Print quantity
^CD Change delimiter character
^CC Change caret character

Text and Fields

Command Description
^FO Field origin (X,Y position from top-left)
^FT Field typeset (X,Y position from bottom-left)
^FD Field data (the text content)
^FS Field separator
^FR Field reverse (inverted colours)
^FW Field orientation/rotation
^FX Comment (ignored in output)

Fonts

Command Description
^A0–^AZ Select font by ID
^CF Change default alphanumeric font
^CI Change international character set/encoding

Graphics

Command Description
^GB Graphic box (rectangle)
^GC Graphic circle
^GD Graphic diagonal line
^GE Graphic ellipse
^GF Graphic field (embedded image data)
^GS Graphic symbol

Barcodes

Command Description
^BC Code 128 / GS1-128 (EAN-128)
^BE EAN-13
^B8 EAN-8
^B3 Code 39
^B2 Interleaved 2 of 5
^B1 Code 11
^BQ QR Code
^B7 PDF417
^B0 / ^BO Aztec
^BY Bar code field defaults (width, ratio, height)

Barcode rendering uses the OkapiBarcode library. GS1 application identifiers are interpreted from xml/config/gs1_app_defs.xml.

Configuration

config.xml

Located at xml/config/config.xml:

Setting Description
Input folder Default directory for ZPL file loading (default: ./examples)
Port Network socket port to listen on (default: 9100)
Default magnification Starting zoom level (default: 0.5)
Max pages Maximum number of label pages to display (default: 3)

fonts.xml

Located at xml/config/fonts.xml, this file maps ZPL font IDs (0, A–Z) to TrueType font files and defines their pixel dimensions. This allows ZPL Renderer to simulate the fonts installed in a physical Zebra printer.

Included fonts: Bitstream Vera, Anonymous Pro, ATTriumvirate.

If your labels use fonts that differ from the defaults, edit fonts.xml to match the font metrics of your target printer.

Relationship to Commander4j

Commander4j generates ZPL label streams for pallet and case labels. ZPL Renderer allows you to preview these labels before deploying them to production printers, and to verify that label templates produce the correct output after making changes to the template syntax. See Label Template Syntax and Zebra ZPL Label for information on ZPL label authoring within Commander4j.

See also: Zebra ZPL Label, Label Template Syntax, Printer Queues, Production Lines & Labellers

Retrieved from ‘https://wiki.commander4j.com/index.php?title=ZPLRenderer&oldid=1828’