Copyright: Copyright© 1999 Symantec Corporation.  All rights reserved.
Citation: Copyright© 1999 Symantec Corporation.  All rights reserved.


A Sample Dialog

  Related Topics

This dialog was constructed using the Dialog Editor. Included in the dialog is a variable text caption, a variable text field encolsed by a groupbox control, and a group of labeled edit boxes. Pushbuttons for closing the dialog and opening help are also included.  The dialogbox statement group generated by the Dialog Editor looks like this:

dialogbox 88 32 44 242 140 26 catsrchopts parent 2

   bitmap 1 194 6 41 37 catagbmp

   groupbox 2 2 6 187 26

   text 3 5 12 181 18 datext center

   groupbox 4 2 36 186 89

   text 5 8 49 39 8 "&Libraries: " right

   editbox 6 48 47 94 11 strvar3

   pushbutton 7 144 46 40 14 "&Select"

   text 8 8 68 39 8 "&Filename: " right

   editbox 9 48 65 49 12 strvar4

   text 10 109 68 39 8 "&Days old: " right

   editbox 11 150 65 32 11 strvar6

   text 12 8 85 39 8 "&Keywords: " right

   editbox 13 48 82 134 11 strvar2

   text 14 8 103 64 8 "&Uploaded by (ID): " right

   editbox 15 76 100 106 11 strvar5

   pushbutton 16 194 46 40 14 "&Ok"

   pushbutton 17 194 64 40 14 "&Help"

   pushbutton 18 194 82 40 14 "&Cancel" cancel

enddialog


An Introduction to the Dialog Editor

  Related Topics

The Procomm Plus Dialog Editor allows you to create and edit dialog boxes for use with ASPECT script files, using a visual approach that is much easier than coding a dialogbox statement group by hand. The dialogs you create can:

•	Serve as user input or option selection boxes.

•	Report the status of an on-going process.

•	Provide information to the user.

After you’ve configured your dialog and its controls, the Dialog Editor generates the code to recreate that dialog within a script. The editor produces a standard dialogbox statement group, which allows you to easily modify or even port the dialog between scripts.

The dialog box group generated by the editor can be inserted into a .was source file in one of two ways:

•	By pasting it directly into the source file.

You can copy the dialog from the editor to the Windows Clipboard, then paste it directly into your .was file.

If you need to modify an existing dialog in an ASPECT source file, you can copy it to the Windows Clipboard, then paste it directly into the Dialog Editor. The editor recreates your dialog, allowing you to make your changes.

•	By saving it as a Windows User Dialog or ".wud" file.

You can save your dialog to disk, then embed it in the main script’s source as an #include file.

If you need to modify an exsiting dialog in a .wud file, simply select the editor’s File | Open Dialog command, and select the file. The editor loads and displays the dialog, and you can make your changes.

Regardless of the method you choose for including the dialogbox statement group in your script, you’ll need to write supporting ASPECT commands to initialize the dialog’s variables and to respond to the user’s actions.


Bitmap Control Options

Double click on a bitmap control to view or modify its properties and control ID in the Bitmap Options dialog:

File Name

This field accepts either a string constant or variable name, containing the name of the bitmap file to be displayed in the dialog box. If you select a string constant, a Browse button is provided, allowing you to select a bitmap using a standard file open dialog.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the bitmap. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the bitmap. However, you may want to change this ID in the actual script to suit your preferences.

When you’re satisfied with the settings you’ve selected for your bitmap control, click on OK to save them and return to the main editing window. If you want to close the Bitmap Options dialog without saving any changes you may have made, click on Cancel.


Checkbox Control Options

Double click on a checkbox control to view or modify its properties and control ID in the Check Box Options dialog:

Label

This field accepts either a string constant or variable to be displayed as the checkbox label. To provide a keyboard accelerator for the checkbox, simply place an ampersand (&) in front of the desired character within the label text. To display an ampersand in the text, use two ampersands; for example, the label "&R&&D" would display as "R&D", with the R appearing as an underlined accelerator.

State Variable

This field requires an integer variable name. The State Variable can be pre-initialized within the script for a starting value. It will also receive a value based on the status of the checkbox. A value of 1 indicates that the box is checked; a 0 indicates that it is unchecked.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the checkbox, and is reported to the script as a dlgevent whenever the button is selected. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the checkbox. However, you may want to change this ID in the actual script to suit your preferences.

When you’re satisfied with the settings you’ve selected for your checkbox control, click on OK to save them and return to the main editing window. If you want to close the Check Box Options dialog without saving any changes you may have made, click on Cancel.


Combobox Control Options

Double click on a combo box control to view or modify its properties and control ID in the Combo Box Options dialog:

General Tab

Itemlist

This field accepts either a string constant or variable for the comma-separated items to be displayed in the combo box. A vertical scrollbar will be displayed at run-time if the item list contents are too numerous to be displayed simultaneously.

Select Variable

This field only accepts a variable name. The named variable will be updated with the contents of the item selected by the user.

Edit Length

If this check box is enabled, its associated edit field accepts either a numeric constant or variable, specifying the maximum number of characters that can be entered in a SIMPLE or DROPDOWN combo box’s edit field.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the combo box. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the combo box. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Sort

If this check box is enabled, the combo box item list will be sorted lexicographically in ascending order when displayed.

Style

There are three styles of combo boxes supported by ASPECT. A SIMPLE combo box will always display the item list, with the current selection displayed in its edit field. The DROPDOWN combo box is similar to the SIMPLE type, but the list is not displayed unless the button beside the edit field is selected. The DROPDOWNLIST combo box is similar to the DROPDOWN style, but the edit field is replaced by static text, meaning that no new items can be added to the list from the keyboard.

When you’re satisfied with the settings you’ve selected for your combo box control, click on OK to save them and return to the main editing window. If you want to close the Combo Box Options dialog without saving any changes you may have made, click on Cancel.


Deleting a Dialog Box Control

  Related Topics

To delete the currently selected control (or controls), press the <Delete> key, or click on the Delete Action Bar button. The Dialog Editor will remove the control without prompting you to confirm the action.


Dialog Box Properties

A dialog’s display, and the way it interacts with your script and user input, are determined by the properties you assign to it. Double click on the dialog box work area to display the Dialog Box Options dialog.

The General Tab

Moveable with Caption

If this check box is enabled, its associated edit field will accept either a string constant or variable to be displayed as the caption in the dialog box's title bar.

Dialog ID

This edit field specifies the ID for the dialog. This integer value is used in such commands as dlgupdate and dlgdestroy to reference and control the dialog box. The editor will assign a default Dialog ID. However, you’ll probably want to modify it depending on your script’s needs.

Call Procedure Name

If this check box is enabled, its associated edit field accepts the name of the ASPECT procedure to be called when the dialog box is created.

Parent ID

If this check box is enabled, its associated edit field accepts either a numeric constant, or a variable equal to the control id of the parent or owner dialog of this dialog box. When a parent dialog box is destroyed, its child dialog boxes will automatically be destroyed as well.

The Styles Tab

Center Dialog Box

If this check box is enabled, the dialog box will be centered horizontally on the display screen.

Modeless

If this check box is enabled, the dialog box will be modeless. This means that the user will be able to access other features of Procomm Plus, or even other script dialogs, without closing the current dialog.

Hide Dialog Initially

If this check box is enabled, the dialog box will remain hidden until it’s displayed by the dlgshow command. This is useful if the script needs to update variables within the dialog before showing them to the user.

Update Variables on Event

If this check box is enabled, the variables and files associated with the dialog box controls will be updated only as their respective events are read from the dialog event queue with dlgevent.

Disable Esc Key and Menu Close

If this check box is enabled, neither the dialog’s control menu Close item nor the Esc key will close the dialog box.

Remove Close from System Menu

If this check box is enabled, the dialog’s control menu Close item will be removed from the dialog box’s system menu.

Dead End Dialog

If this check box is enabled, script execution will not continue past the enddialog command until the dialog box is destroyed.

When you’re satisfied with the settings you’ve selected for your dialog, click on OK to save them and return to the main editing window. If you want to close the Dialog Box Options dialog without saving any changes you may have made, click on Cancel.

For more information on the various dialog options, see the dialogbox command.


Dialog Control Options

  Related Topics

Each control placed in a dialog generates an ASPECT command in the dialogbox statement group generated by the editor. The editor also includes settings and parameters reflecting the control’s size and position, as well as its properties.

If you’d like further details on how the finished .wud statement will appear for a particular control, you may wish to refer to the description for the corresponding command.

For more details, select one of the following control option categories:

Text Control Options

FText Control Options

Checkbox Control Options

Pushbutton Control Options

Radiobutton Control Options

Iconbutton Control Options

Icon Control Options

Listbox Control Options

FListbox Control Options

Dirlistbox Control Options

Dirpath Control Options

Combobox Control Options

FCombobox Control Options

Editbox Control Options

FEditbox Control Options

GroupBox Control Options

Metafile Control Options

Bitmap Control Options


Dirlistbox Control Options

Double click on a dirlistbox control to view or modify its properties and control ID in the Directory List Box Options dialog:

General Tab

Input File

This field accepts either a string constant or variable for the filespec used to scan the files in the target directory. This filespec may include DOS wildcards and/or a DOS path name. A vertical scrollbar will be displayed at run-time if the resultant directory listing is too long for the list box.

File Type

If this check box is enabled, its associated field accepts either a string constant or a variable. It can be used to limit the search pattern for the directory list. For more information, see the dirlistbox command.

Select Variable

This field only accepts a variable name. If a single selection is specified, the named variable will be updated with the contents of the item selected by the user. If multiple selections are allowed, this variable specifies the file to be created to contain the selections.

Dir Path ID

If this check box is enabled, its associated edit field accepts either a numeric constant or variable. This constant value should represent the control ID for a dirpath control within the same dialog, which will be updated with the current directory path selected by the user within the dirlistbox control.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the directory list box. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the directory list box. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Sort

If this check box is enabled, the directory list will be sorted lexicographically in ascending order when displayed.

Horizontal Scroll

If this check box is enabled, the dirlistbox control will be displayed with the appropriate scroll bars, allowing the user to scroll the directory list display.

Selection

To allow a user only a single selection from the list, select the Single option button. The Multiple option button allows one or more items to be selected at once. If the user selects more than one item from the directory list box, they will be written to the text file specified by the Select Variable, one item per line.

When you’re satisfied with the settings you’ve selected for your dirlistbox control, click on OK to save them and return to the main editing window. If you want to close the Directory List Box Options dialog without saving any changes you may have made, click on Cancel.


Dirpath Control Options

Double click on a dirpath control to view or modify its properties and control ID in the Directory Path Options dialog:

Variable

If this check box is enabled, its associated edit field accepts a string variable name. This variable will be updated with the current directory path selected within a dirlistbox control and displayed.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the dirpath. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the dirpath. However, you may want to change this ID in the actual script to suit your preferences.

When you’re satisfied with the settings you’ve selected for your dirpath control, click on OK to save them and return to the main editing window. If you want to close the Directory Path Options dialog without saving any changes you may have made, click on Cancel.


Duplicating Dialog Box Controls

  Related Topics

You can duplicate a control by holding the <Ctrl> key down, then dragging the selected control. The new control will have the same size and characteristics as the original, except for its control id. You can resize it, and double click on it to modify its settings.


Editbox Control Options

Double click on an editbox control to view or modify its properties and control ID in the Edit Box Options dialog:

General Tab

Variable

This field accepts a string variable name which will be updated with any changes made by the user.

Length

If this check box is enabled, its associated edit field accepts either a numeric constant or variable, specifying the maximum number of characters that can be entered in the control. If Length is not specified, up to 255 characters can be entered in the edit field. If necessary, the field will scroll to accommodate larger strings.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the edit box. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the Edit Box. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Mask Input

If this check box is enabled, text displayed in the editbox control will be displayed as asterisks. This is useful if the field is intended to contain sensitive information, such as a password or account number.

Multiline

If this check box is enabled, text displayed within the edit box will line-wrap, rather than scroll as characters are entered at the keyboard.

When you’re satisfied with the settings you’ve selected for your editbox control, click on OK to save them and return to the main editing window. If you want to close the Edit Box Options dialog without saving any changes you may have made, click on Cancel.


Editing a Dialog Box

  Related Topics

New dialog boxes are created by the editor in a default size and with basic properties. Before you begin adding controls to your dialog, you’ll probably want to resize it, move it, or modify its properties.

Re-sizing a Dialog Box

Moving a Dialog Box

Dialog Box Properties


FCombobox Control Options

Double click on an fcombobox control to view or modify its properties and control ID in the File Combo Box Options dialog:

General Tab

Input File

This field accepts either a string constant or variable for the name of the item list file to be displayed in the file combo box. A vertical scrollbar will be displayed at run-time if the item list file contents are too numerous to be displayed simultaneously.

File Offset

If this check box is enabled, its associated edit field accepts either a numeric constant or variable specifying the offset into the item list file where the displayed list begins.

File Length

If this check box is enabled, its associated edit field accepts either a numeric constant or variable specifying the maximum number of bytes to display from the offset.

Select Variable

This field only accepts a variable name. The named variable will be updated with the contents of the item selected by the user.

Edit Length

If this check box is enabled, its associated edit field accepts either a numeric constant or variable, specifying the maximum number of characters that can be entered in a SIMPLE or DROPDOWN file combo box’s edit field.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the file combo box. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the file combo box. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Sort

If this check box is enabled, the file combo box item list will be sorted lexicographically in ascending order when displayed.

Selection

There are three styles of file combo boxes supported by ASPECT. A Simple file combo box will always display the item list, with the current selection displayed in its edit field. The Dropdown file combo box is similar to the Simple type, but the list is not displayed unless the button beside the edit field is selected. The DropdownList file combo box is similar to the Dropdown style, but the edit field is replaced by static text, meaning that no new items can be added to the list from the keyboard.

When you’re satisfied with the settings you’ve selected for your fcombobox control, click on OK to save them and return to the main editing window. If you want to close the File Combo Box Options dialog without saving any changes you may have made, click on Cancel.


FEditbox Control Options

Double click on an feditbox control to view or modify its properties and control ID in the File Edit Box Options dialog:

File Name

This field accepts either a string constant or variable for the name of the text file to be edited or created in the file edit box. The target file can contain a maximum of 65536 characters. A vertical scrollbar will be displayed at run-time if the target file’s contents are too large to be displayed simultaneously.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the file edit box. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the file edit box. However, you may want to change this ID in the actual script to suit your preferences.

Horizontal Scroll

If this check box is enabled, the feditbox control will be displayed with the appropriate scroll bars, allowing the user to scroll the item display.

When you’re satisfied with the settings you’ve selected for your feditbox control, click on OK to save them and return to the main editing window. If you want to close the File Edit Box Options dialog without saving any changes you may have made, click on Cancel.


FListbox Control Options

Double click on an flistbox control to view or modify its properties and control ID in the File List Box Options dialog:

General Tab

Input File

This field accepts either a string constant or variable for the name of the item list file to be displayed in the file list box. A vertical scrollbar will be displayed at run-time if the item list file contents are too numerous to be displayed simultaneously.

File Offset

If this check box is enabled, its associated edit field accepts either a numeric constant or variable specifying the offset into the item list file where the displayed list begins.

File Length

If this check box is enabled, its associated edit field accepts either a numeric constant or variable specifying the maximum number of bytes to display from the offset.

Tab String

If this check box is enabled, its associated edit field accepts either a string constant or a variable. The constant or variable should contain a comma-separated string of tab positions. These positions will be used to space the record fields in the display.

This option is useful if the items in the list file contain tab-delimited records.  Tab positions are measured in DBUs.

Select Variable

This field only accepts a variable name. If a Single selection is specified, the named variable will be updated with the contents of the item selected by the user. If Multiple selections are allowed, this variable specifies the file to be created to contain the selections.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the file list box. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the file list box. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Sort

If this check box is enabled, the item list will be sorted lexicographically in ascending order when displayed.

Horizontal Scroll

If this check box is enabled, the flistbox control will be displayed with the appropriate scroll bars, allowing the user to scroll the item display.

Selection

To allow a user only a single selection from the list, select the Single option button. The Multiple option button allows one or more items to be selected at once. If the user selects more than one item from the file list box, they will be written to the text file specified by the Select Variable, one item per line.

When you’re satisfied with the settings you’ve selected for your flistbox control, click on OK to save them and return to the main editing window. If you want to close the File List Box Options dialog without saving any changes you may have made, click on Cancel.


FText Control Options

Double click on an ftext control to view or modify its properties and control ID in the File Text Box Options dialog:

File Name.

In this field, you can specify either a string constant or variable for the name of the file to be displayed. If a variable is used, a valid ASPECT name must be entered. Otherwise, enter the filespec directly into this field.

File Offset

If this check box is enabled, the associated edit field accepts either a variable name or a numeric constant, specifying the starting point within the source file for the text to be displayed.

File Length

If this check box is enabled, the associated edit field accepts either a variable name or a numeric constant, specifying the maximum number of bytes to be displayed from the source file.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the file based text control box, and can be used with dlgupdate to refresh the file based text control display. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the file based text control box. However, you may want to change this ID in the actual script to suit your preferences.

Dynamic File Update

If this check box is enabled, the file based text control’s scroll bar will be positioned to correspond with the specified final file size rather than the file’s current size. This mode is particularly convenient for displaying a file being received as the user is reading it.

Horizontal Scroll

If this check box is enabled, the ftext control will be displayed with the appropriate scroll bar, allowing the user to scroll the file display horizontally.

When you’re satisfied with the settings you’ve selected for your ftext control, click on OK to save them and return to the main editing window. If you want to close the File Text Box Options dialog without saving any changes you may have made, click on Cancel.


GroupBox Control Options

Double click on a groupbox control to view or specify its label and group ID in the Group Box Options dialog:

Label

If this check box is enabled, its associated edit field accepts either a string constant or variable to be displayed as the label for the groupbox.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the groupbox. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the groupbox. However, you may want to change this ID in the actual script to suit your preferences.

When you’re satisfied with the settings you’ve selected for your groupbox control, click on OK to save them and return to the main editing window. If you want to close the Group Box Options dialog without saving any changes you may have made, click on Cancel.


Icon Control Options

Double click on an icon control to view or modify its properties and control ID in the Icon Options dialog:

File Name

This field accepts either a string constant or variable specifying the file containing the icon graphic. If you select a string constant, a Browse button is provided, allowing you to select an icon file using a standard file open dialog. If you select a variable, an edit field is provided, allowing you to specify a variable name.

You can access icon graphics in executable programs (.exe), DLL modules (.dll) and icon libraries (.ico, .icl and .nil files).

Index

This field accepts either a numeric constant or variable, specifying the index of the icon graphic within the target file. Since some icon files can contain multiple icons, this number identifies which icon to use. If you specified a constant for the File Name and Index fields, the Prev and Next buttons allow you to select an icon from a file containing multiple icons.

The currently selected icon is displayed in the preview button in the lower right corner of the dialog.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the icon. It can also be used to change the icon if variables were specified for either the File Name or Index fields. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the icon. However, you may want to change this ID in the actual script to suit your preferences.

When you’re satisfied with the settings you’ve selected for your icon control, click on OK to save them and return to the main editing window. If you want to close the Icon Options dialog without saving any changes you may have made, click on Cancel.


Iconbutton Control Options

Double click on an iconbutton control to view or modify its properties and control ID in the Icon Button Options dialog:

General Tab

Label

This field accepts either a string constant or variable to be displayed as the icon button label. To provide a keyboard accelerator for the icon button, simply place an ampersand (&) in front of the desired character within the label text. To display an ampersand in the text, use two ampersands. For example, the label "&R&&D" would display as "R&D", with the R appearing as an underlined accelerator.

File Name

This field accepts either a string constant or variable specifying the file containing the icon graphic. If you select a string constant, a Browse button is enabled, allowing you to select an icon file using a standard file open dialog. If you select a variable, an edit field is displayed, allowing you to specify a variable name.

You can access icon graphics in executable programs (.exe), DLL modules (.dll) and icon libraries (.ico, .icl and .nil files).

Index

This field accepts either a numeric constant or variable, specifying the index of the icon graphic within the target file. Since some icon files can contain multiple icons, this number identifies which icon to use. If you specified a constant for the File Name and Index fields, the Prev and Next buttons allow you select an icon from a file containing multiple icons.

The currently selected icon is displayed in the preview button below the ID edit field.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the icon button. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the icon button. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Default

If this check box is enabled, the icon button will act as the default choice if the user simply presses Enter, or double clicks within certain list controls. A dialog box may have only one default button or icon button.

Selection

There are three styles of icon buttons: Normal, OK, and Cancel. A Normal button updates an associated variable, but does not close the dialog. A Cancel button closes the dialog without making a change to any variable. An OK button updates an associated variable and closes the dialog.

When you’re satisfied with the settings you’ve selected for your iconbutton control, click on OK to save them and return to the main editing window. If you want to close the Icon Button Options dialog without saving any changes you may have made, click on Cancel.


Listbox Control Options

Double click on a listbox control to view or modify its properties and control ID in the List Box Options dialog:

General Tab

Itemlist

This field accepts either a string constant or variable for the comma-separated items to be displayed in the list box. A vertical scrollbar will be displayed at run-time if the item list contents are too numerous to be displayed simultaneously.

Tab String

If this check box is enabled, its associated edit field accepts either a string constant or a variable. The constant or variable should contain a comma-separated string of tab positions. These positions will be used to space the record fields in the display.

This option is useful if the items in the list contain tab-delimited records. Tab positions are measured in DBUs.

Select Variable

This field only accepts a variable name. The named variable will be updated with the contents of the item selected by the user.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the list box. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the list box. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Sort

If this check box is enabled, the item list will be sorted lexicographically in ascending order when displayed.

Horizontal Scroll

If this check box is enabled, the listbox control will be displayed with the appropriate scroll bars, allowing the user to scroll the item display.

Selection

To allow a user only a single selection from the list, select the Single option button. The Multiple option button allows one or more items to be selected at once. If the user selects more than one item in the list, the items will be comma-separated in the Select Variable string.

When you’re satisfied with the settings you’ve selected for your listbox control, click on OK to save them and return to the main editing window. If you want to close the List Box Options dialog without saving any changes you may have made, click on Cancel.


Metafile Control Options

Double click on a metafile control to view or modify its properties control ID in the Metafile Options dialog:

File Name

This field accepts either a string constant or variable name, containing the name of the metafile file to be displayed in the dialog box. If you select a string constant, a Browse button is provided, allowing you to select a metafile using a standard file open dialog.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the metafile. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the metafile. However, you may want to change this ID in the actual script to suit your preferences.

When you’re satisfied with the settings you’ve selected for your metafile control, click on OK to save them and return to the main editing window. If you want to close the Metafile Options dialog without saving any changes you may have made, click on Cancel.


Moving a Dialog Box

  Related Topics

Although the editor places a new dialog within its workspace under the Action Bar, ASPECT dialogs can normally be placed anywhere on your Windows display.

To move the dialog, first select it by clicking on it once below its title bar, then place the mouse pointer inside the dialog’s title bar. Drag the dialog to its new location. The mouse pointer changes to indicate that you are moving the control.

If the dialog doesn’t have a title bar, you can move it by dragging any of its borders to the new location.

The editor draws an outline around the mouse pointer to indicate the dialog’s new position. The dialog’s original position is unaffected until you release the mouse button.

You can also use the cursor keys for more precise positioning. Select the dialog, then use the cursor keys to move the control up, down, left or right, one DBU at a time.

The second field of the editor’s status line will always report the dialog’s position with respect to the editor’s window. The x and y values represent the number of DBUs from the left and top of the editor’s window to the left top corner of the dialog, respectively. These values are updated continuously.


Moving a Dialog Box Control

  Related Topics

If the control you want to move doesn’t have drag handles, click on it once to select it. To move the currently selected control, place the mouse pointer inside the area bounded by its drag handles, and drag it to its new location. The mouse pointer changes to indicate that you are moving the control.

The editor draws an outline around the mouse pointer to indicate the control’s new position. The control’s original position is unaffected until you release the mouse button.

You can also use the cursor keys for more precise positioning. Select the control you want to move, then use the cursor keys to move the control up, down, left or right, one dialog unit at a time.

The second field of the editor’s status line will always report the selected control’s position with respect to the dialog. The x and y values represent the number of DBUs from the left and top of the dialog’s client area to the left top corner of the control, respectively. These values are updated continuously as you move the control.


Pushbutton Control Options

Double click on a pushbutton control to view or modify its properties and control ID in the Push Button Options dialog:

General Tab

Label

This field accepts either a string constant or variable to be displayed as the button label. To provide a keyboard accelerator for the button, simply place an ampersand (&) in front of the desired character within the label text. To display an ampersand in the text, use two ampersands. For example, the label "&R&&D" would display as "R&D", with the R appearing as an underlined accelerator.

ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the button, and is reported to the script as a dlgevent whenever the button is selected. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the button. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Default

If checked, the button will act as the default choice if the user simply presses Enter, or double clicks within certain list controls. A dialog box may have only one default button or icon button.

Selection

There are three styles of pushbuttons: Normal, OK, and Cancel. A Normal button updates an associated variable, but does not close the dialog. A Cancel button closes the dialog without making a change to any variable. An OK button updates an associated variable and closes the dialog.

When you’re satisfied with the settings you’ve selected for your pushbutton control, click on OK to save them and return to the main editing window. If you want to close the Push Button Options dialog without saving any changes you may have made, click on Cancel.


Radiobutton Control Options

Double click on a radiobutton control to view or modify its properties and control ID in the Radio Button Options dialog:

General Tab

Button Label

This edit field accepts either a string constant or variable to be displayed as the option button label. To provide a keyboard accelerator for the option button, simply place an ampersand (&) in front of the desired character within the label text. To display an ampersand in the text, use two ampersands. For example, the label "&R&&D" would display as "R&D", with the R appearing as an underlined accelerator.

Button ID

This field requires a constant or a symbol defined as a constant, in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the option button. Each control within a dialog box must have a control ID, and each ID must be unique.

When a option button is selected, its Button ID value is assigned to the status variable associated with its option button group.

The Dialog Editor automatically supplies a control ID for the option button. However, you may want to change this ID in the actual script to suit your preferences.

Style Tab

Group

radiobuttons must be associated with a radiogroup command. The option button group’s associated variable is assigned the value of the control ID of the option button selected by the user. Only one option button within a group can be selected at any time.

Click on the Group ID list box to select an option button group. If an option button group does not exist, it can be created with the New Group button. Existing option button groups can be edited by pressing the Edit Group button.

When you’re satisfied with the settings you’ve selected for your radiobutton control, click on OK to save them and return to the main editing window. If you want to close the Radio Button Options dialog without saving any changes you may have made, click on Cancel.


Re-sizing a Dialog Box

  Related Topics

To resize the dialog, move the mouse pointer over one of the "drag handles" on its corners or sides. The mouse pointer changes to indicate the directions you can drag each particular handle.

If the dialog doesn’t have drag handles, it’s not selected. Click on it once below its title bar to select it.

When you’ve located the handle you want to use, drag it in the desired direction. As you drag the handle, the editor leaves the dialog in its current size, but draws an outline to show you the dialog’s new size. When you’re satisfied with the dialog’s new size, release the mouse button, and the editor will update its display.

For more precise sizing, you can also use the cursor keys. Simply hold the <Shift> key down while pressing the cursor keys. The up and down keys move the bottom of the dialog, while the left and right keys move the dialog’s right side one DBU at a time.

If the dialog is selected, the editor’s status line will report the dialog's size in its third field; the dx and dy values represent the its width and height, respectively. These values will update as the dialog is being expanded or contracted.


Re-sizing a Dialog Box Control

  Related Topics

New dialog controls are initially drawn by the editor in a default size determined by the control’s type. To resize a control, move the mouse pointer over one of the "drag handles" on its corners or sides. The mouse pointer changes to indicate the directions you can drag each particular handle.

If the mouse pointer does not change when placed over a handle, it means that the control is not re-sizable. In particular, icons and icon buttons are not re-sizable.

If the control you want to resize doesn’t have drag handles, click on it once with the mouse to "select" it. Once selected, the control can be moved or resized.

When you’ve located the handle you want to use, drag it in the desired direction. As you drag the handle, the editor leaves the control in its current state, but draws an outline to show you the control’s new size. When you’re satisfied with the control’s size, release the mouse button, and the editor will update its display.

For more precise sizing, you can also use the cursor keys. Select the control you want to re-size, and hold the Shift key down while pressing the cursor keys. The up and down keys move the bottom of the control, while the left and right keys move the control’s right side one DBU at a time.

The editor’s status line will always report the size of a control in its third field; the dx and dy values represent the control’s width and height, respectively. These values will update as the control is being expanded or contracted.


Running the Dialog Editor

  Related Topics

You can launch the Dialog Editor in one of three ways:

•	By selecting Tools | Scripts | Dialog Editor in the Terminal window.

•	By selecting Tools | Dialog Editor in the ASPECT Editor.

•	By clicking on the Dialog Editor button on the Tools-related Action Bar.

•	By clicking on the Dialog Editor icon in the Procomm Plus Utilities group under the Start menu.

The editor’s main window appears with an untitled dialog.  The window is composed of four elements: a menu bar, an Action Bar, a dialog box "work area" and an Item Description status line.

The Dialog Editor’s menus and Action Bar are covered together in The Dialog Editor's Action Bar and Menus. The use of the its work area is discussed in Editing a Dialog Box.

The Item Description status line appears at the bottom of the editor window.  The first field of the Item Description status line usually displays the type of the currently selected item. This may be "Main Dialog", if the dialog box itself is selected, or a particular control name such as "Icon" or "Pushbutton". The field reads "Ready" if no item is selected.

The values in the second status line field reflect the location of the currently selected item. Again, this can be either the dialog box itself, or a control. The x and y values represent the horizontal and vertical coordinates of the upper left corner of the item in Dialog Box Units or DBUs.

For more information on how dialog units are used in ASPECT, see the dialogbox command.

If the selected item is a dialog control, its x and y values are measured with respect to the dialog box. If the dialog box itself is selected, its x and y values are measured with respect to the editor’s main window. The field is blank if no item is selected.

The third status line field describes the size of the currently selected item, with the dx and dy values referring to the horizontal and vertical dimensions of the item in DBUs. The field is blank if no item is selected.

The final status line field displays the id value of the currently selected item. The field is blank if no item is selected.


Step-by-Step: Placing a Dialog Control

  Related Topics

With the Dialog Editor’s "point and click" interface, placing and sizing any dialog control is a simple task:

1.	Select the control from the editor’s Controls menu.

2.	Move the mouse pointer to the control’s approximate location in the dialog.

As you move the pointer over the dialog, you’ll notice that it changes into a crossbar, indicating that you’re placing a control. Move the crossbar to the approximate location for the control’s top left corner.

3.	Click once in the work dialog, anywhere beneath its title bar, to place the control.

The control’s left top corner is placed in the location you clicked.

When you place a new control, the Dialog Editor assigns it the default size and characteristics for that control. text controls, for example, are initially given a constant value of "Text", while pushbuttons, radiobuttons and checkboxes are initialized to "Label". bitmaps and metafiles are initialized to "BMP" and "WMF," respectively.

4.	Adjust the control’s size or placement as needed.

After you place a control, it remains selected, allowing you to easily resize it or modify its characteristics. Drag handles are displayed on the selected control, allowing you to change its size by dragging a handle in the appropriate direction.  You can also use the commands under the Layout menu to align a dialog control with the edges of the dialog and other controls that have already been placed.

Some controls, such as icons and icon buttons, are not re-sizable. For more information, see Re-sizing a Control.

You can "fine tune" the control’s placement with the cursor keys, or use the mouse to drag the control to a new location. For more information, see Moving a Control.

5.	Modify the control’s characteristics or settings.

Double click on the control to open its options dialog and adjust its settings.

The Options dialog for each type of ASPECT dialog control is discussed in Dialog Control Options.

Depending on the type of control you’re placing, you may find that you need to adjust its size or placement after you’ve changed its settings.


Text Control Options

Double click on a text control to view or modify its properties and control ID in the Text Options dialog:

Label

This field accepts either a string constant or variable to be displayed in the text control. If a variable is specified, a valid ASPECT name must be entered in this field. In the Style panel, you may also specify Left, Center or Right Alignment for the text in this dialog.

To include a keyboard accelerator in the text, place an ampersand (&) in front of the desired character. To display an ampersand in the text, use two ampersands. For example, the label "&R&&D" would display as "R&D", with the R appearing as an underlined accelerator.

ID

This field requires a constant in the range of 1 to 999. The ID is used within a dialogbox statement group to reference the control, and can be used with dlgupdate to refresh the text display. Each control within a dialog box must have a control ID, and each ID must be unique.

The Dialog Editor automatically supplies a control ID for the text. However, you may want to change this ID in the actual script to suit your preferences.

When you’re satisfied with the settings you’ve selected for your text control, click on OK to save them and return to the main editing window. If you want to close the Text Options dialog without saving any changes you may have made, click on Cancel.


The Dialog Editor

  Related Topics

The Procomm Plus Dialog Editor allows you to create and edit dialog boxes for use with ASPECT script files, using a visual approach that is much easier than coding a dialogbox statement group by hand.

For more information, see the following topics:

An Introduction to the Dialog Editor

Running the Dialog Editor

Editing a Dialog Box

Working with Dialog Box Controls

A Sample Dialog

The Dialog Editor's Menus and Action Bar


The Dialog Editor's Action Bar and Menus
The Dialog Editor's Menus and Action Bar

  Related Topics

Action Bar Button	Menu | Item	Description
	File | New Dialog	Creates a new, untitled dialog box.
	File | Open Dialog	Retrieves an existing .wud file. The Dialog Editor can also process a .was file to import a dialog box for editing.
	File | Save	Writes any changes you’ve made to the current dialog .wud file.
	File | Save As...	Saves the current dialog code under a new filename. The editor will prompt you for the new filename. If the current dialog code is untitled, the File | Save Action Bar button will respond exactly like the Save As... command.
	File | Default Path...	Opens the Default Path dialog where you can specify the default working directory for the editor. Usually, this is where your .wud files are stored.
	File | Exit	Exits the Dialog Editor. If you've made changes to the current dialog box, the editor will ask if you'd like to save your work.
	Edit | Undo	Reverses the effect of the last action you performed. This command is useful if you happen to make a mistake and want to restore a deleted control.
	Edit | Cut Dialog	Cuts the current dialog source code to the Windows Clipboard. <Ctrl><X> is a keyboard shutcut.
	Edit | Copy Dialog	Copies the current dialog source code to the Windows Clipboard. <Ctrl><C> is a keyboard shortcut.
	Edit Paste Dialog	Pastes a dialogbox statement group from the Windows Clipboard to the Dialog Editor window. <Ctrl><V> is a keyboard shortcut.
	Edit | Delete Object	Deletes the currently selected object/control from the dialogbox statement group. <Delete> is a keyboard shortcut. Note that the "Main Dialog" itself cannot be deleted. However, a new dialog can be opened with the File | New command.
	View | Action Bar	Toggles the display of the Dialog Editor Action Bar, which contains buttons corresponding to  frequently-used menu commands.
	View | Status Line	Toggles the display of the status line.
	View | Large Action Bar	Toggles between small and large Action Bar icon buttons.
	Controls | ...	Each of the controls you place in a dialog has an associated options dialog, which you can access by double clicking on the control. See Dialog Control Options.
	Controls | Text	Places a block of text in a dialog box. A text control is typically used for labels or brief instructions
	Controls | FText	Places a standard scrolling list box which displays text from a file.
	Controls | Checkbox	Places a standard option checkbox.
	Controls | Pushbutton	Places a standard button.
	Controls | RadioButton	Places an option selection button. Option Buttons are normally used in groups of two or more to allow the selection of one option from several related choices, where one option is always selected.
	Controls | IconButton	Places an icon graphic that acts as a button.
	Controls | Icon	Places an icon graphic for display only.
	Controls | Listbox	Places a standard list box with a vertical scroll bar. The displayed list is contained in a string constant or global variable.
	Controls | FListbox	Places a standard list box with a vertical scroll bar. The displayed list is contained in a disk file.
	Controls | DirListBox	Places a directory list box which displays filenames and/or directories, and allows the selection of filespecs from any disk directory.
	Controls | DirPath	Places a text element displaying the current drive and directory, used for display only.
	Controls | ComboBox	Places a combination edit/selection or "drop-down" list control, whose list is stored in a string constant or global variable. After placement, the combo box can be configured for one of three possible styles.
	Controls | FComboBox	Places a combination edit/selection "drop-down" list control, whose list is contained in a disk file. After placement, the file combo box can be configured for one of three possible styles.
	Controls | EditBox	Places a text entry field. Characters typed into the field are stored in a global string variable.
	Controls | FEditBox	Places a text edit box that writes its contents to a disk file.
	Controls | GroupBox	Places a box graphic element, used for display only. groupboxes are often used to enclose option button groups or related dialog box controls.
	Controls | Metafile	Places a Windows metafile graphic element, used for display only.
	Controls | Bitmap	Places a Windows bitmap graphic element, used for display only.
	Layout | Align Controls	A menu cascade that allows you to align the currently selected controls along the left, right, top and bottom of the dialog.  This command is valid only for multiple controls.
	Layout | Space Evenly	A menu cascade that allows you to space the currently selected controls evenly across or down the dialog. This command is valid only for multiple controls.
	Layout | Center in Dialog	A menu cascade that allows you to position the currently selected control in the vertical or horizontal center of the dialog.
	Layout | Make Same Size	A menu cascade that allows you to adjust the height and width of the currently selected controls to the same size. This command is valid only for multiple controls.
	Layout | Tab Order	Adjusts the order in which the focus will move as the <Tab> key is pressed.
	Layout | Test	Displays a working example of how the current dialog will look within an ASPECT program.
	Help | Contents	Opens the Help Topics dialog for the editor.
	Help | How to use help	Displays online help on how to use the Help system.
	Help | About Dialog Editor	Displays important information about this version of the Dialog Editor.


Working with Dialog Box Controls

  Related Topics

Step-by-Step: Placing a Dialog Control

Re-sizing a Dialog Box Control

Moving a Dialog Box Control

Duplicating Dialog Box Controls

Deleting a Dialog Box Control

Dialog Control Options