DIALOG
DIALOG |
|
| Top Previous Next | |
Syntax:
DIALOG ADD,<element type>,<element name>, element description
DIALOG CLEAR, <element name>
DIALOG CLEARSEL, <element name>
DIALOG CLOSE
DIALOG CREATE,<title>,<top>,<left>,<width>,<height>, <styles>
DIALOG CURSOR , <cursor style>
DIALOG DISABLE, <element name>
DIALOG ENABLE, <element name>
DIALOG FOCUS, <element name>
DIALOG HIDE, <element name>
DIALOG POPUP, <items> <x>,<y>
DIALOG SELECT, <id>
DIALOG SET, <element name>, <value>
DIALOG SETPOS, <element name>,<top>,<left>,<width>,<height>
DIALOG SETTIP, <element name>,<text>
DIALOG SHOW {, <element name> }
[VDS6] DIALOG SHOWINFO, <element name>,<caption>,<text>,<icon type>
DIALOG SHOWMODAL
DIALOG SNAP, ON|OFF
DIALOG TITLE, <title>
Description:
DIALOG ADD adds a new dialog element to the currently selected dialog. For a list of element types and a description for each of them, see Dialog Elements.
DIALOG CLEAR clears the contents of <element name>.
DIALOG CLEARSEL clears the selected item in a list box element named <element name>.
DIALOG CLOSE sends a signal that the current dialog of the application should close. This will cause a CLOSE event to be generated. The effect is the same as clicking the close (X) button. The application will typically respond by saving information and then terminating.
| • | An application's main dialog will not be closed or destroyed until the application terminates. Therefore this command is not often used in the context of the main dialog. |
| • | If the current dialog is a child dialog then this command will cause the dialog to be closed. This would typically be used after processing events such as clicking OK or Cancel buttons, or the close button on the dialog. The command will cause a new CLOSE event to be generated, which could erroneously be acted upon by the main dialog event loop, so the event may be discarded using a while @event() / wend loop. |
DIALOG CREATE creates an empty dialog, which is initially hidden, having <title> in the title bar, and of the size specified. Elements are added to this dialog using DIALOG ADD, after which it is displayed using DIALOG SHOW. For more information see Creating Dialogs and Dialog Elements.
The <width> and <height> values specify the width and height of the usable area of the dialog window, the area in which it is possible to place dialog elements. The total width of the dialog is slightly larger than this value. The total height is the height value plus a small amount for the border, plus the title bar height, plus the menu height if a menu is defined. This means that you don't have to worry about calculating the size to take account of non-standard desktop settings (e.g. large fonts, desktop themes etc.) If the <top> value is specified as -1, the dialog is created in the center of the window.
One or more of the following styles may be used to set the properties of the dialog:
BALLOONTIPS [VDS6] |
Show tooltips as balloon tips. |
CLASS <class name> |
This style specifies a window class name to use for the window or dialog. The default is TVDSDialog. For example: CLASS TOptionsDlg. |
CLICK |
A CLICK event is generated if the user clicks on the surface of the dialog. |
DDESERVER {<topic name>} |
A DDEMACRO event is generated if another application links using DDE to this one. This style may optionally be followed by a topic name, if not, a default topic of System is used, |
DRAGDROP |
A DRAGDROP event is generated if the user drags and drops files on the dialog. The filenames can be obtained using LIST DROPFILES. |
INVISIBLE |
The dialog background will be invisible. This style is generally used with a BITMAP or SHAPE dialog element together with the NOTITLE style to create dialogs with a special appearance. |
NOSYS |
Create a dialog without a system menu or close (X) box. |
NOTITLE |
Create a dialog with no title bar, |
NOMIN |
Create a dialog that cannot be minimized. |
ONTOP |
Create a dialog that stays on top of all other windows. |
PAINT |
This style will cause PAINT events to be generated whenever the dialog is redrawn. This occurs when the dialog is resized (if the RESIZABLE style is used), restored or when any part of the dialog surface that has formerly been obscured by another window now becomes visible. This style is not generally required, because VDS automatically takes care of redrawing all dialog elements when necessary. |
RESIZABLE |
Create a dialog that can be resized. When the dialog is first created, and subsequently whenever it is resized, a RESIZE event will occur. The script must respond to this, typically by using @DLGPOS to obtain the new width and height and then using DIALOG SETPOS to reposition or resize any dialog elements that are affected. |
SAVEPOS {<name>} |
Save the dialog position and size in the registry, and restore from the saved information next time it is created. The optional <name> is required to identify saved information relating to different dialogs in a multi-dialog script, for example: SAVEPOS Options. |
SCROLLBARS [VDS6] |
Show scrollbars on the dialog if dialog elements extend beyond the current visible area. |
SMALLCAP |
Create a dialog with a small caption bar. |
SNAP |
Make the dialog snap to the edge of the desktop when it is dragged close to an edge and released. When selected, this feature is enabled by default but can be disabled at run-time using the command DIALOG SNAP, OFF. To re-enable it, use the command DIALOG SNAP, ON. |
XPMENUS |
Menus and popup menus of the window will be drawn using a style similar to Microsoft Office XP. |
DIALOG CURSOR,<cursor style> sets the cursor to be used when the pointer is over the dialog. Valid styles are: NONE, ARROW, CROSS, IBEAM, SIZE, NESW, NS, NWSE, WE, UP, WAIT, DRAG, NODROP, HSPLIT, VSPLIT, MULTI, SQL, NO, HELP, HAND or CUSTOM. The CUSTOM cursor style must be followed by an extra parameter which must be a valid cursor file path (.cur or .ani). The custom cursor may be read from a resource linked in to the executable file. To specify this the filename must be prefixed by a "#" character. To restore the default cursor, the command is issued with no <cursor style> parameter. Tip: Change the cursor to an hourglass whenever the program is doing some processing that may take some time, so that it is unable to respond immediately to user actions.
DIALOG DISABLE and DIALOG ENABLE disable and enable the element named <element name>.
DIALOG FOCUS sets the input focus to the element named <element name>.
DIALOG HIDE and DIALOG SHOW hide and show the element named <element name>.
DIALOG POPUP displays a popup menu. The parameter <items> is a list of menu items, the form <item name>;<shortcut key>;<bitmap>;<disabled>;<checked>.
| • | <item name> specifies the name and text of the menu item. It takes the form <name>:<text> where <name> and its separating colon are optional. Popup menus do not usually need names, but the option is available for consistency with pull-down menus. If <name> is omitted then a <text>MENU event is generated when the menu item is clicked. If <name> is specified, then the event will be <name> instead. (Tip: Choose a name ending in MENU for menu items.) |
| • | <shortcut key> can specify an additional shortcut key or key combination that can be used to invoke the menu. This is defined using the standard syntax for shortcuts, for example: F10, Shift+F8, Ctrl+C. Note: Because DialogScript popup menus are dynamic (they exist only while they are being shown) the shortcut keys displayed on a popup menu cannot actually be used. They are supported for consistency, so that a popup menu item may look the same as its equivalent main menu entry. |
| • | <bitmap> can specify an optional 16x16 pixel bitmap that will be displayed to the left of the menu caption. The filename may be prefixed by a # character if the bitmap file is to be included in the compiled executable file as a resource. |
| • | <disabled> should be non-null if the popup menu item is to be shown disabled. Alternatively, a registry value can be used to set this state, as described below. |
| • | <checked> should be non-null if the popup menu item is to show a check box. Alternatively, a registry value can be used to set this state, as described below. |
Only <item name> is mandatory, and must be unique. The menu items are separated by vertical bars, and semicolons are used to separate the name, shortcut key and bitmap components of each menu item. Each item, when clicked, generates an event of <text>MENU, or <name> if the menu item has been named, for example: CutMENU if you click the Cut item on the popup. The optional <x> and <y> are numbers that specify the screen co-ordinates where the menu is to pop up. If these are omitted the menu will pop up where the mouse pointer is (which is what a user would normally expect.)
Popup menu items may be enabled or disabled or show a check box. To specify whether a menu item should be enabled or disabled, or checked, either:
| • | set these opens in the menu item specification, as described above. |
| • | set values must be set in the program's default registry key to show the required state. These values will be checked when the popup menu item is created. This method is useful when a popup menu has items with the same name as a pull-down menu (such as the Edit menu) as a single registry value can determine the state of both menu items. To show a check box against a menu item, use the command: REGISTRY WRITE, DEFAULT, , <name>,1. To clear the check box, set the value <name> to null, or delete the value. To disable a menu item use the command: REGISTRY WRITE, DEFAULT, MenuCtrl, <name>, X. To re-enable the menu item, set the value <name> to null, or delete it. |
[VDS5] VDS 5 does not support the naming of menu items, nor can popup menu items be disabled or checked.
DIALOG SELECT is required when working with child dialogs. The <id> may be a number that refers to the dialog's position relative to the main window dialog 0 (zero) in a list. <id> 1 would be an only child dialog. This is the same number that is returned by the function @EVENT(D) when a dialog element generates an event. Note: If multiple dialogs are created, then closed in a different order, the <id> number of a particular dialog will change, because it is actually the index value of the dialog in an internal list. DIALOG commands and functions that operate on dialog elements (such as @DLGTEXT) will give an error if the elements they refer to do not exist on the dialog that is currently selected. [VDS6] The <id> may also be the window identifier of the dialog, its class name or its title bar text,
DIALOG SET sets the contents of the element named <element name> to <value> (which may be text, or the filename of a graphic file in the case of an element that displays graphics.). When applied to LIST dialog elements, this command sets the contents of the list box <name> to <text>. To replace the selected item you should use LIST PUT,<name>,<text> instead. When applied to a CHECK element, the box is checked if <value> is not null.
DIALOG SETPOS lets you alter the size or position of a dialog element at run-time. The <top>,<left>,<width> and <height> are the values for those respective properties. To leave an existing value unchanged, the corresponding parameter should be left null. If <element name> is null, the command refers to the currently selected dialog. In this case, <width> and <height> specify the size of the client area of the dialog, not including any border, menu bar or title bar.
DIALOG SETTIP lets you change the text of a a dialog element tooltip.
DIALOG SHOW displays the dialog that has been created, or re-shows the selected dialog if it has been hidden. If <element name> is given, then it shows a dialog element that has been hidden.
DIALOG SHOWINFO [VDS6] applies only to a TASKICON element. It causes an information balloon to be displayed above the task bar icon, with a caption of <caption> (up to 63 characters), text of <text> (up to 255 characters) and an optional <icon type>. The <icon type> may be one of NONE (default), INFORMATION, WARNING or ERROR. If the TASKICON element was created with the INFOCLICK style, then an <element name>INFOCLICK event will be generated if the user clicks on the body of the information balloon (but not its close button.)
DIALOG SHOWMODAL This command is similar to DIALOG SHOW, except that the script halts at this command until a button is pressed. This simplifies the handling of child dialogs, as you don't have to worry about events occurring because the user clicked a button on another dialog. When a button is pressed, a <button_name>BUTTON event is generated, but the dialog behaves as if it has been closed. The script can use @EVENT to test which button was pressed. After processing, it must use DIALOG CLOSE to close the dialog.
DIALOG SNAP is used to enable or disable the SNAP dialog style, which causes a dialog to snap to the edge of the desktop.
DIALOG TITLE sets the text in the title bar of the dialog window to <title>. This is different from setting the title of the script program, which is done using the TITLE command.
OK:
Unchanged.
Example:
dialog title,Address Book
dialog clear,Name
dialog set,NM,1
dialog focus,Name
See an example of a DragDrop dialog...
See an example of a ShowModal dialog...
See an example of a multi dialog application...
See also: