Programmer Guide/Shell Items/Dialog/SET DIALOG

Use the SET commands to design and control an existing dialog item.

See DIALOG Item Attributes for a list of item attributes. See Dialog Controls for the individual control documentation (e.g. Buttons, Edit boxes etc).

Data Exchange

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

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	HIDDEN|VISIBLE|ENABLED|*). If NOWINDOW is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc).
style	MAXIMIZE|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|layout	Recalculate the dialog window size, including (/Layout) or ignoring (/layout) hidden controls (case sensitive!).

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

E.g. SET $#dlg TITLE '$#title'

LAYOUT

SET dialog LAYOUT font left top right bottom

Set the dialog margins and default font. The default font is used for all controls created later. The margins are specified in 'number of characters' (like the control position and size). Note that each control can have an individual font overriding this default font (see SET dialog index controltype below).

font	The default font (see Fonts and Font Arguments for details).
left, right	right side (in characters).
top, bottom	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 …
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.
itemX	The menu items.
tableItem	A table

SETPOPUP

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

Activate|deactivate and/or set|clear the check status of menu items indexX. The items may be located in different menus.

DELPOPUP

SET dialog DELPOPUP|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.

Dialog Control Configuration

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

Set mode and attributes of a control. The option /N=count can be used to apply settings to all controls in the range index to index+count-1. The options /Read and /Write can be specified to perform the data-exchange (see 'SET dialog mode' for a description) for the addressed control(s) only. The color and font specifications are described in the appendix. Color settings are only applied to controls of type static and to the caption of controls with a separate caption window!

index

The index of the (first) control.

count

The number of controls (>= 1, default = 1).

mode

The control mode (HIDDEN|VISIBLE|ENABLED|TITLE).

title

The control caption.

font

The control font. See Fonts and Font Arguments for details.

fg, bg

The font (fg) and background (bg) color. Either one of the color keywords or an RGB value.

The mode TITLE is defined for compatibility to earlier versions only and has the same meaning as * (do not change mode, just set attributes).

FOCUS

SET dialog FOCUS
SET dialog index FOCUS

Give a particular control the input focus. All keyboard input is then redirected 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 its value is less than zero, the focus is set to the dialog window.

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, the 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). See Bitmaps for Dialog Controls, Icons, Toolbar Buttons for images available in STx.

The SET dialog index BITMAP command only works once a dialog has been created, i.e. after domodaldialog begin.

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.