Dialog Controls
| Dialog Item | |||||
|---|---|---|---|---|---|
| NEW | SET | CONTROLS | ATTRIBUTES | MESSAGES | EXAMPLES |
The STx dialog item implements a variety of controls. Each control is created with it's own command SET dialog index <<control type>> command.
Contents
Common arguments
The following parameters have the same meaning for all the SET DIALOG control commands.
| index | The control index (a number in the range 0…999). The index is used in other setup commands and in messages to identify the control within the dialog.
|
| row | The position of the upper left corner of the control on the y-axis in dialog units |
| col | The position of the upper left corner of the control on the x-axis in dialog units. |
| text | The control caption. This is displayed inside or near to the control depending on the control type and the caption positioning. |
| var1 | The name of the first variable or item which is bound the the control. See the individual control syntax for more details. |
| width | The width of the control in dialog characters. |
| height | The height of the control in dialog characters. |
| var2 | The name of the second variable or item which is bound the the control. See the individual control syntax for more details. |
| fg | The foreground (text) color. |
| bg | The background color. This is only used for captions and STATIC controls.
|
| font | The font to use for this control. This overrides the dialog font. See Fonts and Font Argument Format for details. |
/A, /L, /R, /B or /C
|
For controls with a caption, you can set the position of the caption in relation to the control. |
/Above, /Left, /Right, /Below or /Center
|
A dialog can coexist with graphs inside a display (dialog+graphs) or can be the attached exclusively to a display (dialog-only). If an undefined command is applied to a dialog, the command is directly forwarded to the display owning the dialog. This means that all commands defined for display items can also be applied to dialog items. |
Dialog Caption Position
For the control types STATIC, BUTTON and GROUPBOX the caption is displayed inside the control window. For all other types, the position of the caption can be set by one of the options /Above, /Left (default) or /Right. The same options plus the option /Center are used to set the text alignment for STATIC controls.
For controls without their own caption (inside the control), the caption is implemented as a separate static control which is bound to the control.
Dialog Control Resizing And Positioning
If the size of the display window is changed, the control positions and sizes remain unchanged. The option /Window can be used to enable resizing/repositioning for some controls (changes are relative to the change in the display window):
Format 1: /Window=xy
x and y are single characters; each addresses two control window attributes of one dimension
| Value for x | Meaning |
|---|---|
x
|
50% change of x position |
X
|
100% change of x position |
w
|
50% change of width |
W
|
100%change of width |
b
|
50% change of x position and width |
B
|
100% change of x position and width |
| Value for y | Meaning |
|---|---|
y
|
50% change of y position |
Y
|
100% change of y position |
h
|
50% change of height |
H
|
100% change of height |
b
|
50% change of y position and height |
B
|
100% change of y position and height |
Format 2: /Window=xywh
Each of the characters x, y, w and h addresses one attribute of the control window (x/y position, width, height) and can be set to h (half change), f (full change) or a (automatic alignment).
For example, if you want to include an edit box in a dialog within a resizeable display, and you want the edit box to resize with the display, you can use the combination /W=**ff as follows:
$#dlg $#index edit $#row $#col 'caption' $#tEdit $#width $#height /W=**ff
Dialog Controls
BUTTON
SET dialog index BUTTON row col text [ * width height * fg bg font] [ /D ]
/Defaultbutton
|
Make the button the default button (activated when the dialog is displayed for the first time). A more general way (for all controls) to activate a control is implemented through the command: SET dialog index FOCUS
|
See Common arguments for a description of the parameters not described here.
Note that you may display an image in a button using the SET dialog BITMAP command.
CHECKBOX
SET dialog index CHECKBOX row col text var1 [width height * fg bg font][ /L|R ]
A checkbox control. The checkbox sends an UPDATE message when it is checked or unchecked.
| var1 | The name of the checkbox status variable (0=unchecked, 1=checked, 2=checked+grayed).
|
/3
|
Enable third state (checked+grayed); a normal checkbox supports only the states checked and unchecked. |
See Common arguments for a description of the parameters not described here.
COMBOBOX
SET dialog index COMBOBOX row col text var1 w h var2 [fg bg font] [ /E [ /I|N ]] [ /T ] [ /A|L|R ]
| var1 | The name of the variable to contain the input field text (/Editenabled) or the name of the variable to contain the index of selected item in the list. |
| var2 | The name of the table item (if /Table is specified) containing the combobox list (with one item per entry) or a variable containing a blank or tab separated list of words. |
/Editenable
|
Allow input field editing. If this option is used, the combobox entry can be edited and the string is stored in var1. |
/Integer or /Number
|
Only available if /Edit is specified. See /Edit/ |
| /Table | If specified, var2 must be the id of a simple table item containing the list to be displayed (one entry per row). |
See Common arguments for a description of the parameters not described here.
EDIT
SET dialog index EDIT row col caption var1 [ width height var2|* fg bg font ] [ /A|L|R ] [ /F[=PCAFS] ]
| var1 | The name of the variable or table (for multiline edit; /Multiline) to store the edit string in.
|
| var2 | This is an optional table setting advanced properties of the edit control (see below). If you don't need to set advanced properties, you may indicate so by supplying the asterisk, "*", instead of a table.
|
Advanced properties of the EDIT control
A large number of advanced properties (i.e., settings) for an edit control may be set using a parameter table supplied as the var2 argument (see above). If you don't need these advanced features, you may indicate so by supplying an asterisk, "*", instead of a table.
The parameter table used for setting the advanced properties of an edit control must be an extended table containing exactly two string columns that, in turn, must be named "parameter" and "string". You may create such a table using the following STx statement:
#tab := new table * * /E string:parameter string:string
For each advanced property to set, you need to store a respective entry (i.e., row) in the table, and tag the entry (see Tagging table entries). Each such entry has to contain the name of the respective property in the name column, and its desired value in the string column.
The following advanced parameters are supported:
| Parameter | Value(s) |
|---|---|
| name field | string field |
append
|
on or off
|
breakpoints
|
on or off
|
caret
|
on or off
|
clear
|
If specified, clears the contents of the edit control. There is no argument to this parameter.
Example: |
colorOutput
|
sets the color for the shell output (only for edit controls with a type property set to cli)
|
colorInput
|
sets the color for the input (only for edit controls with a type property set to cli)
|
colorPrompt
|
sets the color for the prompt (only for edit controls with a type property set to cli)
|
colorBackground
|
Sets the color for the background (only for edit controls with a type property set to cli)
|
colorCaret
|
Sets the color (only for edit controls with a type property set to cli)
Example: |
currentLine
|
lineNumber
|
lineNumbers
|
on or off
|
outputMode
|
The following values are supported:
Example: |
outputLineLimit
|
If set to a number higher than zero, the control will limit the number of lines displayed. This is particularly useful when using a "log" type edit box.
|
prompt
|
the CLI prompt, e.g. "> " or "# "
|
readonly
|
on or off
|
showLine
|
lineNumber
|
type
|
The following values are supported:
|
waitforinput
|
If set to "on", key messages will be passed on to the shell without the CLI processing them in any other way. This can, e.g., be used by the console getc command to wait for the user to input a character. When the key processing should continue, this parameter should be set to "off".
|
Note again that parameters you supply in the control table are ignored unless tagged.
Important: Once a setting has been applied, the tag will be removed. So, if you want to change the setting at a later time, you need to tag it again.
Additional options for the EDIT control
| Option | Meaning |
|---|---|
/Integer or /Number
|
Input field must contain a valid floating-point number (/Number) or an integer (/Integer), or a numeric expression of the respective type; expressions are evaluated before assigned to var1 (not applicable/available if var1 is a table).
|
/Password
|
Input is hidden; an asterisk, "*" is displayed for each entered character
|
/Multiline
|
Allow multiline input. |
/Keystroke
|
Send UPDATE message to shell for each entered character; otherwise the update message is only sent if the input is completed (another control is selected).The enter key is a special case; for /Multiline edit boxes, the enter key is used for line breaks, whilst for single line edit boxes, the enter key sends a COMMAND message (since STx version 3.6.0). Note that the enter key for a single line edit box also sends the same command as the default button (if one is defined - see BUTTON).
|
/F[=PCAFS]
|
If no modifier is specified, all keys are forwarded. Otherwise, the listed modifiers will come into effect. Any combination of the modifiers is allowed. The modifiers have the following meaning:
|
See Common arguments for a description of the parameters not described here.
GROUPBOX
SET dialog index GROUPBOX row col text [ * w h * fg bg font [first last]]
The groupbox control draws a frame around the area row/col, row+h/col+w, or around the specified controls first to last. If the controls first and last are specified, they must already be defined. In this case, row and col are used as margins (row for the top/bottom margin, col for the left/right margin) and not as positions. The caption is displayed inside the top line of the frame.
See Common arguments for a description of the parameters not described here.
LISTBOX
SET dialog index LISTBOX row col text var1 width height var2 [fg bg font] [ /Table [ /X ]][ /A|L|R ]
With commands containing the option /Read, the selection status is copied to the tag flags of the table entries, but the entry content remains unchanged. Dialog commands with the option /Write write both table data and selection status to the control. Table entries are displayed in show format (see the SET TABLE CONFIG command in Configuring a table field).
| var1 | The name of the variable to store the index or the counter in. |
| var2 | The name of a table item (/Table) or variable containing a blank separated list of items. |
/Table
|
You must specify this option if var2 is the name of a table containing the list items. |
/X
|
The option /X stands for eXtended selection. Multiple items may be selected, and var1 is set to the number of selected items. This option is only applicable with the /Table option. If this option is not specified, only one item may be selected and, var1 contains the index of the selected item.
|
See Common arguments for a description of the parameters not described here.
LISTVIEW
SET dialog index LISTVIEW row col text var1 w h var2 [fg bg font] /T [ /A|L|R ] [ /E ] [ /F[=PCAFS] ] [ /R=n ]
The LISTVIEW control is an enhanced variant of LISTBOX (q.v.). It displays each table field in a separate column and has a built-in function for sorting tables. The data exchange is implemented in the same way as for the LISTBOX control. Rows which are tagged in the table are used to initialize listview row selection, after which the table parameter's tags reflect the listview's selection.
| var1 | The name of the index (single selection) or counter variable (extended selection). |
| var2 | The name of the extended table item containing list items |
/T
|
This is a mandatory and therefore not an option! |
/X
|
X stands for eXtended selection. If specified, more than one entry can be selected at one time. See LISTBOX for details.
|
/Header
|
If specified, column headers are displayed. Note that if you do not configure the var2 table, then the field ids are used for the header text. |
/Sort
|
If specified, column headers are displayed and can be used to sort the entries. |
/Grid
|
If specified, grid lines are displayed between rows and columns |
/J
|
If specified, columns are automatically sized to fit their widest entry. |
/Centervertically
|
If specified, the selected entry is automatically centered vertically. |
/E
|
If this flag is not set on creation, the ListView will not be editable regardless of the connected tables display attributes. See the example script editabletable.sts for a complete example.
|
/F[=PCAFS]
|
If no modifier is specified, all keys are forwarded.
Any combination of the modifiers is allowed. The modifiers have the following meaning:
|
/R=n
|
If specified, n determines the maximum number of lines of text which can be displayed in the listview. |
See Common arguments for a description of the parameters not described here. The ListView sends messages when it's data has changed.
Use the SET dialogItem listviewIndex STARTEDIT command to programmatically start editing a cell in a LISTVIEW.
Note that a lot of the listview's configuration is read from the var2 table. You can configure the table using the SET TABLE CONFIG command.
[macro TestListView]
// create table data
#t := new table * /E * string:s1 string:s2
if '$#t[?]' != 'table' em -1 ; failed to create the table
$#t config s1 1 1 1 %s 0 'heading1' * 0 1
$#t config s2 1 1 1 %s 0 * 0 1 // no heading specified. field name will be used
for #i := 0 to $#i < 100 step #i := int $#i + 1
$#t * s1 's1str$#i' s2 's2str$#i'
end
// create the dialog item
#dlg := $(createmenu frame * ListView Text Dialog)
#map := CDlgMap $#dlg
$#dlg $($#map ci ok) button 0 0 '&OK' * 10 1
$#dlg $($#map ci cancel) button 0 10 '&Cancel' * 10 1
$#dlg $($#map ci) listview 1 0 #i 20 10 $#t /X /J /Header /Sort /Center
// update dialog controls
$#dlg * /Write
// begin the modal mode
domodaldialog begin $#dlg
$#dlg 1 focus
do forever // enter message loop
// update the control
$#dlg * /Write
// get next dialog message
domodaldialog loop $#dlg $($#map ci ok) $($#map ci cancel)
// id and parameter only are returned
readvar result #id #par
// update the variables
$#dlg * /Read
// process messages
if '$#id' == COMMAND then
#ctl := set $($#map cn $#par)
if '$#ctl' == 'ok' || '$#ctl' == 'cancel'then
break // leave message loop
end
end
end
domodaldialog end // end modal mode
// clean up
delete $#t $#dlg $#map
exit
A further example can be found in the example script file editabletable.sts.
PROGRESS
SET dialog index PROGRESS row col text var1 w h var2 [fg bg font][ /A|L|R ]
The progress control can be used to display the progress of a process. It could also be used to simulate a level-meter or other value displays. The position (fill status) of a progress control is updated on each command specifying the option /Write. If a hash '#' is used in place of var2, the default range (0-100) is used. You can connect a value item to a progress control using the command SET dialog index INPUT output. If the user clicks the progress bar, the message VALUE is generated.
| var1 | The name of the position variable. |
| var2 | The name of the range variable (var2 = minimum maximum). |
/Horizontal or /Vertical
|
A horizontal or vertical progress bar. |
/Smoothfill
|
Use smooth filling instead of blocked filling. |
See Common arguments for a description of the parameters not described here.
RADIOBUTTON
SET dialog index RADIOBUTTON row col text [var1|* w h * fg bg font] [ /A|L|R ]
The radio buttons are the only controls where one variable is bound to multiple controls. A new radio button group is started when a variable name var1 is specified. For all other radio buttons of the group the argument var1 must be set to '*'. The value of var1 is set to activeindex-groupstartindex, where groupstartindex is the index of the first radio button of a group and activeindex is the index of the activated radio button of the same group. Only one button in the group can be activated at one time.
| var1 | The name of button index variable (only for the first button in the group). |
See Common arguments for a description of the parameters not described here.
Using radio buttons may lead to problems because the function searching for the first button in a group does not always work correctly. It only works if no other control (e.g. a groupbox or a static) is placed between the buttons of the group.
SLIDER
SET dialog index SLIDER row col text var1 width height var2 [fg bg font] [ /A|L|R ]
Slider controls can be used to enter values by setting the slider position and/or the display values (similar to progress controls). Normally the slider position is defined by one value. If option /2 is specified the slider can be used to select a range. Optionally, a scale can be displayed (option /Scale with tickdistance for var2). If a hash character (#) is used in place of var2, the default range (0-1000) is used.
| var1 | The name of the position (var1 = pos) or selection variable (var1 = min max).
|
| var2 | The name of the range variable (var2 = minimum maximum tickdistance).
|
/Horizontal or Vertical
|
Make the slider horizontal or vertical |
/Scale=pos
|
This option controls where the ticks are placed. The value of pos can be set to Above, Below, Left, Right, Both or None.
|
/2
|
This option means that the slider has only two values, minimum and maximum. Otherwise a position is selected. |
See Common arguments for a description of the parameters not described here.
SPIN
SET dialog index SPIN row col text var1 width height var2 [fg bg font] [ /A|L|R ]
The spin control is a button with two arrows (horizontal: left/right, vertical: up|down) which increment (right/up) or decrement (left/down) the position variable in steps of stepwidth. If a hash character (#) is used in place of var2, the default range (0-100) and stepwidth (10) are used.
| var1 | The name of the position variable. |
| var2 | The name of the range variable (var2 = minimum maximum stepwidth).
|
/Horizontal or /Vertical
|
Horizontal or vertical spin button. |
See Common arguments for a description of the parameters not described here.
STATIC
SET dialog index STATIC row col text [ *|var1 width height * fg bg font] [ /L|R|C ]
Note that it is not possible to connect a value item to a static control using the command SET dialog index INPUT output.
| text | The text to display in the static control. |
| var1 | An optional variable to be used instead of text. If specified, the static's caption can be updated set to the content of var1 by using the option /Write. Note that you can update the text even if you do not use a variable, by using the SET dialog $#controlIndex * 'the new static text' command.
|
| /L, /R, or /C | Set the caption text alignment inside the static control. |
See Common arguments for a description of the parameters not described here.
You can display an image in a static control using the SET dialog BITMAP command.
TREEVIEW
SET dialog index TREEVIEW row col text var1 width height var2 [fg bg] [ /A|L|R ]
| var1 | The name of table item for multiple selected elements (/X), or the name of shell variable for single selected item. |
| var2 | The name of the file item containing the XML tree. |
/X
|
Multiple items can be selected ("eXtended selection") |
/Expand
|
Expands the whole tree (without this option, the tree is only expanded up to the selected element) |
/V
|
Enable the use of the XML attribute Expand. This attribute is set to 1 when a branch of the tree is expanded, and removed when the branch is collapsed. If the option /Expand is also used, the whole tree is expanded and all expanded branches have the Expand attribute set to 1.
|
With commands containing the option /Read, the selection status is copied to the tag flags of the table entries, but the entry content remains unchanged. Dialog commands with the option /Write write table data and selection status to the control. Table entries are displayed in show format (see SET TABLE … CONFIG).
See Common arguments for a description of the parameters not described here.
