Custom Expressions
Expressions Overview
Expressions allow complex tag-based logic to set a property. Expressions are evaluated on the main GUI thread.
Expression
Expressions are broken down into two phases: the math phase and the formatting phase. In the math phase, one can use tags to compute various mathematical operations to get a single value. The formatting phase is intended for displaying purposes. Formatting options would include things like specifying the number of decimals for a number, date time string format, etc.
Math
The math phase will always return a single numeric value. A good way of thinking about this phase is to think it as a calculator where the only allowed
inputs are tag values, constants, and operations on those values. All constants are treated as doubles, including boolean values (e.g., 1.0/0.0).
Operators
- Tag (
[<Tag name>]) - Constants (
pi,epsilon,inf) - Basic math operators (
+,-,*,/,%) - Functions (
min,max,avg,sum,abs,ceil,floor,round,exp,log,log10,logn,pow,root,sqrt,clamp) - Trigonometry (
sin,cos,tan,acos,asin,atan,atan2,cosh,cot,csc,sec,sinh,tanh) - Equalities (
==,!=,<,<=,>,>=) - Control (
if,then,else)
Format
The format phase will always return a single string value. A good way of thinking about this phase is to think of the value from the math value being converted into some reasonable string. Because of this, using formatting options will convert the math value into a string.
Operators
round(decimalPlaces)
- Returns a number rounded to the nearest decimalPlaces decimal places.
base(base)
- Returns a string equivalent of the input number according to the specified base.
numericFormat(format)
-
Returns a string formatted by the pattern described in
format. Invalid formats will return an empty string. -
Format:
Character Description #Denotes a basic decimal character. If used past a decimal point, it will specify the minimum number of decimal values to show. This is not compatible with hexadecimal formats. HDenotes a hexadecimal character. This is not compatible with decimal formats. 0Denotes a zero fill character. The index of this character will be used as the minimum number of digits to display before a decimal point. There should be at most one of these. .Denotes a decimal point. There should be at most one of these in a decimal format, and it is not compatible with hexadecimal formats. ,Denotes a group separator. The index of this character will be used as the number of digits to group. There should be at most one of these, and they cannot be used past a decimal point. -
Examples:
Input Format Result 123 # "123" 123 #,### "123" 123 0### "0123" 123 ##.## "123.00" 123456 #,### "123,456" 123456 ##,## "12,34,56" 1 #0## "001" 1234 #,0## "1,234" 123 HH "7B"
dateTimeFormat(format)
-
Returns the Unix timestamp as a string in the form described in
format. -
Format:
Option Output h The hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display) hh The hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display) H The hour without a leading zero (0 to 23, even with AM/PM display) HH The hour with a leading zero (00 to 23, even with AM/PM display) m The minute without a leading zero (0 to 59) mm The minute with a leading zero (00 to 59) s The whole second, without any leading zero (0 to 59) ss The whole second, with a leading zero where applicable (00 to 59) z The fractional part of the second, to go after a decimal point, without trailing zeroes (0 to 999). Thus, "s.z" reports the seconds to full available (millisecond) precision without trailing zeroes zzz The fractional part of the second, to millisecond precision, including trailing zeroes where applicable (000 to 999). AP or A Use AM/PM display. A/AP will be replaced by an upper-case version of either QLocale::amText() or QLocale::pmText() ap or a Use am/pm display. a/ap will be replaced by a lower-case version of either QLocale::amText() or QLocale::pmText() t The timezone (for example "CEST") d The day as a number without a leading zero (1 to 31) dd The day as a number with a leading zero (01 to 31) ddd The abbreviated localized day name (e.g. 'Mon' to 'Sun'). Uses the system locale to localize the name, i.e. QLocale::system() dddd The long localized day name (e.g. 'Monday' to 'Sunday'). Uses the system locale to localize the name, i.e. QLocale::system() M The month as a number without a leading zero (1 to 12) MM The month as a number with a leading zero (01 to 12) MMM The abbreviated localized month name (e.g. 'Jan' to 'Dec'). Uses the system locale to localize the name, i.e. QLocale::system() MMMM The long localized month name (e.g. 'January' to 'December'). Uses the system locale to localize the name, i.e. QLocale::system() yy The year as a two digit number (00 to 99) yyyy The year as a four digit number. If the year is negative, a minus sign is prepended, making five characters. -
Example format strings (assumed that the Unix timestamp is
990447189120):Format Result dd.MM.yyyy 21.05.2001 ddd MMMM d yy Tue May 21 01 hh:mm:ss .zzz 14:13:09.120 hh:mm:ss .z 14:13:09.12 h:m:s ap 2:13:9 pm
map(format)
- Returns the value that falls in the range provided in
formatbased on the input value. The following is the expected syntax of theformat:- A list of range values separated by a comma
- A range value is defined as:
- Starts with
{ - A pair of a range and a value
- A range is defined as:
- Starts with
[or(- A
[implies inclusive - A
(implies exclusive
- A
- A pair of numeric values separated by a comma
- An empty numeric value implies either positive infinity or negative infinity, depending on which side of the pair it is on
"inf","+inf"resolve to infinity"-inf"resolves to negative infinity
- Ends with
]or)- A
]implies inclusive - A
)implies exclusive
- A
- Ends with
}
- Starts with
- Starts with
- A default value may be specified with a
|character
hasPermission(permission)
- Returns whether or not the currently signed-in user has permission:
permission. This is the expression equivalent to the script with the same name:system.hasPermission()
Examples
Get Tag
- Expression:
{[TAG1]} - Possible output:
10
Round Value
- Expression:
{round[TAG1]} - Possible output:
6
Add Tags
- Expression:
{[TAG1] + [TAG2]} - Possible output:
30
Format Sum
- Expression:
{([TAG1] + [TAG2])|numericFormat("#,###")} - Possible output:
1,456
Return Value as Binary
- Expression:
{[TAG1] + [TAG2]|base(2)} - Possible output:
11110
Conditional Value
- Expression:
{if ([TAG1] % 2) [TAG2]; else [TAG3];} - Possible output:
1or3
Convert °C to °F
- Expression:
{([CelsiusTag] * 9 / 5) + 32} - Possible output: If
CelsiusTag=20,68
Embed Values into String
- Expression:
Temp: {[TAG1]} | Pressure: {[TAG2]} - Possible output:
Temp: 1 | Pressure: 2
Map Values from Range
-
Expression:
{[TAG1]|map("{,0),-1},{[0,10),0},{[10,20),1},{[20,30),2},|nan")} -
Possible outputs:
TAG1Output -10"-1"0"0"1"0"15"1"30"nan"
Check User Permission
- Expression:
{[TAG1]|hasPermission("Open Page")} - Possible outputs: False:
0, True:1