DISPLAY and DIALOG Messages

From STX Wiki
Jump to navigation Jump to search

The dialog and display messages are described together because all messages sent by a display can also be sent by a dialog. The display only generates messages if there are both graphs and dialogs in the display. If the display only contains a dialog, all display messages are redirected to the dialog item! In the following description, dialogitemname is used if a message is always generated by a dialog and windowitemname if a dialog or a display can send the message.

Keyboard
MENU|DISPLAY windowitemname KEY keycode keyname
This message is generated if a key is pressed inside the dialog area or inside a display without an active graph. The information about the key is stored in the variables keycode and keyname. The value of keycode is a unique identification of the key including some status flags (shift, control, ...). The keyname is a translation of keycode into a string representation, or an asterisk (*) if translation is not possible (see keyname values).
Popup Menu
MENU|DISPLAY windowitemname POPUP menuitem
This message indicates that the user has selected a popup menu item. The parameter menuitem identifies the menu and item: menuitem = 100.menuindex + itemindex. The menus and menu items are numbered in the same order as the ADDPOPUP commands were executed.
Toolbar
MENU|DISPLAY windowitem TBCOMMAND buttonid buttonname
MENU|DISPLAY windowitem TBCHECK buttonid buttonname
MENU|DISPLAY windowitem TBUNCHECK buttonid buttonname
These messages are generated if a toolbar button is pressed (TBCOMMAND), checked (TBCHECK) or unchecked (TBUNCHECK). There are two styles of toolbar button: the button sends a command, whilst the switch sends its checked/unchecked state. Both parameters buttonid and buttonname can be used to identify the button. For a list of available buttons see the command SET DISPLAY.
Mouse Wheel
MENU|DISPLAY windowitemname WHEEL code delta ctrl shift left right
A special message is used for the mouse wheel. If its position is changed and no graph is active, the display or dialog item sends a WHEEL message. The code is the original window-message code. It is decoded into delta (positive/negative position increment) and flags (0…not pressed, 1…pressed) for simultaneously pressed keys and/or mouse buttons. The value of delta depends on the change-speed and the type of mouse.
Print
MENU|DISPLAY windowitemname STOP par
If a copy/print process (initiated via a command or the copy/print dialog) is finished, the display sends a STOP message to the shell. The parameter par is meaningless (and normally set to 0).
Only the graphs contained in a display are printed - not the dialog!
Joystick
MENU|DISPLAY windowitemname JOYSTICKBUTTONS buttons
MENU|DISPLAY windowitemname JOYSTICKPOV pov
If a joystick is attached to the system and the option /Joystick was used on display creation (see NEW DISPLAY), these messages are send on button/point of view activation by the user. The buttons parameter is 32 bits long. Theoretically 32 buttons are supported. Each bit indicates the status (pressed=1, not pressed=0) of a button. For a joystick with 8 buttons, only the first 8 bits are relevant. E.g. to check if the 4th button was pressed use the following if 'buttons & bit(3)' != 0 then…. Note: the value of buttons if only the 4th button is pressed is 8 (23). The value of buttons if the 2nd and 4th buttons are pressed is 10 (21+23). The pov parameter has the values 0…7 if pressed, where 0 is North, 1 is North-east, 2 is East etc. If the point of view button is not pressed (centered), pov has the value –1.

COMMAND

MENU dialogItemName COMMAND controlindex

If a control is double-clicked, the message COMMAND is generated. The index of the control (specified when the dialog was created) controlindex is the only parameter. The new status is copied to connected variables and table items before the message is sent.

Context Menu

The DIALOG item context menu implementation sends the following messages:

CMSTAT

MENU dialogItemName CMSTAT controlindex

The CMSTAT message is generated when the right mouse button (context menu) is pressed by the user. The parameter controlindex is the index of the control pointed to by the mouse cursor or –1 if the mouse-click was located in the dialog background. The message handler should respond with a SET dialogitemname CONTEXTMENU menuid command. The message is also sent if no context menu is defined.

CMITEM

MENU dialogItemName CMITEM menuitem

If an item of a (previously defined and displayed) context menu is activated, the CMITEM message is sent. The parameter menuitem is computed in the same way as for popup menu items: menuitem = 100.menuindex + itemindex.

DROPFILE

DISPLAY|MENU itemId DROPFILE filePath

This message is sent to a display or dialog when one or more files are dropped onto it. The parameter filePath is a simple table with one absolute path per entry. Dropfile messages are only generated for displays which were created using the /R option (see NEW DISPLAY).

ListView message

The ListView dialog control may send any of the following messages:

CELLEDITED

MENU dialogItemName CELLEDITED controlindex rowIndex columnIndex newLength newValue oldLength oldValue

The CELLEDITED message is sent when the user has finished editing an editable field of a ListView control. At this stage, the edited text is already stored in the ListView (but, of course, not in the connected STx table item - reading the contents of the ListView into its connected table requires use of the SET dialog /Read" command).

controlIndex The index of the ListView control.
rowIndex, columnIndex Indicating the cell that has been edited (both starting from 0).
newLength, newValue The new length and value to which the respective cell has been set.
oldLength, oldValue The length and value before editing.

See the example script editabletable.sts for a functioning example.

CELLCANCELLED

MENU dialogItemName CELLCANCELLED controlindex rowIndex columnIndex

The CELLCANCELLED message is sent when the user cancels cell editing by pressing, e.g., the ESC key.

controlIndex The index of the ListView control.
rowIndex, columnIndex Indicating the cell that has been edited (both starting from 0).

CELLEDITEDTAB

MENU dialogItemName CELLEDITEDTAB controlindex rowIndex columnIndex newLength newValue oldLength oldValue

The CELLEDITEDTAB message is sent when the user finishes editing an editable field of a ListView control by pressing the TAB key. See CELLEDITED for an explanation of parameters.

CELLEDITEDBACKTAB

MENU dialogItemName CELLEDITEDBACKTAB controlindex rowIndex columnIndex newLength newValue oldLength oldValue

The CELLEDITEDBACKTAB message is sent when the user finishes editing an editable field of a ListView control by pressing the Shift+TAB key combination. See CELLEDITED for an explanation of parameters.

Progress value

VALUE

MENU dialogItemName VALUE controlIndex progressValue

The VALUE message is generated by a DIALOG when the dialog contains a progress control and the user clicks somewhere on the progress bar. The value of progressValue is within the range specified when the control was created (see SET dialog index PROGRESS).

UPDATE

MENU dialogItemName UPDATE controlindex

If a control is updated, the message UPDATE with the parameter controlIndex is generated. controlIndex is the index of the control as specified when the dialog was created. The new status is copied to connected variables and table items before the message is sent.

Window state

When the user presses the maximize, minimize, restore or close buttons on a window, the DIALOG or DISPLAY sends one of the following messages:

MINIMIZE

MENU|DISPLAY windowItemName MINIMIZE par

The DIALOG or DISPLAY sends this message when the user presses the minimize button. The argument par is meaningless and may well be set to 'STx is great'.

MAXIMIZE

MENU|DISPLAY windowItemName MAXIMIZE par

The MAXIMIZE message is send by a DIALOG or a DISPLAY when the user presses the maximize button. The parameter par is meaningless (normally 0).

RESTORE

MENU|DISPLAY windowItemName RESTORE par

The RESTORE message is sent by a DIALOG or a DISPLAY when the user presses the restore button. The parameter par distinguishes between the restore (0) and the activate (1) function.

CLOSE

MENU|DISPLAY windowItemName CLOSE par

The CLOSE message is sent by a DIALOG or a DISPLAY when the user presses the close button. The parameter par is meaningless (normally 0).