Dialog Boxes

Project: A script which automates one or more session activities is configurable and needs to prompt the user for selections before proceeding. A custom dialog box is desired so it can use standard Windows controls appropriate for this custom application.

Algorithm: The script defines a dialog box with checkboxes, text boxes, combo buttons, listboxs and/or buttons for user selections and waits until the user chooses to proceed by clicking the OK button. When this happens, user selections are read, interpreted and stored for future script operations, and the dialog box is cancelled.

Relevant Commands and Functions:

DIALOG — Beginning of dialog block, also specifies size, position, and attributes of the dialog box
DIALOG END — Defines end of dialog block
DIALOG CANCEL — Cancels the specified dialog
SHOW — Display each script command as it is executed.
Dialog Controls (commands):

(DIALOG) BUTTON — Creates a command button control in a dialog box
(DIALOG) CHECKBOX — Creates a check box control in a dialog box
(DIALOG) EDITTEXT — Creates an edit text control in a dialog box
(DIALOG) GROUPBOX — Creates a group box control in a dialog box
(DIALOG) ICON — Displays the specified icon in the a dialog box
(DIALOG) ICONBUTTON — Creates an icon button control in a dialog box
(DIALOG) LISTBOX — Creates a list box control in a dialog box
(DIALOG) MESSAGE — Displays a text message in a dialog box
(DIALOG) NEWLINE — Positions next dialog control on next line of dialog box
(DIALOG) PICTURE — Displays the specified picture in the dialog box
(DIALOG) RADIOBUTTON — Creates a radio button control in a dialog box
(DIALOG) RADIOGROUP — Defines a group of radio button controls in a dialog box

Dialog Functions, which return user selections from dialog controls:

(DIALOG) CHECKBOX — Determines if the specified checkbox is checked
(DIALOG) EDITTEXT — Returns the contents of the specified edit text control
(DIALOG) LISTBOX — Indicates which item in the specified listbox is selected
(DIALOG) RADIOGROUP — Indicates which radio button in a radio group is selected.

Additional Dialog Commands:

DIALOG DIMENSION — Specifies the size and position of a control in a dialog box
DIALOG UPDATE — Modifies dialog controls displayed in an active dialog

A Brief Example

Below is a picure of the dialog box we are creating:

*DialogPrompt
TABLE DEFINE 0 FIELDS CHAR 15
@R0.1 = "TSO SYSTEM", RECORD WRITE 0
@R0.1 = "TANDEM", RECORD WRITE 0
@R0.1 = "VAX", RECORD WRITE 0
@R0.1 = "AS/400", RECORD WRITE 0
@R0.1 = "RS6000", RECORD WRITE 0
DIALOG (0,0,188,126) "Session Setup" SYSMENU FALSE 1
MESSAGE (40,6,48,9) "Host System:"
LISTBOX (40,19,65,33) 0 (0)
EDITTEXT (5,53,99,12) "User ID:" ""
EDITTEXT (5,67,100,12) "Password" "" PASSWORD
CHECKBOX (117,22,60,10) 0 "Idle Timeout" PERFORM ToggleRadioGroup
GROUPBOX (116,36,64,43) "Timeout period"
RADIOGROUP ""
RADIOBUTTON (120,51,50,10) "20 Minutes"
RADIOBUTTON (120,62,50,10) "30 Minutes"
BUTTON (59,93,32,14) DEFAULT "&Open" RESUME
BUTTON (98,93,32,14) CANCEL "&Cancel" CANCEL
DIALOG END

DIALOG CONTROL 1 RADIOGROUP 1 DISABLE
DIALOG CONTROL 1 RADIOBUTTON 1 DISABLE
DIALOG CONTROL 1 RADIOBUTTON 2 DISABLE
WAIT RESUME

%HostSystem = LISTBOX(1,1)
RECORD READ 0 AT %HostSystem
$HostSystem = TRIM(@R0.1)
$UserId = TRIM(EDITTEXT(1,1))
$Password = TRIM(EDITTEXT(2,1))
IF CHECKBOX(1,1) = 1 #timeout = TRUE
ELSE #timeout = FALSE
If RADIOGROUP(1,1) = 1 $time = "00:20:00"
If RADIOGROUP(1,1) = 2 $time = "00:30:00"
DIALOG CANCEL 1
RETURN

*ToggleRadioGroup
IF CHECKBOX(1,1) = 0
BEGIN
DIALOG CONTROL 1 RADIOGROUP 1 DISABLE
DIALOG CONTROL 1 RADIOBUTTON 1 DISABLE
DIALOG CONTROL 1 RADIOBUTTON 2 DISABLE
END

IF CHECKBOX(1,1) = 1
BEGIN
DIALOG CONTROL 1 RADIOGROUP 1 ENABLE
DIALOG CONTROL 1 RADIOBUTTON 1 ENABLE
DIALOG CONTROL 1 RADIOBUTTON 2 ENABLE
END
RETURN

This example is developed in two routines, a main one which presents the dialog box and a worker routine which toggles the state of some of the dialog box controls. Writing scripts in procedures and passing arguments are discussed further in the Program Flow example.

A few lines preceed the dialog box definition in this example. These are to define a table and load it with the names of several host systems since the Listbox dialog control uses a table to display available values. Alternatively, the table could be loaded from a file using the TABLE LOAD command. Further illustration of data table manipulation can be found in the example of Data Tables.

The DIALOG command begins the dialog block and the DIALOG END command ends it. The commands between them define the dialog controls to be displayed, their properties, and where appropriate, what they do when activated. The order of the controls within the dialog box determines the tab order within the dialog. In addition, several of the controls allow definition of accelerator keys for easy access from the keyboard. This example contains a listbox of available host systems, edittext boxes for the user to enter their userid and password, a checkbox for an optional script feature, and if checked, a set of radiobuttons used to configure that timeout feature. The DIALOG CONTROL command is used to update the Radiobutton controls to be disabled/enabled based on the state of the checkbox, and for simplicity, this part of the script was offloaded to a separate routine which is called from the dialog and returns after making the changes.

A WAIT RESUME command is commonly used at the end of the Dialog block to pause script execution until the user makes selections and chooses to continue. The user clicks on the OK button which issues the necessary RESUME script command to move past the WAIT RESUME, the selections are read from the dialog controls and stored to variables, and the DIALOG CANCEL command removes the dialog box. This example illustrates the use of the the EDITTEXT( ), LISTBOX( ), RADIOGROUP( ), and CHECKBOX( ) functions to return the user selections, and the TRIM( ) function to remove trailing spaces from strings. Finally, the DIALOG CANCEL command terminates the dialog box and the RETURN command returns to the line following the command which called this DialogPrompt routine.

Further Development:

  • Up to 16 dialogs may be displayed at once by using the optional Index parameter of the DIALOG command. Thus, several sub dialogs can be defined for additional or related configuration choices.
  • The position and size of dialogs, and each of the controls within them, are configurable via optional coordinate parameters. Using these features, you can fine tune the appearance of dialogs.
  • Several of the DyanComm products include a Dialog Editor standalone program, which allows drag and drop creation of dialog boxes. The Dialog Editor outputs the script commands to create the dialog box. See the product documentation for more details.
  • Many of the controls of the dialog can be updated dynamically with the DIALOG UPDATE command without repainting the dialog. This can be used to gray or change the options available in the dialog, based on user choices or other events that can be monitored via Script commands.

Additional Examples:

Several of the examples examined here use dialog boxes for input/output. See the Session Manager example and the Data Tables example.

MULTIDLG - This example lists files and subdirectories in the root directory of the PC in a listbox. When you click on an item in the listbox, it uses a secondary dialog to report the properties of the object.

DDECLNT - This example exhibits DDE Client functionality, but is also a good illustration of enabling/disabling dialog controls based on user actions.