Accessing display elements through the interpreter (or script)

(only available for terminals with 32-bit CPU, for example "MKT-View II")

Principle
Examples for the "disp" command

Principle

You can access a certain display element (on the current display page) from the interpreter, for example ...

to change the colour of the element during run-time as an error signal
to change the position of an element to let it move across the screen
to retrieve the name of the variable associated with an element (to pass it to a different page as a reference)

To tell the interpreter which element to access, the element must have a unique name (at least unique within the display page, on which it is located).

For example, there may be a display element named "Title" (btw, you can see or modify that name in the 2nd column of the display definition table).

The basic syntax to get / set a property of a display page element through the display interpreter (*) is

disp.<NAME>.<COMPONENT> ,: where <NAME> is the user-defined name of the element ("Title" in this example),
and <COMPONENT> is one of the components listed further below .
The token "disp" may be abbreviated as "dis".

Example:: disp.Title.xp=8 : disp.Title.yp=8 : REM change title position
(more examples in another chapter)

In this example 'Title' is an arbitrary name of a certain display element, while 'xp' and 'yp' are the components.

This way, you can modify parameters during runtime, which can otherwise only be modified with the programming tool. (Note: This only works because the "current display page" is loaded from FLASH ROM into RAM).

Hint: Use short, but "speaking" names whereever you can. It's poor programming style to use names like "Name1", "Name2", "Name3".

Alternatively, the n-th element of the current display page can be accessed like an array (at least, formally).

Syntax:: disp.li[.<index>].<COMPONENT>

This format should only be used if the elements of a display page need to be accessed like a (formal) array. Example #3 shows one of the (few) cases where this is necessary. The array index ("line index") is the same as the "li" component.
For example, the following expression returns the name of the N-th display element on a page:

disp.li[N].na

Using the interpreter function clnr ("current line number"), a display element can retrieve its own name (or any other member, see list in the next chapter):

disp.li[clnr].na

Complementary to the above, the following command sets N to the array index ("number", nr) of the element named "Title":

@N = disp.Title.nr

Display elements can also be accessed through the script language in a similar way.

Syntax:: display.elem[<Element>].<COMPONENT>

where <Component> has the same meaning as for the display interpreter - see next chapter.
<Element> may be a string (in that case, it's the name of a display element, or an integer number (which would be the index in the page's definition table, shown in the first grid column in the programming tool).
A few examples for accessing/modifying display elements through the script language can be found here.

Accessable Components

The following components for "disp" (in the interpreter) / "display.elem" (in the script language) have been implemented :

ar: access rights
ba: numeric BAse (radix) : 2=binary, 10=decimal, 16=hexadecimal
bc: background colour
b2: second background colour (for colour gradients and filled polygons)
dm: draw mode, like 0=normal, 6=reversed fore-and background colour, etc.
The draw mode values are the same as for the interpreter command dm .
fc: foreground color. The preferred colour format is explained here .
fl: Flags
fn: font number
fs: Format String (completely, including all backslash sequences used in this line)
hp: height of the display element in pixels
id: control ID of this element. Only for the script language.
na: Name of this element. If the element doesn't have a name, this function returns an empty string.
nr: Number of this element (i.e. the zero-based array index of this display element within the current display page). Read-Only.
sf: Selection Flags. Allows to check if this display element is currently 'selected', and why .
visible: Only for scripts, see display.elem[<Element-Name>].visible. TRUE=visible, FALSE=invisible.
vn: variable name (name of the variable displayed in this element; if any)
wp: width of the display element in pixels
xp: X-Position (pixel coord.)
yp: Y-Position (pixel coord.)
zo: Zoom (X,Y)

Note: Assigning a new value to some of these components will force updating that display line, but not the entire display. If the display elements overlap, or a display element shall move across the screen, consider using the option "always redraw this page completely" in the display page header .

disp.<ElementName>.fl : A bit combination of the following display-flags; usually set at design-time (but not modified at runtime) :: 1 : 'When modified (while editing), the new value shall be sent to the output immediately'
2 : 'This line (or display element) is a menu item'
4 : 'Always redraw this line (or display element) completely' (it may be overlapped with something else)
8 : 'This line (or whatever display element) can be selected via touchscreen'

disp.<ElementName>.sf : Contains a bit combination of the following 'selection/highlight'-flags:: 1 (sfSelByState) : 'the item is currently highlighted due to the state code (for example, the "button state" has been set via command)
2 (sfSelByTouch) : 'the item is currently highlighted because the touchscreen is pressed on it'
4 (sfSelExecuted) : 'the item is currently highlighted because it's being 'executed' at the moment' (for example, button-event being executed)
This function can be used to check if a graphic button is currently selected because the operator keeps the touchscreen pressed (over the button). An example of polling a graphic button this way can be found in the display application ?/programs/MKTview2/MV2_Demo.cvt, page "Organ".
In the script language, the symbolic bitmasks ( "sf....", shown above in parentheses) should be used instead of the decimal values.

Examples (for the "disp" command)

If you use the "MKT-View II" (or a similar device with colour TFT display), load the application MV2_Demo.cvt from the folder "MKTview2" in the tool's "programs" folder.

Example 1: Modifying an element's position on the screen

On the display page titled "EarthMov", you will see an icon slowly moving across the screen in the background of the text :

To achieve this effect, the program permanently modifies the pixel coordinate of the display element named "Earth" (which, in this case, is a bitmap but it may as well be something else). The coordinate of the "Earth" bitmap is permanently modified in the local event definitions of this page:

The construct dis.Earth.xp=... and dis.Earth.yp=... modifiy the coordinate of the display element named "Earth". We use the event "always" here for simplicity, so the position will be modified in every main loop. The frequency of the update depends on the CPU speed, but in this case the speed of the movement does *not* depend on the CPU speed because the coordinate is derived from the system timer (ti is a 32-bit timer, incremented every 100 milliseconds).

There's nothing special about the definition of the display element itself. All it takes is a unique name so we can access the element through the interpreter, using a formal assignment to the "disp" command. Here, the name of the display element is "Earth" :

Example 2: Modifying an element's colour with the "disp" command

Another example for the usage of the "disp" command/function is on the first page in the same application (MV2_Demo.cvt) . On some pages, the foreground colour of a bargraph (which shows the page-scan timer) changes if the page-scan function is active, depending on the current value of the page-scan timer:

The syntax is

disp.<ElementName>.fc = <new foreground colour>
disp.<ElementName>.bc = <new background colour>

In this case, the element named "PST" is a bargraph as indicator for the page-scan timer. In a real-world application, similar event definitions could be used to change the colour of a display element as a function of a signal received from the CAN bus. Note that the colour values should use one of the 'standard' colours specified here .

Example 3: Retrieving the name of the variable connected to a certain display element

Assume you need to do "something" with the display element which is currently selected (for editing or navigation). In this case, the mi function ("menu index") can be used as an index into the array of display elements on the current page. The expression

disp.li[mi].vn

will retrieve the name of the variable which is connected to the currently selected edit field (or similar) on the screen. This function is used in the demo application MV2_Demo.cvt (for the MKT-View II) on the page named "ParSel" to select one of six different parameters as shown here:

Screenshot "Variable Reference Demo", part 1

An in-depth explanation, with details on variable references can be found in a separate document (follow the link, and remember to use your browser's "back"-button to return here).