Programmer Guide/Shell Items/Dialog/SET DIALOG: Difference between revisions
(55 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
{{DISPLAYTITLE:{{SUBPAGENAME}}}} | {{DISPLAYTITLE:{{SUBPAGENAME}}}} | ||
Use the <code> | {{Dialog Item}} | ||
Use the [[Programmer_Guide/Shell_Items/Dialog/NEW_DIALOG|<code>NEW DIALOG</code>]] command for creating a [[Programmer_Guide/Shell_Items/Dialog|<code>DIALOG</code> shell item]]. Then apply the <code>SET <var>dialog</var></code> commands described here. | |||
== Data Exchange== | == Data Exchange== | ||
SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write | SET <var>dialog</var> [ <var>ctrlId</var> ] /Read|Write | ||
<var>dialog</var> [ <var>ctrlId</var> ] /Read|Write | |||
Exchange data between the dialog controls and their respective variables. | Exchange data between the dialog controls and their respective variables. | ||
Line 13: | Line 12: | ||
{|class="keinrahmen" | {|class="keinrahmen" | ||
| <var>ctrlId</var> | | <var>ctrlId</var> | ||
| | | colspan="2" | 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. | ||
|- | |- | ||
| | | rowspan="3" | <code>/Read</code> or <code>/Write</code> | ||
| colspan="2" | The direction of data exchange (as seen from the shell). | | colspan="2" | The direction of data exchange (as seen from the shell). | ||
|- | |- | ||
Line 22: | Line 21: | ||
| <code>/Write</code> || sets the values of the controls. | | <code>/Write</code> || 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 <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ] | |||
See [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Setting_the_attributes_of_a_control|Setting the attributes of a control]] on this page. | |||
== Dialog Window Control == | == Dialog Window Control == | ||
Line 29: | Line 32: | ||
=== Dialog only === | === Dialog only === | ||
SET <var>dialog mode</var> [<var>style xpos ypos width height</var>] [/Centered /Foreground /Dialog /View /Layout|layout] | SET <var>dialog</var> <var>mode</var> [<var>style</var> <var>xpos</var> <var>ypos</var> <var>width</var> <var>height</var>] [/Centered /Foreground /Dialog /View /Layout|layout] | ||
The dialog is enabled (window is created) and the command is forwarded to the display. | The dialog is enabled (window is created) and the command is forwarded to the display. | ||
Line 35: | Line 38: | ||
=== Dialog and graphs === | === Dialog and graphs === | ||
SET <var>dialog mode</var> [/Read|Write] | SET <var>dialog</var> <var>mode</var> [/Read|Write] | ||
The dialog window mode is set. Other arguments/options are ignored if specified. | The dialog window mode is set. Other arguments/options are ignored if specified. | ||
Line 42: | Line 45: | ||
{|class="keinrahmen" | {|class="keinrahmen" | ||
| <var>mode</var> | |||
| The dialog window mode | | The dialog window mode, one out of <code>NOWINDOW</code>, <code>HIDDEN</code>. <code>VISIBLE</code>, <code>ENABLED</code> and <code>*</code>). If <code>NOWINDOW</code> is used, the dialog window is destroyed and the dialog must be reconfigured (i.e. controls must be created etc). | ||
|- | |- | ||
| <var>style</var> | |||
|The window style (<code>MINIMIZE</code> | | The window style (<code>MINIMIZE</code>, <code>MAXIMIZE</code> or <code>RESTORE</code>). | ||
|- | |- | ||
| <var>xpos</var> | |||
|The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin. | |The x-axis position in pixels of the upper left corner of the dialog relative to the desktop origin. | ||
|- | |- | ||
| | | <var>ypos</var> | ||
|The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin. | | The y-axis position in pixels of the upper left corner of the dialog relative to the desktop origin. | ||
|- | |- | ||
| <var>width</var> | |||
| The width of the dialog in pixels. | | The width of the dialog in pixels. | ||
|- | |- | ||
| <var>height</var> | |||
|The height of the dialog in pixels. | | The height of the dialog in pixels. | ||
|- | |- | ||
| <code>/Centered</code> | |||
| Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored. | | Center the display to the screen in which the mouse is currently. <var>xpos</var>, <var>ypos</var>, <var>width</var> and <var>height</var> are ignored. | ||
|- | |- | ||
| <code>/Foreground</code> | |||
|Send the window to the front (make the window the topmost window). | | Send the window to the front (make the window the topmost window). | ||
|- | |- | ||
| <code>/Dialog=<var>pos</var></code> | |||
| Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code> | | Set dialog position inside the display (relative to graphs); changing the position is only possible if the dialog is non-floating. The following values for <var>pos</var> are allowed: <code>ABOVE</code>|<code>BELOW</code>|<code>LEFT</code>|<code>RIGHT</code> | ||
|- | |- | ||
| <code>/View=<var>view</var></code> | |||
| Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated). | | Set window view mode to <var>view</var> ('<code>WINDOW</code>' is a normal window, or '<code>FULLSCREEN</code>' = display takes up whole screen (for displays of type 'frame' only) or '<code>ALWAYSONTOP</code>' = the display remains on top, even when other windows are activated). | ||
|- | |- | ||
| <code>/Layout</code> or <code>/layout</code> | |||
| Recalculate the dialog window size, including (/Layout) or ignoring (/layout) hidden controls (case sensitive | | Recalculate the dialog window size, including (<code>/Layout</code> - note the upper-case "L") or ignoring (<code>/layout</code> - note the lower-case "l") hidden controls (this is one of our very few case-sensitive option letters). | ||
|} | |} | ||
Line 84: | Line 87: | ||
Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> in quotes, since otherwise, only the first word of the string is interpreted as the title (the rest being additional arguments, which are ignored). | Set the caption of the display owning the <var>dialog</var> to <var>title</var>. The caption can be an empty string. Note that it is advisable to surround the string <var>title</var> 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' | |||
=== <code>LAYOUT</code> === | === <code>LAYOUT</code> === | ||
SET <var>dialog</var> LAYOUT <var>font left top right bottom</var> | SET <var>dialog</var> LAYOUT <var>font</var> <var>left</var> <var>top</var> <var>right</var> <var>bottom</var> | ||
Set the dialog margins and default font. The default font | 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 <var>n</var>, it will be roughly as wide as a string of <var>n</var> 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 <code>SET dialog index controltype</code> below). | ||
{|class="keinrahmen" | {|class="keinrahmen" | ||
| <var>font</var> | |||
| The default font (see Fonts and Font Arguments for details). | | The default font (see Fonts and Font Arguments for details). | ||
|- | |- | ||
| <var>left</var>, <var>right</var> | |||
| The margin on the left | | The margin on the left/right side (in characters). | ||
|- | |- | ||
| <var>top</var>, <var>bottom</var> | |||
|The margin on the top | | The margin on the top/bottom (in characters). | ||
|} | |} | ||
== Dialog Context Menus == | == 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 <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> 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 <code>SET display ADDPOPUP</code>. | 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 <code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMSTAT]]</code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages| and ]]<code>[[Programmer Guide/Shell Items/Dialog/DISPLAY and DIALOG Messages|CMITEM]]</code> in a message handler). Context menus are identified by an id string (specified in the <code>ADDPOPUP /X</code> command) or a zero-based index (in the same order as the <code>ADDPOPUP</code> 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 <code>[[Programmer_Guide/Shell_Items/Display/SET_DISPLAY#ADDPOPUP|SET display ADDPOPUP]]</code>. | ||
=== <code>ADDPOPUP</code> === | === <code>ADDPOPUP</code> === | ||
SET <var>dialog</var> ADDPOPUP /X <var>id item<sub>1</sub> item<sub>2</sub></var> … <var>item<sub>n</sub></var> | SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>item<sub>1</sub></var> <var>item<sub>2</sub></var> … <var>item<sub>n</sub></var> | ||
SET <var>dialog</var> ADDPOPUP /X <var>id tableitem</var> /Table | SET <var>dialog</var> ADDPOPUP /X <var>id</var> <var>tableitem</var> /Table | ||
Add a context menu to the dialog. | Add a context menu to the dialog. | ||
{|class="keinrahmen" | {|class="keinrahmen" | ||
| <var>id</var> | |||
| 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. | | 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. | ||
|- | |- | ||
| <var>item<sub>n</sub></var> | |||
| The menu items. | | The menu items. | ||
|- | |- | ||
| | | <var>tableItem</var> | ||
|A table | | A table | ||
|} | |} | ||
=== <code>SETPOPUP</code> === | === <code>SETPOPUP</code> === | ||
SET <var>dialog</var> SETPOPUP /X <var> | SET <var>dialog</var> SETPOPUP /X <var>index<sub>1</sub></var> [ … <var>index<sub>n</sub></var> ] [ /Enable|Disable ] [ /Check|Uncheck ] | ||
Activate | Activate or deactivate and/or set or clear the check state of menu items <var>index<sub>1</sub></var> to <var>index<sub>n</sub></var>. The items may be located in different menus. | ||
=== <code>DELPOPUP</code> === | === <code>DELPOPUP</code> === | ||
SET <var>dialog</var> DELPOPUP | SET <var>dialog</var> DELPOPUP /X | ||
SET <var>dialog</var> DELETEPOPUP /X | |||
Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index. | Delete all context menus. Note that you can replace an existing popup by just calling <code>ADDPOPUP</code> again with the same index. | ||
Line 142: | Line 147: | ||
Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message. | Show the contextmenu with index or id <var>menuId</var>. This command is usually called in response to a <code>CMSTAT</code> message. | ||
== Editing cells in a <code>LISTVIEW</code> == | |||
SET <var>dialogItem</var> <var>listviewIndex</var> STARTEDIT <var>col</var> <var>row</var> | |||
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. <var>col</var> and <var>row</var> are zero-based indices addressing the field and entry. See the example script <code>editabletable.sts</code> for a complete example. | |||
== Dialog Control Configuration == | == Dialog Control Configuration == | ||
=== Setting attributes === | === Setting the attributes of a control === | ||
SET <var>dialog index mode</var> [ <var>title font fg bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ] | SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ] | ||
<var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>fg</var> <var>bg</var> ] [ /Read|Write ] [ /N=<var>count</var> ] | |||
Set mode and attributes of a control. | Set mode and attributes of a control. | ||
;/N=<var>count</var>: apply settings to ''all'' controls in a range <var>index</var> to <var>index</var>+<var>count</var>-<samp>1</samp> | |||
;/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 [[Programmer_Guide/Shell_Items/Dialog/SET_DIALOG#Data_Exchange|Data Exchange]] section on this page. This data exchange will take place for the addressed control(s) only (as opposed to <code>SET dialog mode</code> which transfers data to/from ''all'' controls of the dialog). | |||
{|class="keinrahmen" | {|class="keinrahmen" | ||
| <var>index</var> | |||
| The index of the (first) control. | | The index of the (first) control. | ||
|- | |- | ||
| <var>count</var> | |||
| The number of controls (>= 1, default = 1). | | The number of controls (>= 1, default = 1). | ||
|- | |- | ||
| <var>mode</var> | |||
| The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>). | | The control mode (<code>*</code>, <code>HIDDEN</code>, <code>VISIBLE</code>, <code>ENABLED</code> or <code>TITLE</code>). | ||
The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes). | The <var>mode</var> <code>TITLE</code> is defined for compatibility to earlier versions only. It has the same meaning as <code>*</code> (do not change mode, just set attributes). | ||
|- | |- | ||
| <var>title</var> | |||
| The control caption. | | The control caption. | ||
|- | |- | ||
| <var>font</var> | |||
| The control font. See Fonts and Font Arguments for details. | | The control font. See [[Programmer_Guide/General_Descriptions/Fonts_and_Font_Argument_Format|Fonts and Font Arguments]] for details. | ||
|- | |- | ||
| <var>fg</var>, <var>bg</var> | |||
|The | |The foreground (<var>fg</var>) and background (<var>bg</var>) color. You may use either a color keyword or an RGB value for each of <var>fg</var> and <var>bg</var>. | ||
|} | |||
The color and font specifications are described in the appendix. Note that color settings are applied to controls of type <code>static</code>, and to the caption of controls with a separate caption, window only. | |||
SET <var>dialog</var> <var>index</var> <var>mode</var> [ <var>title</var> <var>font</var> <var>row</var> <var>col</var> <var>width</var> <var>height</var> ] [ /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 | |||
{|class="keinrahmen" | |||
| <var>row, col</var> | |||
| new control position (use -1 or * if a value should not be changed) | |||
|- | |||
| <var>width, height</var> | |||
| new control size (use -1 or * if a value should not be changed) | |||
|} | |} | ||
Line 176: | Line 208: | ||
SET <var>dialog</var> FOCUS | SET <var>dialog</var> FOCUS | ||
SET <var>dialog index</var> FOCUS | SET <var>dialog</var> <var>index</var> FOCUS | ||
Give a particular control the input focus. All keyboard input is then | 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. | |||
=== <code>INPUT</code> === | === <code>INPUT</code> === | ||
SET <var>dialog index</var> INPUT <var>output</var> | SET <var>dialog</var> <var>index</var> INPUT <var>output</var> | ||
Connect dialog control with a data output. | Connect dialog control with a data output. | ||
Line 195: | Line 229: | ||
SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /B ] | SET dialog index BITMAP <var>buttonId</var>|<var>bitmapFile</var> [ <var>tooltipText</var> ][ /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, | 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 <code>/B</code>) can be used. | ||
{| class="keinrahmen" | |||
| valign="top" | <var>index</var> | |||
| The 'button' or 'static' dialog control index. | |||
|- | |||
| valign="top" | <var>buttonId</var> | |||
| 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 | |||
|- | |||
| valign="top" | <var>bitmapFile</var> | |||
| The name of a bitmap file. | |||
|- | |||
| valign="top" | <var>tooltipText</var> | |||
| 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. | |||
|- | |||
| valign="top" | <code>/B</code> | |||
| If the option <code>/B</code> is specified, the <var>buttonId</var> references a toolbar button (rather than a bitmap resource). [[Programmer_Guide/General_Descriptions/Bitmaps_for_Dialog_Controls,_Icons,_Toolbar_Buttons|Bitmaps for Dialog Controls, Icons, Toolbar Buttons]] shows all images available in {{STX}}. | |||
|} | |||
The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>. | The <code>SET dialog index BITMAP</code> command only works once a dialog has been created, i.e. after <code>domodaldialog begin</code>, since it modifies the style of an existing window. | ||
== Dialog Control Creation == | == Dialog Control Creation == | ||
You can create a control in a dialog using the <code>SET dialog index controlType</code> 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 <code>SET dialog mode</code> command. See [[ | You can create a control in a dialog using the <code>SET dialog index controlType</code> 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 <code>SET dialog mode</code> command. See [[Programmer_Guide/Shell_Items/Dialog/Dialog_Controls|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. | The number of controls per dialog is limited to 255 due to the MFC implementation. |
Latest revision as of 09:41, 24 September 2019
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.
Contents
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 index1 to indexn. 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 | 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.