Programmer Guide/Shell Items/Dialog/SET DIALOG

Dialog Item
NEW	SET	CONTROLS	ATTRIBUTES	MESSAGES	EXAMPLES

Use the NEW DIALOG command for creating a DIALOG shell item. Then apply the SET dialog commands described here.

Data Exchange

SET dialog [ ctrlId ] /Read|Write
dialog [ ctrlId ] /Read|Write

Exchange data between the dialog controls and their respective variables.

ctrlId	The optional id of an existing control. If specified, the exchange only takes place for this control. Otherwise, all data for all controls is exchanged.
/Read or /Write	The direction of data exchange (as seen from the shell).
	/Read	reads the data out of the control into the shell variable.
	/Write	sets the values of the controls.

If you want to read or write only a subset of connected dialog controls, you may do so by using the command

SET dialog index mode [ title font fg bg ] [ /Read|Write ] [ /N=count ]

See Setting the attributes of a control on this page.

Dialog Window Control

Set the display and/or dialog window mode, style position and/or size, and configure the dialog. If the option /Read (dialog → shell) or /Write (shell → dialog) is specified, a data exchange between the dialog controls and the variables and items bound to the controls is performed. The mode command has different functions for displays with only a dialog and for displays containing a dialog and graphs.

Dialog only

SET dialog mode [style xpos ypos width height] [/Centered /Foreground /Dialog /View /Layout|layout]

The dialog is enabled (window is created) and the command is forwarded to the display.

Dialog and graphs

SET dialog mode [/Read|Write]

The dialog window mode is set. Other arguments/options are ignored if specified.

Options

mode	The dialog window mode, one out of NOWINDOW, HIDDEN. VISIBLE, ENABLED and *). If NOWINDOW is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
style	The window style (MINIMIZE, MAXIMIZE or RESTORE).
xpos	The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
ypos	The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin.
width	The width of the dialog in pixels.
height	The height of the dialog in pixels.
/Centered	Center the display to the screen in which the mouse is currently. xpos, ypos, width and height are ignored.
/Foreground	Send the window to the front (make the window the topmost window).
/Dialog=pos	BELOW|LEFT|RIGHT
/View=view	Set window view mode to view ('WINDOW' is a normal window, or 'FULLSCREEN' = display takes up whole screen (for displays of type 'frame' only) or 'ALWAYSONTOP' = the display remains on top, even when other windows are activated).
/Layout or /layout	Recalculate the dialog window size, including (/Layout - note the upper-case "L") or ignoring (/layout - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters).

Dialog Window Configuration

TITLE

SET dialog TITLE title

Set the caption of the display owning the dialog to title. The caption can be an empty string. Note that it is advisable to surround the string title in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored).

Code example:

SET $#dlg TITLE 'Der Wiener Schnitzel mit de Lavignetten und de Sauerkraut'

LAYOUT

SET dialog LAYOUT font left top right bottom

Set the dialog margins and the default font. The default font will be used for all newly created controls (the existing ones will keep their respective font). The unit for specifying margins is characters, just like the control position and size. So, if you specify a margin of n, it will be roughly as wide as a string of n characters would be ("roughly", because with proportional fonts, the single characters are of different widths). Note that each control may be assigned an individual font, thereby overriding this default font (see SET dialog index controltype below).

font	The default font (see Fonts and Font Arguments for details).
left, right	The margin on the left/right side (in characters).
top, bottom	The margin on the top/bottom (in characters).

Dialog Context Menus

It is possible to attach a set of context menus to each dialog. The displaying of the context menu is controlled by the programmer (normally by processing the messages CMSTAT and CMITEM in a message handler). Context menus are identified by an id string (specified in the ADDPOPUP /X command) or a zero-based index (in the same order as the ADDPOPUP commands). Note: If the option /X is not supplied in a command, the menu handling command is forwarded to the display and used for popup-menu handling. For a detailed description of menu item formats and menu item index computation see command SET display ADDPOPUP.

ADDPOPUP

SET dialog ADDPOPUP /X id item1 item2 … itemn
SET dialog ADDPOPUP /X id tableitem /Table

Add a context menu to the dialog.

id	The id of the context menu in the dialog (a dialog can have more than one context menu). This is not shown in the menu itself.
itemn	The menu items.
tableItem	A table

SETPOPUP

SET dialog SETPOPUP /X index1 [ … indexn ] [ /Enable|Disable ] [ /Check|Uncheck ]

Activate or deactivate and/or set or clear the check state of menu items index₁ to index_n. The items may be located in different menus.

DELPOPUP

SET dialog DELPOPUP /X
SET dialog DELETEPOPUP /X

Delete all context menus. Note that you can replace an existing popup by just calling ADDPOPUP again with the same index.

CONTEXTMENU

SET dialog CONTEXTMENU menuId

Show the contextmenu with index or id menuId. This command is usually called in response to a CMSTAT message.

Editing cells in a LISTVIEW

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.

Dialog Control Configuration

Setting the attributes of a control

SET dialog index mode [ title font fg bg ] [ /Read|Write ] [ /N=count ]
dialog index mode [ title font fg bg ] [ /Read|Write ] [ /N=count ]

Set mode and attributes of a control.

/N=count

apply settings to all controls in a range index to index+count-1

/Read, /Write

request data being transferred from the dialog to the connected shell variable/item (Read), or from the connected shell variable/item to the dialog control (Write) - for a description, see the Data Exchange section on this page. This data exchange will take place for the addressed control(s) only (as opposed to SET dialog mode which transfers data to/from all controls of the dialog).

index	The index of the (first) control.
count	The number of controls (>= 1, default = 1).
mode	The control mode (*, HIDDEN, VISIBLE, ENABLED or TITLE). The mode TITLE is defined for compatibility to earlier versions only. It has the same meaning as * (do not change mode, just set attributes).
title	The control caption.
font	The control font. See Fonts and Font Arguments for details.
fg, bg	The foreground (fg) and background (bg) color. You may use either a color keyword or an RGB value for each of fg and bg.

The color and font specifications are described in the appendix. Note that color settings are applied to controls of type static, and to the caption of controls with a separate caption, window only.

SET dialog index mode [ title font row col width height ] [ /Read|Write ] /Layout|layout|Setposition

Set mode, caption, font, position and size of a control

/Layout

update position/size of the control and recompute dialog window layout

/layout

update position/size of the control and recompute dialog window layout, ignore hidden controls

/Setposition

update position/size of the control but do not recompute dialog window layout

row, col	new control position (use -1 or * if a value should not be changed)
width, height	new control size (use -1 or * if a value should not be changed)

FOCUS

SET dialog FOCUS
SET dialog index FOCUS

Give a particular control the input focus. All keyboard input is then directed to the control. This command can be used in setup or input dialogs to set the focus to the default input field after creating and displaying the dialog. If no index is specified or if its value is less than zero, the focus is set to the dialog window itself.

Note that this command only has an effect once the dialog has been enabled.

INPUT

SET dialog index INPUT output

Connect dialog control with a data output.

output

an SPU output or a value object

BITMAP

SET dialog index BITMAP buttonId|bitmapFile [ tooltipText ][ /B ]

Assign a bitmap to a button or a static control. The assigned bitmap is displayed in its original size and colors in the center of the control. If no bitmap is specified, any existing assignment is removed. Bitmaps can be read from bitmap files (*.BMP) or from the STx resource file. To identify a resource the name (or index) of a bitmap resource (no option) or a toolbar button (option /B) can be used.

index	The 'button' or 'static' dialog control index.
buttonId	The bitmap id or toolbar button id. See the "Bitmaps for Dialog Controls, Icons, Toolbar Buttons" topic in <GD> for a list of available b
bitmapFile	The name of a bitmap file.
tooltipText	If specified, this string will be displayed as a tooltip when the mouse hovers over the button. This parameter overrides any string associated with the bitmap (/b) in the resource file.
/B	If the option /B is specified, the buttonId references a toolbar button (rather than a bitmap resource). Bitmaps for Dialog Controls, Icons, Toolbar Buttons shows all images available in STx.

The SET dialog index BITMAP command only works once a dialog has been created, i.e. after domodaldialog begin, since it modifies the style of an existing window.

Dialog Control Creation

You can create a control in a dialog using the SET dialog index controlType commands defined below. All dialog controls must be created before the dialog is displayed for the first time. You can show and hide dialog controls once the dialog has been created with the SET dialog mode command. See Dialog Controls for a list of available controls and their individual creation syntax.

The number of controls per dialog is limited to 255 due to the MFC implementation.