Expressions

Overview

Expressions can include a combination of variables, constants, operators, functions, and references to label Items as well as to data fields in a data binding scenario. ThermalLabel supports Expressions at two different levels, Item Expressions & Global Expressions.

Item Expressions

The Expression is set to any Item in the label through the Expression property and is used to dynamically set the Item's content. The following are the Items that currently support expressions:

  • TextItem: any expression will be evaluated to set the Text property.
  • BarcodeItem: any expression will be evaluated to set the Code property.
  • ImageItem: any expression will be evaluated to set the SourceFile or SourceBase64 property.
  • RFIDTagItem: any expression will be evaluated to set the DataToEncode property.
  • LiteralItem: any expression will be evaluated to set the Text property.

Example: To set the current Date and Time in a TextItem, then set the Expression property to 

DateString() + " " + TimeString()
Note

Item Expressions are evaluated by ThermalLabel SDK at label rendering stage and it's the last step that will finally set the Item's content. So, in a Data Binding, Data Masking or Counter scenarios, they will be processed first and then Expressions will be evaluated as the last step in the label rendering process.

Global Expressions

In addition to Item Expressions, ThermalLabel also supports Global Expressions that allows advanced and dynamic changes on any Item properties based on the Expressions code evaluation. For example, this allows hidding Items, changing colors, fonts, location, size and most of the properties available on each Item type. The Global Expressions are specified to the Expressions collection property of the ThermalLabel object. It can contain N-Expressions code that will be evaluated in order.

Example: The following list of Global Expressions are present in one of the label samples shipped with the Visual Label Editor demo project and shows how to change or modify different items properties. Each line below represents a single entry in the Expressions collection property! 

Set [Items!SampleText.BackColorHex] = "#00ff00"
Set [Items!TempText.Visible] = CBool(IIf([Items!SampleText.BackColorHex]="#00ff00", "False", "True"))
Set [Items!BC.Code] = CStr(Now())
Set [Items!BC.Symbology] = BarcodeSymbology.DataMatrix
Set [Items!myRect.CornerRadius] = New RectangleCornerRadius(0.1)
Set [Items!Logo.X] = ((LABEL_WIDTH - [Items!Logo.Width]) / 2)

Each of those Expressions code does the following:

  1. Sets the BackColorHex property of a TextItem named SampleText to a new color value.
  2. Hides or Shows a TextItem named TempText based on the value of previous Item using a conditional Expression.
  3. Sets the barcode value to encode.
  4. Changes or sets the barcode type.
  5. Sets the CornerRadius of a RectangleShapeItem named myRect by using New Expression keyword.
  6. Centers an ImageItem named Logo by using the LABEL_WIDTH Expression variable.
Note

Global Expressions are evaluated by ThermalLabel SDK at label rendering stage and it's the last step that will finally set any Items properties (if any) even after Item Expressions.

Expression References

  • Referencing an Item: To reference the content of a given Item, that Item must be assigned with a unique Name and then the following expression must be used: [Items!Item_Name] e.g. if an Item Name is ProductID, then that item content expression would be [Items!ProductID]
  • Referencing a Data Field: To reference the content of a data field, the following expression must be used: [DataFields!DataField_Name] e.g. if a data field name is ProductDescription, then that data field expression would be [DataFields!ProductDescription]
  • Referencing Operators, Variables/Constants and Functions: To reference any supported operator and function, just specify the correct syntax for them. 100+ built-in functions are provided by default based on the popular VBA syntax. You can also add Custom Functions, Types and Variables/Constants through ExpressionBuilder class.

ExpressionEngine Class

The ExpressionEngine class allows you to get the list of built-in Expressions as well as the ability of adding and setting Custom Functions, Types and Variables/Constants.

The list is available in the ExpressionEngine class through the SupportedExpressions property which returns a 5-tuple object where the first component represents the Expression Category, the second component represents the Expression Name, the third component represents the Expression Syntax, the fourth component represents the Expression Description, and the last component represents Expression Example.

The SDK also ships with the ExpressionBuilder class which is just a static instance of the ExpressionEngine class.

Important

The ExpressionBuilder class is not intended to be used in concurrency scenarios! For concurrency scenarios please set a new instance of ExpressionEngine class to the PrintJob instance.

Please refer to the Visual Label Editor demo project that shows how to use ExpressionEngine class.