Literal Item

The LiteralItem Class

A LiteralItem – represented by the Neodynamic.SDK.Printing.LiteralItem class – lets you send raw printer commands (ZPL, EPL, Fingerprint/Direct Protocol) inside a label. The text you set in its Text property is written, as is, into the command stream generated for the label. Use it for anything the SDK items do not cover: a printer setting, a native command, a feature that is specific to your printer model.

The LiteralItem has no visual representation: it has no Width/Height, its X and Y are not used to generate commands, and nothing is drawn for it. It does not appear when the label is exported to an image, PDF or HTML. It only produces printer commands.

Note

A LiteralItem generates commands for ZPL, EPL and Fingerprint/Direct Protocol printers. The SDK does not validate, translate or adapt the text. A ZPL literal sent to an EPL printer is sent as is, and the printer will not understand it. You are responsible for sending commands of the same language as PrinterSettings.ProgrammingLanguage.

Quick Start

ThermalLabel tLabel = new ThermalLabel(UnitType.Inch, 4, 3);

// A native ZPL command the SDK does not generate: ^LT (Label Top)
// moves the whole label 20 dots up
LiteralItem literal = new LiteralItem();
literal.Text = "^LT-20";

tLabel.Items.Add(literal);

Main Properties

Data

Property	Description
`Text`	The raw commands to send to the printer. Default is an empty string. Supports `Expression`.

The text is converted to bytes using UTF-8 and sent unchanged. If Text is empty (and the item is not data bound), the item generates nothing.

Inherited properties

The LiteralItem inherits the common properties of every item. Only some of them have an effect:

Property	Effect on a LiteralItem
`Visible`	When `false` the item is skipped and nothing is sent.
`DataField`	Takes the text from the data source instead of `Text`. See Data binding and expressions.
`Expression`	Builds the text at print time.
`Name`, `Comments`, `Tag`, `GroupName`	Informational. Not sent to the printer.
`Locked`, `Editable`, `Resizable`, `ReadOnly`	Design-time behavior. `ReadOnly = true` makes the `Text` setter ignore new values.
`X`, `Y`, `UnitType`, `Dpi`	Exist, but are not used to build the commands.
`CacheItemId`, `UseCache`, `PrintAsGraphic`	Not applicable: there is nothing to render. See Limitations.

How the text is sent

The bytes are the UTF-8 encoding of Text, exactly as written.
The label commands are built by concatenating the output of each item in the order of tLabel.Items.
- ZPL does not need line breaks; each command starts with ^ or ~. The text is sent exactly as written.
- EPL, Fingerprint and Direct Protocol are line oriented: every command must end with a line break. If your text does not end with one, the SDK appends it automatically (LF for EPL, CRLF for Fingerprint/Direct Protocol). If it already ends with a line break, nothing is added. Line breaks inside the text are never touched, so separate multiple commands with \n yourself.
The position in the stream follows the position in the Items collection. To run a command before the rest of the label content, add the LiteralItem first; to run it after, add it last.
The label header (size, speed, darkness, etc.) is always written before the items, and the printer job wraps the whole label (for example ^XA/^XZ in ZPL). Do not add those wrappers in your literal unless you know what you are doing.
UTF-8 is used regardless of the printer code page. Characters outside ASCII may not reach the printer as you expect. Prefer ASCII or the escape mechanism of the printer language (for example ^FH in ZPL).

Printing the samples

All samples below only change the label. Use the following code to print any of them:

VB.NET

'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 ZT410"

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

C#

//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 ZT410";

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

LiteralItem Samples

Example #1: Using a ZPL command the SDK does not support

The SDK has no property for ZPL's ^LT (Label Top) and ^LS (Label Shift) commands, which fine-tune the print position of the whole label. A LiteralItem sends them to the printer. Here the label is shifted 12 dots down and 8 dots to the left, and then a regular TextItem is drawn.

Add the LiteralItem first, so the settings are in the stream before the content they affect.

VB.NET

Dim tLabel As New ThermalLabel(UnitType.Inch, 4, 2)

' ZPL-only commands that have no SDK equivalent:
' ^LT = Label Top (12 dots down), ^LS = Label Shift (8 dots to the left)
Dim literal As New LiteralItem()
literal.Text = "^LT12^LS8"
tLabel.Items.Add(literal)

Dim txt As New TextItem(0.2, 0.2, 3, 0.4, "Regular SDK text")
tLabel.Items.Add(txt)

C#

ThermalLabel tLabel = new ThermalLabel(UnitType.Inch, 4, 2);

// ZPL-only commands that have no SDK equivalent:
// ^LT = Label Top (12 dots down), ^LS = Label Shift (8 dots to the left)
LiteralItem literal = new LiteralItem();
literal.Text = "^LT12^LS8";
tLabel.Items.Add(literal);

TextItem txt = new TextItem(0.2, 0.2, 3, 0.4, "Regular SDK text");
tLabel.Items.Add(txt);

Note

Both commands are specific to Zebra ZPL printers. Check the allowed ranges in the ZPL Programming Guide for your model.

Example #2: Several commands in one item

One LiteralItem can hold as many commands as you want. Using several items is only needed if you want to control the order relative to other items.

C#

// ^LT = Label Top, ^LS = Label Shift, ^CF = Change default alphanumeric font
LiteralItem literal = new LiteralItem();
literal.Text = "^LT12" +
               "^LS8" +
               "^CFA,30";
tLabel.Items.Add(literal);

Data binding and expressions

When DataField is not empty, the text of the literal comes from the data source (the value of the field replaces Text) for each label. Nothing else is applied: the value is sent unchanged, so the field must already contain valid commands.

LiteralItem literal = new LiteralItem();
literal.DataField = "zplSnippet";
tLabel.Items.Add(literal);

Expression is also supported. At print time the result of the expression is used as the text: if the item was already data bound its value is replaced; otherwise Text is replaced. This is useful to compose a command from other fields or variables, for example a ZPL ^FD value built from several data fields. See Expressions.

Warning

Data coming from users or external systems is sent to the printer as commands. Do not bind a LiteralItem to untrusted data: it can change printer settings or print unexpected content.

Limitations

No preview. The item is not drawn, so label exports to image, PDF or HTML do not show the effect of your commands. See Export Labels to Image.
Multipage and duplex labels. When a label is split into pages (multipage or duplex designs), LiteralItems are removed from the pages. Their commands are not sent in that case.
Printer-specific. Any command that moves, rotates or scales the print area is outside the SDK's control; the SDK does not adjust it for LabelsPerRow or print orientation.

Common mistakes

Wrong language. The literal must match the printer's programming language. The SDK will not check it.
Missing line break between commands in EPL/Fingerprint/Direct Protocol. Only the final one is added for you.
Adding ^XA/^XZ (ZPL) inside the literal. The job already wraps the label.
Expecting it in the preview. The item has no visual representation.
Using it in multipage/duplex labels. The item is removed from the pages.
Binding untrusted data. See the warning above.