< 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
See also:
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.
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).
popup("<message-text>") orpopup("<message-text>", <interval-time> )
orpopup( #<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:
(logger.state==2) && (popup.id!=3)popup(#3,"TRIGGERED",10)
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.
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.
popup.close orpopup.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) .
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 :
popup.rect( x1, y1, x2, y2
)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.
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")
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) :
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) :
popup.key==13popup.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:
popup.key
through the interpreter (in contrast to the 'normal' keyboard functions,
see below).
popup.key does not receive new input.
popup.key will be cleared by the firmware automatically when
a new popup window is opened.
popup.key itself, the next
pressed key will also be passed to the normal keyboard processing queue.See also: "normal" keyboard functions (outside popup windows)
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.
The following interpreter commands / functions are implemented in the terminal firmware. General information about the interpreter language can be found here .