Dialog Controls

Dialog Controls

The STx dialog implementation supports the following control types.

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

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 Dialog Controls for a description of parameters not described here.

You can 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 Dialog Controls for a description of 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|Number

Only available if /E 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 Dialog Controls for a description of 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

If specified, a table containing parameters to configure the edit control with. This must be an extended table created using the following command:

new table * * /E string:parameter string:string

The following parameters are supported:

append	off
breakpoints	off
caret	off
clear	If specified, clears the contents of the edit control. There is no parameter.Example: $#tSettings parameter clear /T
colorOutput	Sets the color for the shell output for edits of type cli.
colorInput	Sets the color for the input for edits of type cli.
colorPrompt	Sets the color for the prompt for edits of type cli.
colorBackground	Sets the color for the background for edits of type cli.
colorCaret	Sets the color for the caret for edits of type cli.Example: $#tSettings * parameter colorBackground string hlgray /tExample: $#tSettings * parameter colorPrompt string 0:250:128 /t
currentLine	lineNumber
lineNumbers	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 lineExample: $#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	"prompt string" E.g. "> " or "# "
readonly	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".

The parameters are ignored by the edit control unless the entry is tagged. Once applied, the tag is removed by the edit control, so you have to set the tag again if you want to change the parameter.

/Integer|Number

Input field must contain a valid float (/Number) or integer (/Integer) number or numeric expression; expressions are evaluated before assigned to var1 (not applicable/available for the table var1)

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

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 Dialog Controls for a description of 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 and row and col are used as margins (row = top|bottom, col = left|right) and not as positions. The caption is displayed inside the top line of the frame.

See Dialog Controls for a description of 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 writes table data and selection status to the control. Table entries are displayed in show format (see SET TABLE CONFIG).

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 can 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 can be selected and var1 contains the index of the selected item.

See Dialog Controls for a description of 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 a enhanced variant of the LISTBOX. 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. 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 Dialog Controls for a description of parameters not described here.

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

SET dialogItem listviewIndex STARTEDIT col row

Sets the dialog focus to the specified cell and enters edit mode. If the user presses ESC, Return or Enter, the control leaves edit mode. col and row are zero-based indices addressing the field and entry. See the example script editabletable.sts for a complete example.

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|Vertical

A horizontal or vertical progress bar.

/Smoothfill

Use smooth filling instead of blocked filling.

See Dialog Controls for a description of 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 Dialog Controls for a description of 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. A scale can optional be displayed and configured (option /Scale and value tickdistance of var2). If a hash '#' 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|Vertical

Make the slider horizontal or vertical

/Scale=pos

This option controls where the ticks are displayed. The value of pos can be set to Above|Below|Left|Right|Both|None.

/2

This option means that the slider has only two values, minimum and maximum. Otherwise a position is selected.

See Dialog Controls for a description of 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 '#' 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|Vertical

Horizontal or vertical spin button.

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

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.

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

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

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

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 & 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

x =	x	50% change of x position
	X	100% change of x position
	w | W	50% change of width
	W	100%change of width
	B	100% change of x position and width
y =	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:

<code>$#dlg $#index edit $#row $#col 'caption' $#tEdit $#width $#height /W=**ff</code>