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.
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
- BarcodeItem: any expression will be evaluated to set the
- ImageItem: any expression will be evaluated to set the
- RFIDTagItem: any expression will be evaluated to set the
- LiteralItem: any expression will be evaluated to set the
Example: To set the current Date and Time in a TextItem, then set the
Expression property to
DateString() + " " + TimeString()
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.
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:
- Sets the
BackColorHexproperty of a TextItem named SampleText to a new color value.
- Hides or Shows a TextItem named TempText based on the value of previous Item using a conditional Expression.
- Sets the barcode value to encode.
- Changes or sets the barcode type.
- Sets the
CornerRadiusof a RectangleShapeItem named myRect by using
- Centers an ImageItem named Logo by using the
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.
- 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
- 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
- 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.
ExpressionBuilder 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 ExpressionBuilder 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.
Please refer to the Visual Label Editor demo project that shows how to use ExpressionBuilder class.