Text Item

The TextItem Class

A TextItem – represented by Neodynamic.SDK.Printing.TextItem class – simply wraps a text string that must be drawn/printed on the label. TextItem objects are created by specifying some basic properties such as X, Y, Width, Height, Text, Font, etc.

TextItem objects feature the following capabilities: Data Binding, Masking and Counters, text Alignment and multi-line; Rotation, Text Sizing, Unicode support, RTL (Hebrew, Arabic, etc.), Custom and installed Windows TTF files, White text on black, rich Border settings, and basic rich text formatting (Bold, Italic and Underline).

After creating a TextItem object, it will printed on the label if you add it to the Items collection property of the ThermalLabel object.

Working with Fonts

In order to draw/print texts on a label you must specify Font settings on TextItem objects. The font to use with TextItem objects can be a Native Printer Font; any installed Windows Fonts on the client/target machine or a separated TTF font file which you can deploy with your application. The default font is NativePrinterFontA, 10pt. Please read more about Fonts...

Unicode and RTL text support

The TextItem object does support Unicode strings which means that you can set up the Text property of the TextItem object to any kind of characters (Note: to support Unicode characters, the Font you have set up for the TextItem must provide Unicode support too).

RTL

With TextItem objects you can also print text for RTL (Right to Left) languages like Arabic, Hebrew, etc. Again, it is mandatory that the Font you set up for the TextItem object does support such language characters.

Some RTL considerations:

If the Text property of the TextItem is set to a string that contains RTL chars only, then the RightToLeft property must be set to true in order to render the text with the correct text alignment.
If the Text property of the TextItem is set to a string that contains a single paragraph which contains LTR mixed with RTL chars, then the RightToLeft property must be set to false.
If the Text property of the TextItem is set to a string that contains multiple paragraphs, and one paragraph contains LTR chars only while other paragraph contains RTL chars only, then the RightToLeft property must be set to false and the RTL substring must be surrounded by the [rtl] ... [/rtl] markup.

Please refer to some samples at the end of this page.

Text Alignment

When you create a TextItem object, you are required to specify the area (X, Y, Width & Height) where the text must be allocated and printed. In that area, you can align the text to the left, right, center or justify it by setting up the TextAlignment property.

Sizing & "Effects"

By default, the text is printed with the size specified in the Font property. However, TextItem object allows you render text with different sizes and effects through the following Sizing property options:

Stretch: There're situations where you could require a text to fill its allocated area. For example, titles or legends that should be highlighted on the label like "IMPORTANT", "NOTICE", "WARNING", "CAUTION", "FRAGILE", etc; are good candidates for this purpose.
FontSizeScaling: Useful if you want the text always fit in the container size. The Font size is automatically reset and it applies for single line of text only.
ParagraphScaling: Same effect as FontSizeScaling option but applies for multi-line texts as well.
Arc: Text is rendered on an arc path inside the container size. This applies for single line of text only.
Vertical: Text is rendered vertically (like stacked chars) inside the container size. This applies for single line of text only.

Borders and White Text On Black

The TextItem object feature a rich Border settings allowing you to draw text inside a rectangular frame. The frame size is determined by the Width & Height properties of the TextItem and the stroke thickness is set up by using BorderThickness property. The frame can be set up so all corners be rounded or individually rounded i.e. maybe you want just the top corners be rounded and not the bottom ones. The corner roundness is set up by using CornerRadius property.

Another common design you found on thermal labels is known as White Text On Black. That's a text which foreground is White printed over a Black area. To get the "White Text On Black" effect, you must set up the ForeColor property to White and the BackColor to Black. That’s it! This could be easily combined with the Stretch sizing feature if you need to highlight it on the label.

Real Time Clock (RTC) support

By using a special formats within text items, you can print time & date values from the printer's Real Time Clock when available. The following is the list of formats for RTC that you can embed into the Text property and their values at printing time.

{yy} Use it for 2-digit year number
{yyyy} Use it for 4-digit year number
{M} Use it for abbreviated month name
{m} Use it for month number
{d} Use it for day number
{H} Use it for the hour of the day (military), 00 to 23
{h} Use it for the hour of the day (civilian), 01 to 12
{p} Use it for AM/PM designation
{min} Use it for minutes
{sec} Use it for seconds

Note

RTC is supported for ZPL and Fingerprint printers only. For EPL printers as wel as for PDF/Image outputs, date & time values are got from client OS when label is being generated.

Basic Rich Text Formatting

The TextItem object feature a basic set of markup for specifying rich text formatting combining Bold, Italic and Underline by using the [b]...[/b], [i]...[/i], and [u]...[/u] tags respectively.

Important

If using these rich text format tags, the output printer commands will be generated in graphics format affecting printing performance. Use it cautiously.

Input Mask Patterns support for Visual Label Editors Add-on

TextItem objects can be configured to force end-users to enter the text based on some mask pattern when using the visual label editors.

The Input Mask Pattern is specified to the InputMaskPattern property and it must be a string composed of one or more of the following masking elements:

Masking Element	Description
0	Digit, required. This element will accept any single digit between 0 and 9.
9	Digit or space, optional.
#	Digit or space, optional. If this position is blank in the mask, it will be rendered as a space in the `Text` property. Plus (+) and minus (-) signs are allowed.
L	Letter, required. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z] in regular expressions.
?	Letter, optional. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to [a-zA-Z]? in regular expressions.
&	Character, required.
C	Character, optional. Any non-control character.
A	Alphanumeric, required.
a	Alphanumeric, optional.
.	Decimal placeholder.
,	Thousands placeholder.
:	Time separator.
/	Date separator.
$	Currency symbol.
<	Shift down. Converts all characters that follow to lowercase.
>	Shift up. Converts all characters that follow to uppercase.
\|	Disable a previous shift up or shift down.
\	Escape. Escapes a mask character, turning it into a literal. "\" is the escape sequence for a backslash.
All other characters	Literals. All non-mask elements will appear as themselves within TextItem. Literals always occupy a static position in the mask at design time, and cannot be moved or deleted by the end user.

TextItem Samples

The following code creates a couple of TextItem objects using the Native Printer Fonts (NPF). Please read more about Fonts...

TextItem objects using the Native Printer Fonts (NPF)

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

'A sample text using NativePrinterFontA font            
Dim txt1 As New TextItem(0.25, 0.25, 3.5, 0.5, "Sample of NPF A - 012345")
txt1.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontA
txt1.Font.Unit = FontUnit.Point
txt1.Font.Size = 10

'A sample text using NativePrinterFontB font            
Dim txt2 As New TextItem(0.25, 0.75, 3.5, 0.5, "Sample of NPF B - 012345")
txt2.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontB
txt2.Font.Unit = FontUnit.Point
txt2.Font.Size = 14

'A sample text using NativePrinterFontB font
Dim txt3 As New TextItem(0.25, 1.5, 3.5, 0.25, "THIS IS A VERY SMALL TEXT USING NPF S")
txt3.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontS

'Add items to ThermalLabel object...
tLabel.Items.Add(txt1)
tLabel.Items.Add(txt2)
tLabel.Items.Add(txt3)

'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;

//A sample text using NativePrinterFontA font            
TextItem txt1 = new TextItem(0.25, 0.25, 3.5, 0.5, "Sample of NPF A - 012345");
txt1.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontA;
txt1.Font.Unit = FontUnit.Point;
txt1.Font.Size = 10;

//A sample text using NativePrinterFontB font            
TextItem txt2 = new TextItem(0.25, 0.75, 3.5, 0.5, "Sample of NPF B - 012345");
txt2.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontB;
txt2.Font.Unit = FontUnit.Point;
txt2.Font.Size = 14;

//A sample text using NativePrinterFontB font
TextItem txt3 = new TextItem(0.25, 1.5, 3.5, 0.25, "THIS IS A VERY SMALL TEXT USING NPF S");
txt3.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontS;

//Add items to ThermalLabel object...
tLabel.Items.Add(txt1);
tLabel.Items.Add(txt2);
tLabel.Items.Add(txt3);

//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);
}

The following code creates a couple of TextItem objects with most of the features briefly described above.

TextItem objects

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

'Hello World in Chinese            
Dim txt1 As New TextItem(0.25, 0.25, 1, 0.5, "世界您好")
txt1.Font.Name = "Arial"
txt1.Font.Unit = FontUnit.Point
txt1.Font.Size = 18

'Hello World in Arabic (RTL)
Dim txt2 As New TextItem(2, 0.25, 1.5, 0.5, "مرحبا العالمي")
txt2.Font.Name = "Arial"
txt2.Font.Unit = FontUnit.Point
txt2.Font.Size = 18
txt2.RightToLeft = True

'Stretched text with White On Black effect
Dim txt3 As New TextItem(0.25, 0.75, 3, 0.75, "WHITE TEXT")
txt3.Font.Name = "Arial"
txt3.Sizing = TextSizing.Stretch
txt3.BackColor = Neodynamic.SDK.Printing.Color.Black
txt3.ForeColor = Neodynamic.SDK.Printing.Color.White
txt3.TextPadding = New FrameThickness(0.2)

'Multiline text with center alignment
Dim txt4 As New TextItem(0.25, 2, 3, 0.75, "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.")
txt4.Font.Name = "Arial"
txt4.Font.Unit = FontUnit.Point
txt4.Font.Size = 8
txt4.Font.Bold = True
txt4.TextAlignment = TextAlignment.Center
txt4.BorderThickness = New FrameThickness(0.02)

'Add items to ThermalLabel object...
tLabel.Items.Add(txt1)
tLabel.Items.Add(txt2)
tLabel.Items.Add(txt3)
tLabel.Items.Add(txt4)

'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;

//Hello World in Chinese            
TextItem txt1 = new TextItem(0.25, 0.25, 1, 0.5, "世界您好");
txt1.Font.Name = "Arial";
txt1.Font.Unit = FontUnit.Point;
txt1.Font.Size = 18;

//Hello World in Arabic (RTL)
TextItem txt2 = new TextItem(2, 0.25, 1.5, 0.5, "مرحبا العالمي");
txt2.Font.Name = "Arial";
txt2.Font.Unit = FontUnit.Point;
txt2.Font.Size = 18;
txt2.RightToLeft = true;

//Stretched text with White On Black effect
TextItem txt3 = new TextItem(0.25, 0.75, 3, 0.75, "WHITE TEXT");
txt3.Font.Name = "Arial";
txt3.Sizing = TextSizing.Stretch;
txt3.BackColor = Neodynamic.SDK.Printing.Color.Black;
txt3.ForeColor = Neodynamic.SDK.Printing.Color.White;
txt3.TextPadding = new FrameThickness(0.2);

//Multiline text with center alignment
TextItem txt4 = new TextItem(0.25, 2, 3, 0.75, "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.");
txt4.Font.Name = "Arial";
txt4.Font.Unit = FontUnit.Point;
txt4.Font.Size = 8;
txt4.Font.Bold = true;
txt4.TextAlignment = TextAlignment.Center;
txt4.BorderThickness = new FrameThickness(0.02);

//Add items to ThermalLabel object...
tLabel.Items.Add(txt1);
tLabel.Items.Add(txt2);
tLabel.Items.Add(txt3);
tLabel.Items.Add(txt4);

//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);
}

The following code creates a TextItem mixing LTR and RTL paragraphs by using the [rtl]...[/rtl] markup.

TextItem objects

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

'LTR and RTL paragraphs inside a single TextItem  
Dim ltrPara As String = "We are closely monitoring the situation during the COVID-19 outbreak, follow this link for the latest service updates. Stay Safe!"
Dim rtlPara As String = "[rtl]!نتابع في أرامكس عن كثب التطورات المتعلقة بفيروس كورونا المستجد (كوفيد ١٩)، يمكنكم من خلال هذا الرابط متابعة آخر تحديثات الخدمة. نتمنى لكم السلامة[/rtl]"

Dim text As String = ltrPara + Environment.NewLine + rtlPara

Dim txt1 As New TextItem(0.25, 0.25, 3, 2.5, text)
txt1.Font.Name = "Arial"
txt1.Font.Unit = FontUnit.Point
txt1.Font.Size = 12

'Add items to ThermalLabel object...
tLabel.Items.Add(txt1)

'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;

//LTR and RTL paragraphs inside a single TextItem  
string ltrPara = "We are closely monitoring the situation during the COVID-19 outbreak, follow this link for the latest service updates. Stay Safe!";
string rtlPara = "[rtl]!نتابع في أرامكس عن كثب التطورات المتعلقة بفيروس كورونا المستجد (كوفيد ١٩)، يمكنكم من خلال هذا الرابط متابعة آخر تحديثات الخدمة. نتمنى لكم السلامة[/rtl]";

string text = ltrPara + Environment.NewLine + rtlPara;        
TextItem txt1 = new TextItem(0.25, 0.25, 3, 2.5, text);
txt1.Font.Name = "Arial";
txt1.Font.Unit = FontUnit.Point;
txt1.Font.Size = 12;

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

//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);
}

The following sample uses a custom *.ttf font file. The following code uses a "dingbat" type font called RecycleIt Font which features a lot of recycling symbols.

Note

The RecycleIt font is used here for demo purpose only. Please read the license agreement of the fonts you will use in your apps before using them.

Custom Font File

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

'A sample text using NativePrinterFontA font            
Dim txt1 As New TextItem(0.25, 0.25, 3.5, 0.5, "Using Custom Font Files")
txt1.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontA
txt1.Font.Unit = FontUnit.Point
txt1.Font.Size = 10

'A sample text using a custom ttf font file            
Dim txt2 As New TextItem(0.25, 0.75, 3.5, 0.5, "M 8 S Z I")
txt2.Font.CustomFontFile = "C:\Temp\CustomFonts\RecycleIt.ttf"
txt2.Font.Unit = FontUnit.Point
txt2.Font.Size = 24

'Add items to ThermalLabel object...
tLabel.Items.Add(txt1)
tLabel.Items.Add(txt2)

'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;

//A sample text using NativePrinterFontA font            
TextItem txt1 = new TextItem(0.25, 0.25, 3.5, 0.5, "Using Custom Font Files");
txt1.Font.Name = Neodynamic.SDK.Printing.Font.NativePrinterFontA;
txt1.Font.Unit = FontUnit.Point;
txt1.Font.Size = 10;

//A sample text using a custom ttf font file            
TextItem txt2 = new TextItem(0.25, 0.75, 3.5, 0.5, "M 8 S Z I");
txt2.Font.CustomFontFile = @"C:\Temp\CustomFonts\RecycleIt.ttf";
txt2.Font.Unit = FontUnit.Point;
txt2.Font.Size = 24;

//Add items to ThermalLabel object...
tLabel.Items.Add(txt1);
tLabel.Items.Add(txt2);

//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);
}