You can write property expressions to define object properties based on functions, columns, or parameters that supply values at runtime. Property expressions can be simple, such as a column returned by a query. Property expressions can also be complex, such as an If () statement combined with a parameter and a concatenated string of literal values.
Property expressions enable you to create dynamic values for your object properties. Many business decisions depend on factors such as market conditions, sales, operational expenses, new locations, profit and loss margins, and customer satisfaction. These factors are subject to change.
Your QMF Visionary world can be responsive to these changes and show their significance in the appearance of the world. Profit or loss, for example, can be displayed visually using color: black for profit, red for loss.
Here is a property expression that you might use to distinguish profit and loss in the Color property of the object:
If(sum(sales/expenses)>=0,Black,Red)
The following sections provide syntax guidelines and examples to help you write property expressions in QMF Visionary.
Many QMF Visionary objects have a list of constant values you can use to define a constant property.
The following figure shows an example of the supplied values for the LineStyle.Pattern property.
By looking at the supplied property values in the Object Inspector, you can also determine the data type that must be returned when you write a property expression. For example, the Visible property (a property of most QMF Visionary objects) supplies True or False as options in the property list box. You can also write a property expression for the Visible property that returns a true or false result.
For a full reference to QMF Visionary objects, object properties, and property data types, see the QMF Visionary Studio online help.
When you write property expressions, you must use the syntax required by QMF Visionary. The following table describes some basic rules for typing property expressions in the Object Inspector or the Formula bar.
Task | Rule | Example |
---|---|---|
Display a calculated value, such as a parameter or column name | Use equals sign (=) for calculated expressions. | =cust_num |
Display a literal value | Type the literal exactly as you want it to appear in text. | Sales Organization |
Display a text string in an expression | If the string is part of a combined expression that also includes calculated values, columns or parameters, it must be surrounded by quotation marks (" "). | ="My name is: "+fname |
Concatenate two or more elements of ambiguous or differing data types into one expression | Use the Concat() function to concatenate elements in an expression. | =Concat(fname,lname) |
Concatenate two or more text strings | Use the plus sign (+) to concatenate text strings. | ="Click here to go to"+newline+ "Scene2" |
Add two or more numeric values | Use the plus sign (+) to add constants or parameters of numeric data types. | =Param1+5 |
Insert a carriage return in an expression | Type newline. If the expression elements are the same data type, use a plus sign (+) before and after. Otherwise, include newline in the Concat() function.Warning: ToolTipText and Caption properties do not allow multiple lines of text. | =city+newline+state |
Display the value of another property | Use the equals sign (=) plus the object name and property name with dot notation. | =Text1.value |
This following sections describe these syntax rules in more detail and describe formatting, units of measure, and casting rules in QMF Visionary Studio:
In addition to these syntax rules, the QMF Visionary Studio online help contains detailed reference entries for all functions provided by the application.
QMF Visionary treats all object properties as literals, unless the value entered begins with an equals sign (=). The following figures show two property expressions for the ToolTipText property of a Button object: the first defines a literal value, and the second defines a calculated value.
Try it. Use the = sign in an expression and then try the same expression without the sign. View the results in runtime. For example, type a column name from the query for your layout. View the object in runtime. Then precede the column name with the = sign.
You can concatenate parts of a property expression in two ways:
When the parts of the property expression are of unambiguous data types, you can use the plus sign. Thus, two text strings can be concatenated explicitly using the plus sign, and two integers can be added using a plus sign.
However, if the parts of the expression have different data types, you can use the plus sign.
To concatenate more than two elements, you must embed more Concat() expressions in the outer Concat() expression.
Therefore, you can use the plus sign to add parameters or columns that all have a numeric data type. You can also use the plus sign to concatenate two columns that contain text or character data types. However, to combine a literal text string with a column that contains a numeric data type, you must use the Concat() function as shown.
To combine a parameter that has a text data type, a literal text string, and a column that has a numeric data type, you must use embedded Concat() functions, as shown.
QMF Visionary provides a custom formatting function and templates for displaying property values in special formats. The FormatNum() function transforms the value you supply into the display format you specify.
The syntax for FormatNum() is as follows:
FormatNum(format,value)
In this expression, format is one of the templates provided by QMF Visionary, and value is the value you want formatted.
The function FormatNum() is similar to custom number formats in Microsoft Excel. It allows you to specify how you want your object properties to be displayed. You can either type the syntax for the format template or select the format template from a list of available templates. To select a format template click Edit --> Format Number.
FormatNum() can be used to format the following types of values:
For a description of the syntax and templates you can use with the FormatNum() function, see the reference section of the QMF Visionary Studio online help.
QMF Visionary Studio allows you to enter the following unit specifications in a property value.
Units | Abbreviation Formats |
---|---|
Inches | in, inch, inches |
Centimeters | cm, centimeter, centimeters |
Millimeters | mm, millimeter, millimeters |
Points | pt, point, points |
Twips | tw, twip, twips |
If no units are specified, the default units are inches or the default setting in your Windows registry.
QMF Visionary Studio automatically casts some data types when a scene is executed. For example, in any property that requires a text value, you can write a property expression that returns any data type (Boolean, Color, PointList, Integer, and so on). Thus, the property displays these values as text strings: True, Blue, 1, and so on. However, you cannot cast an expression that returns a PointList value into a property value that accepts only a MultiPolygon type.
If you want to explicitly cast an object property value to a different data type, QMF Visionary provides functions for explicit casting.
See the reference section of the QMF Visionary Studio online help for a list of implicit casts and a list of the explicit casting functions.
QMF Visionary provides many built-in functions and a standard function library (StdFunc.vlb) that you can use to write property expressions. In addition, you can include your own function libraries in QMF Visionary Studio by placing the library .dll file in the same directory as the QMF Visionary Studio .exe file. When QMF Visionary Studio is launched, it recognizes and loads your function library.
The following table describes the types of built-in and standard functions provided.
Function category | Description | Example |
---|---|---|
Color | A set of functions that provide information about and perform calculations on colors | Brighten(color, amount) returns a color brightened by the specified amount. |
Conversion | A set of functions that convert data types | NumToBool(number) returns a Boolean value. |
Data Formatting | A set of functions that convert data between database format and Windows regional format | DbNumToWin(number) converts a number from database format to Windows format. |
Date and Time | A set of functions that perform date and time calculations | Date(year, month, day) returns a numeric value that represents the specified date. |
Hierarchy | A set of functions that are valid for hierarchy layouts | SiblingCount() returns the number of sibling data instances in the current data template. |
Information | A set of functions that return information | StockImage(imageName) retrieves the specified image from the Images folder of the world. |
Logical | A set of If() functions that accept various argument types and return various value types The If() function returns Boolean values if the supplied values for valueIfTrue and valueIfFalse are Boolean. Similarly, it returns other data types based on the argument data types. | If(condition, valueIfTrue, valueIfFalse) |
Math and Trigonometry | A set of functions useful for calculating angles, degrees, exponents, and other mathematical formulas | Abs(number_value) returns the absolute value of a numerical argument. |
Spatial | A set of functions that scale, convert, rotate, and compute spatial values | CenterPoint(pointList) returns the center point for a list of points. |
Statistical | A set of functions that apply statistical calculations | StdDev(number_value) returns the standard deviation in a series. |
Text | A set of functions that examine text values | Trim(text_string) returns the text string with any blank spaces to the left and right of the string removed. |
For a complete list of built-in functions and the standard function library, see the reference section of the QMF Visionary Studio online help.