Using Functions

You use a function by calling it by name, along with its parameter values.

A function is a unit of functionality that calculates a value or performs some steps which you can use from within your UJML scripting statements by referring to its name. See Identifiers. If the function requires them, you must also provide one or more parameter values of the proper data types. See Data Types. A function may return a value.

UJML provides a set of built-in functions to perform common tasks or retrieve common values. See Functions. You can also create your own functions in UJML and call them from within your program. See User Defined Functions.

Calling a function from the scripting language

For scripting language expressions you specify the name of the function followed by a pair of parentheses. See Script Blocks, Expressions. The parameters of the function are specified within the parentheses and are separated with commas. See Parameters. For example 'someFunction(foo, bar)'.

Calling a function from XML scripting

For XML scripting, you specify the name of the function in a call element. See XML Scripts, call. The parameters of the function are specified by XML script expression elements within the call element. See Parameters.

Using function result values

If the function returns a value you may assign it to a variable of the proper data type, use it in an expression, use it as a parameter in another function, or even ignore it. See Variables, Literals, Script Expressions. The return value of a function is just like the value of a variable or a literal except that the function might return different values each time it is called.

Specifying parameters

A function parameter may be a variable, a literal, another function, or any other form of scripting expression that returns a value. The type of the thing used as a parameter must match the data type expected by the function for the parameter at that position. See Parameters.

Required and optional parameters

All functions may have required parameter values. Failure to specify a value of the proper data type for all of the required parameter values will result in a compiler error. Some functions may have optional parameter values, which may be included or not as appropriate for how you are using the function.

Example

The following example shows how to call two built-in functions as property value expressions that are evaluated when the box is displayed. The parameter values are predefined XML entities provided by UJML. It is part of the helloworld4.ujml sample.

Copy Code

<box>
    <width>
        <eval>_getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;)</eval>
    </width>
    <height>
        <eval>_getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;)</eval>
    </height>
    <bg>&_COLOR_BLACK;</bg>
</box>

The following example shows how to call a function and assigns the result to a value. The parameter values are literals. It is part of the assignment.ujml sample.

Copy Code

mStringVar = aFunction(true, 2000000, "Foo");

The following example shows how to call a function and assigns the result to a value. The parameter values are a mix of variables, mathematical expressions, and function calls. It is part of the assignment.ujml sample.

Copy Code

mStringVar = _substring(mMessages[7], _strlen(mMessages[7]) - 6, _strlen(mMessages[7]));

The following example shows how to call a function of a state machine using dot notation. The parameter values are a mix of literals, functional calls, mathematical expressions, and predefined XML entities. It is part of the visualelements.ujml sample.

Copy Code

ScrollingMenu.init(0, 0, _getIntProperty(&_PROPERTY_INT_SCREEN_WIDTH;),
    (_getIntProperty(&_PROPERTY_INT_SCREEN_HEIGHT;) / 2), &_COLOR_BLUE;,
    &_COLOR_SILVER;, &_COLOR_BLACK;, &_COLOR_WHITE;, &_COLOR_BLUE;,
    &_FONT_SIZE_MEDIUM;, &_FONT_STYLE_BOLD;, &_FONT_FACE_SYSTEM;);