3breadt.BinaryKits.Zpl.Label 3.3.0-preview

3breadt.BinaryKits.Zpl

Forked version of BinaryKits.Zpl with updated dependencies.

This project contains several modules for working with Zebra Programming Language. ZPL is a very common printer language that is supported by various manufacturers. The project helps you to describe a label and generates a preview from the ZPL data. We can convert different image formats to the Zebra image format. The image data is compressed to cause as little traffic as possible. More information about Zebra printer languages can be found in the ZPL Documentation.

What modules does the project offer

• BinaryKits.Zpl.Label

  This module provides the basic building blocks of the ZPL language and the logic for converting the images into the correct format.

• BinaryKits.Zpl.Labelary

  This module is a client for the Labelary project with which a preview can be generated from ZPL data.

• BinaryKits.Zpl.Protocol

  This module contains the raw commands of the Zebra protocol.

• BinaryKits.Zpl.Viewer

  This module is our own implementation of a viewer. It converts the ZPL data into an image like Labelary but does it locally. Try our viewer. The viewer is also available as a docker container

How can I use it?

The packages are available via:

Package Manager	.NET CLI
PM> install-package 3breadt.BinaryKits.Zpl.Label	> dotnet add package 3breadt.BinaryKits.Zpl.Label
PM> install-package 3breadt.BinaryKits.Zpl.Labelary	> dotnet add package 3breadt.BinaryKits.Zpl.Labelary
PM> install-package 3breadt.BinaryKits.Zpl.Viewer	> dotnet add package 3breadt.BinaryKits.Zpl.Viewer
PM> install-package 3breadt.BinaryKits.Zpl.Protocol	> dotnet add package 3breadt.BinaryKits.Zpl.Protocol

Supported Elements

This library supports following elements:

Is there a way to generate a preview?

There are several ways to view the result from the ZPL data.

How can I send the generated data to my printer?

For example, the data can be transmitted to the printer IpAddress on port 9100.

var zplData = @"^XA^MMP^PW300^LS0^LT0^FT10,60^APN,30,30^FH\^FDSAMPLE TEXT^FS^XZ";
// Open connection
var tcpClient = new System.Net.Sockets.TcpClient();
tcpClient.Connect("10.10.5.85", 9100);

// Send Zpl data to printer
var writer = new System.IO.StreamWriter(tcpClient.GetStream());
writer.Write(zplData);
writer.Flush();

// Close Connection
writer.Close();
tcpClient.Close();

Examples to describe Labels

Using statement

using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

Single element

var output = new ZplGraphicBox(100, 100, 100, 100).ToZplString();
Console.WriteLine(output);

Barcode 128

var output = new ZplBarcode128("123ABC", 10, 50).ToZplString();
Console.WriteLine(output);

Whole label

var sampleText = "[_~^][LineBreak\n][The quick fox jumps over the lazy dog.]";
var font = new ZplFont(fontWidth: 50, fontHeight: 50);
var elements = new List<ZplElementBase>();
elements.Add(new ZplTextField(sampleText, 50, 100, font));
elements.Add(new ZplGraphicBox(400, 700, 100, 100, 5));
elements.Add(new ZplGraphicBox(450, 750, 100, 100, 50, LineColor.White));
elements.Add(new ZplGraphicCircle(400, 700, 100, 5));
elements.Add(new ZplGraphicDiagonalLine(400, 700, 100, 50, 5));
elements.Add(new ZplGraphicDiagonalLine(400, 700, 50, 100, 5));
elements.Add(new ZplGraphicSymbol(GraphicSymbolCharacter.Copyright, 600, 600, 50, 50));

// Add raw Zpl code
elements.Add(new ZplRaw("^FO200, 200^GB300, 200, 10 ^FS"));

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { AddEmptyLineBeforeElementStart = true });

Console.WriteLine(output);

Simple layout

var elements = new List<ZplElementBase>();

var origin = new ZplOrigin(100, 100);
for (int i = 0; i < 3; i++)
{
    for (int j = 0; j < 3; j++)
    {
        elements.Add(new ZplGraphicBox(origin.PositionX, origin.PositionY, 50, 50));
        origin = origin.Offset(0, 100);
    }
    origin = origin.Offset(100, -300);
}

var options = new ZplRenderOptions();
var output = new ZplEngine(elements).ToZplString(options);

Console.WriteLine(output);

Auto scale based on DPI

var elements = new List<ZplElementBase>();
elements.Add(new ZplGraphicBox(400, 700, 100, 100, 5));

var options = new ZplRenderOptions { SourcePrintDpi = 203, TargetPrintDpi = 300 };
var output = new ZplEngine(elements).ToZplString(options);

Console.WriteLine(output);

Render with comment for easy debugging

var elements = new List<ZplElementBase>();

var textField = new ZplTextField("AAA", 50, 100, ZplConstants.Font.Default);
textField.Comments.Add("An important field");
elements.Add(textField);

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { DisplayComments = true });

Console.WriteLine(output);

Different text field type

var sampleText = "[_~^][LineBreak\n][The quick fox jumps over the lazy dog.]";
var font = new ZplFont(fontWidth: 50, fontHeight: 50);

var elements = new List<ZplElementBase>();
// Special character is repalced with space
elements.Add(new ZplextField(sampleText, 10, 10, font, useHexadecimalIndicator: false));
// Special character is repalced Hex value using ^FH
elements.Add(new ZplTextField(sampleText, 10, 50, font, useHexadecimalIndicator: true));
// Only the first line is displayed
elements.Add(new ZplSingleLineFieldBlock(sampleText, 10, 150, 500, font));
// Max 2 lines, text exceeding the maximum number of lines overwrites the last line.
elements.Add(new ZplFieldBlock(sampleText, 10, 300, 400, font, 2));
// Multi - line text within a box region
elements.Add(new ZplTextBlock(sampleText, 10, 600, 400, 100, font));

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { AddEmptyLineBeforeElementStart = true });

Console.WriteLine(output);

Draw pictures

For the best image result, first convert your graphic to black and white. The library auto resize the image based on DPI.

You have 2 possibilities to transfer the graphic to the printer:

1. ZplDownloadObjects (Use ~DY and ^IM)

With this option, the image is sent to the printer in the original graphic format and the printer converts the graphic to a black and white graphic

var elements = new List<ZplElementBase>();
elements.Add(new ZplDownloadObjects('R', "SAMPLE.BMP", System.IO.File.ReadAllBytes("sample.bmp")));
elements.Add(new ZplImageMove(100, 100, 'R', "SAMPLE", "BMP"));

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { AddEmptyLineBeforeElementStart = true, TargetPrintDpi = 300, SourcePrintDpi = 200 });

Console.WriteLine(output);

2. ZplDownloadGraphics (Use ~DG and ^XG)

With this option, the image is converted from the library into a black and white graphic and the printer already receives the finished print data

var elements = new List<ZplElementBase>();
elements.Add(new ZplDownloadGraphics('R', "SAMPLE", System.IO.File.ReadAllBytes("sample.bmp")));
elements.Add(new ZplRecallGraphic(100, 100, 'R', "SAMPLE"));

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { AddEmptyLineBeforeElementStart = true, TargetPrintDpi = 600, SourcePrintDpi = 200 });

Console.WriteLine(output);

Example to use the Viewer

IPrinterStorage printerStorage = new PrinterStorage();
var drawer = new ZplElementDrawer(printerStorage);

var analyzer = new ZplAnalyzer(printerStorage);
var analyzeInfo = analyzer.Analyze("^XA^FT100,100^A0N,67,0^FDTestLabel^FS^XZ");

foreach (var labelInfo in analyzeInfo.LabelInfos)
{
    var imageData = drawer.Draw(labelInfo.ZplElements);
    File.WriteAllBytes("label.png", imageData);
}

Font mapping

ZPL font download commands are not supported. You can provide a font mapping logic to the viewer if:

• You are hosting or using the BinaryKits.Zpl.Viewer
• The font is properly installed on the system

using SkiaSharp;

string zplString = @"^XA^FO20, 20^A1N,40, 30 ^FD西瓜^FS^FO20, 50^A0N,40, 30 ^FDABCDEFG^FS^XZ";

var drawOptions = new DrawerOptions()
{
    FontLoader = fontName =>
    {
        if (fontName == "0")
        {
            return SKTypeface.FromFamilyName("Arial", SKFontStyleWeight.Bold, SKFontStyleWidth.Normal, SKFontStyleSlant.Upright);
        }
        else if (fontName == "1")
        {
            return SKTypeface.FromFamilyName("SIMSUN");
        }

        return SKTypeface.Default;
    }
};

IPrinterStorage printerStorage = new PrinterStorage();
var drawer = new ZplElementDrawer(printerStorage, drawOptions);
var analyzer = new ZplAnalyzer(printerStorage);
var analyzeInfo = analyzer.Analyze(zplString);

foreach (var labelInfo in analyzeInfo.LabelInfos)
{
    var imageData = drawer.Draw(labelInfo.ZplElements, 300, 300, 8);
    File.WriteAllBytes("test.png", imageData);
}

Printer manufacturers that support zpl

Alternative projects