Dialog Controls

From STX Wiki
< Programmer Guide‎ | Shell Items‎ | Dialog
Revision as of 10:24, 24 September 2019 by Jw (talk | contribs) (Dialog Control Resizing And Positioning)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search
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.

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

Dialog control button.png

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

Dialog control checkbox.png

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

Dialog control combobox.png

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

Dialog control edit.png

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: $#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-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:
  • 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

Dialog control groupbox.png

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

Dialog control listbox.png

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

Dialog control listview.png

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:

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

Dialog control progress.png

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

Dialog control spin.png

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

Dialog control static.png

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

Dialog control treeview.png

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.