ThermalLabel Basics

Programming Object Model

ThermalLabel SDK features the Programming Object Model which can be summarized in the following diagram:

The ThermalLabel object

The ThermalLabel object represents the label's rectangular area intended for placing items like texts, barcodes, images, graphics, pictures, and shapes. You can create as many items as you want to print on the label. Items are simple objects which are assembled together to design and create the output thermal label. All items are printed in the order that each of them has in the stack of items (which is the Items collection property of the ThemalLabel object) and in the location specified for each item through their X and Y properties. There are five main kinds of items which can be placed on the label: TextItem, BarcodeItem, ImageItem, RFIDTagItem, and ShapeItem (Lines, Rectangles, Circles, etc.)

Single Roll Labels

To design a label, the first thing to set up is the unit of measurement (inch, cm, mm, dots, point, or pica) through the UnitType property which will be used for sizing as well as items location purposes. After unit of measurement is set up, then you simply specify the label's size (Width & Height properties) and the separation (GapLength, MarkLength, or OffsetLength property) between labels on the same roll media.

Pre-printed Labels

For pre-printed labels or labels with designs that are not rectangular shape, ThermalLabel object allows you to specify a non-printable background image to assist your end users to design the label content by filling the available blank zones when using the visual label designers. This image template is specified through the DesignBackgroundImage property and must be a PNG image in Base64 format.

Multi-column Roll Labels

ThermalLabel object also supports multi-column roll labels i.e. the roll media contains more than one label per "row". In this case, the ThermalLabel object must be configured with the label size (Width & Height properties) of each individual label, the number of labels per row on the roll (LabelsPerRow property), the horizontal gap separation between labels (LabelsHorizontalGapLength property) and the vertical separation (GapLength, MarkLength, or OffsetLength property) between the rows of labels.

Multi-page Labels

ThermalLabel object also supports the pages concept, where a set of consecutive (horizontal, vertical or both) labels should be considered as a single multi-page label. Each page must be added to the Pages collection property of the ThermalLabel object by specifying the page location (X & Y properties) and size (Width & Height properties). Now, the ThermalLabel size (Width & Height properties) must be set differently depending on whether the labels are horizontally and/or vertically distributed:

• Horizontal Multi-page Labels

In this case, the ThermalLabel object must be configured with the label size (Width & Height properties) as shown in the following picture i.e. the Width of the ThermalLabel object would be the sum of both pages width plus the horizontal gap.

• Vertical Multi-page Labels

In this case, the ThermalLabel object must be configured with the label size (Width & Height properties) as shown in the following picture i.e. the Height of the ThermalLabel object would be the sum of both pages height plus the vertical gap.

Note

In any case, the pages definition is just a way to show to the end users where to design and add the label items through the different visual label designers.

Sheet Labels

ThermalLabel object also supports Sheet Labels layout (like Avery and other brands). In this case, the ThermalLabel object must be configured with the label size (Width & Height properties) of each individual label, the number of labels per row on the roll (LabelsPerRow property), the horizontal gap separation between labels (LabelsHorizontalGapLength property), the vertical separation (GapLength property) between labels, and the sheet general setting (SheetLabelsWidth, SheetLabelsHeght, SheetLabelsCount, and SheetLabelsMargin properties).

PrintJob, WindowsPrintJob & WebPrintJob

PrintJob

The PrintJob is the object that specifies information about how the ThermalLabel object is converted to raw printer commands, including settings like label orientation and number of copies. It is also used for exporting or saving a ThermalLabel object to raster image formats or Adobe PDF documents which is very useful when you are in development/test phase or have no access to a physical thermal printer.

WindowsPrintJob

The WindowsPrintJob (which is found in the Neodynamic.SDK.ThermalLabel.WindowsPrinting.dll) is the object that specifies information about how the ThermalLabel object is printed, including the printer device settings and communication, label orientation, number of copies, etc. in a Windows client app project.

WebPrintJob

The WebPrintJob (which is found in the Neodynamic.SDK.ThermalLabel.WebPrinting.dll) is the object that specifies information about how the ThermalLabel object is printed, including the printer device settings and communication, label orientation, number of copies, etc. in an ASP.NET project.

Designing a Basic Label

In this section you'll learn how to design a simple label with a text and a barcode items. In this sample, the physical label size is 4 inch wide and 3 inch high. On that label, we'll place a TextItem displaying "Thermal Label Test" string and a BarcodeItem encoding the "ABC 12345" string in Code 128 Symbology. The label to design will look like the following:

The following is the VB.NET and C# codes for generating that basic label. You should create a .NET project like a Windows Forms App and use the code below to print the label. You must have a Thermal Printer connected to your machine and a Windows Driver installed on your system or you can save the the label output to a raster image format or Adobe PDF. Notice that the printing process is launched by a WindowsPrintJob object.

VB

'Define a ThermalLabel object and set unit to inch and label size
Dim tLabel As New ThermalLabel(UnitType.Inch, 4, 3)
tLabel.GapLength = 0.2
'Define a TextItem object
Dim txtItem As New TextItem(0.2, 0.2, 2.5, 0.5, "Thermal Label Test")
'Define a BarcodeItem object
Dim bcItem As New BarcodeItem(0.2, 1, 2, 1, BarcodeSymbology.Code128, "ABC 12345")
'Set bars height to .75inch
bcItem.BarHeight = 0.75
'Set bars width to 0.0104inch
bcItem.BarWidth = 0.0104
'Add items to ThermalLabel object...
tLabel.Items.Add(txtItem)
tLabel.Items.Add(bcItem)
'Create a WindowsPrintJob object
Using pj As New WindowsPrintJob()
    'Create PrinterSettings object
    Dim myPrinter As New PrinterSettings()
    myPrinter.Communication.CommunicationType = CommunicationType.USB
    myPrinter.Dpi = 203
    myPrinter.ProgrammingLanguage = ProgrammingLanguage.ZPL
    myPrinter.PrinterName = "Zebra  TLP2844-Z"

    'Set PrinterSettings to WindowsPrintJob
    pj.PrinterSettings = myPrinter
    'Print ThermalLabel object...
    pj.Print(tLabel)
End Using

CS

//Define a ThermalLabel object and set unit to inch and label size
ThermalLabel tLabel = new ThermalLabel(UnitType.Inch, 4, 3);
tLabel.GapLength = 0.2;

//Define a TextItem object
TextItem txtItem = new TextItem(0.2, 0.2, 2.5, 0.5, "Thermal Label Test");

//Define a BarcodeItem object
BarcodeItem bcItem = new BarcodeItem(0.2, 1, 2, 1, BarcodeSymbology.Code128, "ABC 12345");
//Set bars height to .75inch
bcItem.BarHeight = 0.75;
//Set bars width to 0.0104inch
bcItem.BarWidth = 0.0104;

//Add items to ThermalLabel object...
tLabel.Items.Add(txtItem);
tLabel.Items.Add(bcItem);

//Create a WindowsPrintJob object
using (WindowsPrintJob pj = new WindowsPrintJob())
{
    //Create PrinterSettings object
    PrinterSettings myPrinter = new PrinterSettings();
    myPrinter.Communication.CommunicationType = CommunicationType.USB;
    myPrinter.Dpi = 203;
    myPrinter.ProgrammingLanguage = ProgrammingLanguage.ZPL;
    myPrinter.PrinterName = "Zebra  TLP2844-Z";

    //Set PrinterSettings to WindowsPrintJob
    pj.PrinterSettings = myPrinter;
    //Print ThermalLabel object...
    pj.Print(tLabel);
}