Programmer Guide/Shell Items/Dialog/Dialog Controls

The STx dialog implementation supports the control types listed below.

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.
/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

Format2: /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

Available 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/ for details.
/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 var₂ 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: $#tSettings parameter clear /T
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: $#tSettings * parameter colorBackground string hlgray /tExample: $#tSettings * parameter colorPrompt string 0:250:128 /t
currentLine	lineNumber
lineNumbers	on or off
outputMode	The following values are supported: overwrite - overwrites old content with new content append - appends new content to old content overwriteLastLine - overwrites the last line newLine - which appends new data on a new line Example: $#tSettings * parameter outputMode string overwriteLastLine /T
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: edit - a normal edit box log - read-only, append mode, caret off code - read-only, breakpoints on, linenumbers on, caret off and uses STx syntax highlighting cli - the command line interface
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-pont number (/Number) or an integer (/Integer/<ocde>), 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: P - printable keys C - control keys (ctrl, shift, alt, alt-gr) A - action keys (left, right, esc, return etc. F - function keys (F1-F24) S - sticky keys (caps lock, num lock, scroll lock)

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 or counter variable.
var2	The name of the extended table item containing list items
/T	This is a mandatory 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: P - printable keys C - control keys (ctrl, shift, alt, alt-gr) A - action keys (left, right, esc, return etc.) F - function keys (F1-F24) S - sticky keys (caps lock, num lock, scroll lock)
/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.

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 var₂ 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 var₂, 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 var₁ is specified. For all other radio buttons of the group the argument var₁ must be set to '*'. The value of var₁ 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 var₂). If a hash character (#) is used in place of var₂, 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 var₂, 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 ]

You can 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.

var₁

An optional variable to be used instead of text. If specified, the static's caption can be updated set to the content of var₁ 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.

/Left|Right|Center

Set the caption text alignment inside the static control.

See Dialog Controls for a description of 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 ]

var₁

The name of table item for multiple selected elements (/X), or the name of shell variable for single selected item.

var₂

The name of the file item containing the XML tree.

/X

Multiple items can be selected

/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 writes table data and selection status to the control. Table entries are displayed in show format (see SET TABLE).

See Dialog Controls for a description of parameters not described here.