Interpreter commands for a "popup" window

< under construction. 2007-04-27: added the option to control a popup window via CAN in non-CANopen-networks >

Note: This document is a work in progress. In April 2007, it was not clear what the final result would look like !

Contents

  1. Scope
  2. Opening a popup window
  3. Closing a popup window
  4. Defining size and position of a popup window
  5. Keyboard handling in a popup window
  6. Controlling a popup window via CAN
  7. Interpreter commands and -functions for the popup window

See also:



Scope

Under certain conditions, you may have to attract the user's attention if "something special" happens, for example show a small warning message in the center of the screen. For this purpose, there are some interpreter commands in the programmable terminal to open and close such a message window. The terminal firmware uses the same subroutines to show its own warning messages, errors, etc. In some devices, a popup window can also be controlled entirely via CAN-bus.

In your application, you may use popup windows ..

You should not use a popup window ..

The main differences between a popup window and other, normal graphic elements are :

The next chapters show how to open and close these popup windows / message boxes.

Note: Only terminals with a firmware compiled in October 2003 (or later) have these commands. On small displays (like the 128*64 pixel display used in the UPT515) it makes no sense to open a popup window in front of the "normal" display screen, so there may be no "popup"-commands in certain displays.

back to top


Opening a popup window

Open a popup window in an event reaction, similar as in this example:


(screenshot: 3 global events which may open different messages as "popups")

In this example, three different popup windows are displayed, each of them triggered by a special "event" (here: the state of the CAN logger, but that doesn't matter now).

Syntax:
popup("<message-text>") or
popup("<message-text>", <interval-time> ) or
popup( #<popup-id>, "<message-text>", <interval-time> )

The first variant only contains the text which shall appear in the popup window. If you do not specify the position and size of the popup window, it will automatically appear in the center of the screen, and look like one of the system message boxes.

The last variant specifies two optional parameters: An ID-number (popup-id) and an interval time. The interval time is specified as

<interval-time> = Number of 100-millisecond-intervals until the popup window closes automatically.

The popup-ID can be any decimal number between 0 and 32767. It is -more or less- just a kind of variable which you can use to find out which popup window has been displayed at last. It doesn't matter which values you use as identifier, the only thing to remember is the "default" value after power-on is zero.

In the example, the popup-ID was used in the event definition to avoid opening a popup window saying "CAN-Logger has been triggered" (logger_state=2) over and over. Remember the "&&"-operator is the BOOLEAN AND, here used to combine two boolean subexpressions.

Look at this example to see what the "popup identifier" can be used for:

Event :
(logger.state==2) && (popup.id!=3)
Reaction :
popup(#3,"TRIGGERED",10)
In natural words, this event / reaction definition says:

"If the logger has been triggered AND this message has not been displayed previously,  
then show a small message for one second which says 'Triggered' ".

The numeric interpreter function popup.id just returns the popup-identifier which has been used in the previous function call popup( #id, ..). After power on, the function popup.id will return something which is not equal to '3'. As soon as logger.state has a value of '2', the event-condition gets TRUE, and a new message window with the identifier 3 pops up for 10 * 100 milliseconds before it disappears automatically. The value of popup.id remains 3, so even if logger.state remains 2, the message window will not open up again.

In the screenshot shown above another event will be detected as soon as logger.state gets zero (which means "logger off"). Note that a different popup-id is used here. The effect is: Only if the logger state changes, a new message will appear.

back to top


Closing a popup window

If you do not want to close a message popup automatically after a certain time, you may close it through an interpreter command. This can be done with the command popup.close.

Syntax:
popup.close or
popup.close( #<popup-id> )

The first variant closes any user-defined popup message, no matter which identifier has been assigned to it. The second variant can be used to close only a certain popup message (for example, you may want to close only certain message boxes with a function key) .

back to top


Defining the size and position of a popup window

This is only used for certain "special cases". Normally you do not have to define the size and position of a popup yourself. The firmware will automatically place the popup window in the center of the screen and give it a size which is less than a quarter of the screen. If you do not like this, or want to position your message box so it does not hide important parts of your user-defined screens, you can define size + position of the message box yourself.

Note: You must do this before you open a popup-window ! Changing size and position of a message box which is already visible may lead to irreproducible results.

To define size and position of a popup window, use this interpreter command :

Syntax:
popup.rect( x1, y1, x2, y2 )

where
x1=left, y1=top, x2=right, y2=bottom; all these are graphic coordinates, starting at zero.

The weak point of this command is, you must know the size of the target display (in pixels). For the "MKT-View" terminal, x may be 0...319,  y may be 0...239 because the screen is 320 pixels wide and 240 pixels high. For other terminals, this may be different.

Example:
popup.rect(4,200,110,237) : popup("Hello !")

Lets all message boxes appear in a small box in the lower left corner of the display. The second instruction ("Hello !") is just for testing, it produces something like this:


(screenshot from test application "popup_t.cvt")

Note:
Make sure the strings in the command popup("<string>") are small enough to fit inside the message box. The firmware may chose a small font for the text inside the popup window, but this does not help in all cases.

back to top


Keyboard handling in a popup window

You may want to do something special if the user presses a special key while a popup window is open. For example:

The terminal detects the engine temperature gets too hot, opens a popup window, and waits until the user presses the ENTER key to confirm having read this message. The simplest reaction (for the terminal) would be to close the popup window then.

For this (and other) purposes, there is a special function (which, in fact, works like a global variable) :

popup.key

When read, this function returns the code of the last key which was pressed while a popup window was open. If no popup window is open, the function returns zero, even if keys are pressed !

When written, the internal variable will be set to any numeric value. In 99% of all cases this will be used to clear the key after it has been processed.

Example (from popup_t.cvt) :

Event :
popup.key==13
Reaction :
popup.close : popup.key=0 : rem Done

This example closes any popup window, if the user presses ENTER (alias the rotary button) while a user-defined popup is visible.

Notes:

See also:  "normal" keyboard functions (outside popup windows)

back to top


Controlling a popup window via CAN-BUS (since 2007-04)

In addition to the interpreter commands mentioned in the previous chapters, the terminal's popup window can also be controlled via CAN bus (requires firmware compiled 2007-04-25 or later).

To control the popup window via CAN (in a CANopen-less network), you must define which CAN identifier shall be used to control the popup-window via CAN. This only needs to be once during initialisation, preferrably in a local event on page zero. For example:

popup.canid = 0x7FF : REM CAN-identifier (rx) for the popup window

With this command, the terminal is instructed to listen for CAN-traffic on identifier 0x7FF (hexadecimal). Whenever the terminal receives a CAN-message with this identifier, the data are treated as a sequence of 8-bit ANSI characters which will be printed into the popup window.

A few special backslash sequences can be embedded in the character stream for the popup window. These are:

A few ASCII control characters are interpreted too (here given in hexadecimal format)

Character codes 0x20 (32 decimal) and above are considered normal, "printable" 8-bit ANSI (!) characters. Because the terminal's internal fonts use a DOS character set, some special characters may not appear correctly. German Umlauts, and some special French and Spanish characters are also displayed correctly (because they are internally converted from ANSI to DOS).

When sending long strings into the terminal, leave a gap of a few milliseconds between two CAN frames to give the microcontroller in the terminal some time to breathe. Otherwise, the application may seem to freeze for a moment, because while printing the characters in the popup window, the microcontroller firmware cannot update the "normal" (programmed) screens.

back to top


Interpreter commands (and -functions) for the popup window

The following interpreter commands / functions are implemented in the terminal firmware. General information about the interpreter language can be found here .

back to top


Last modified: 2007-04-25 (YYYY-MM-DD)

back to top