Script Command: DIALOG

DIALOG [h:mt:w:x:y:] {dialog type} {"user message string"} ["q_and_a default answer"]

This command allows the script to interact with the user through some type of dialog box.

Options:

-h {##}       override default height of dialog box created.

-m            create dialog box in "modeless" mode (more details below)

-t {title}    override the default text in the title bar of the dialog box created.

-w {##}    override default width of dialog box created.

-x {##}   override left edge position for new dialog box.

-y {##}   override top edge position for new dialog box.

Valid dialog types:

- OK

- YES_NO

- DDLIST *

- GET_FILE *

- Q_AND_A *

- OK_CANCEL

- RETRY_CANCEL

- YES_NO_CANCEL

- ABORT_RETRY_IGNORE

* indicate special case (see below)

This gives the script the ability to specify a type of message box and a message. The box will then be presented to the user and the user will have to click a button (OK or YES or ABORT etc..) depending on the type of message box selected. Then the content of the shell variable DIALOG will contain the string that corresponds to that button... If the "YES" button was hit, then $DIALOG would contain "YES", if the "CANCEL" button was hit, then $DIALOG would contain "CANCEL" (and so on..).

Special cases (not just button selections):

- Q_AND_A <}>[default_answer]

The script provides a question and the user provides the answer. Whatever is in the answer becomes the content of the DIALOG shell variable. The script can then use the IF statement to process the result of the interaction.

- GET_FILE filename

The script provides the default filename then allows the user to accept that, enter a new one or browse for a filename using the standard FileOpen mechanism in windows. The DIALOG shell variable will contain the filename.

- DDLIST <}>1<}>[item2] [item3] ... (max of 28)

The script provides the question and a list of possible choices, each of which will be clickable through a drop-down list. The DIALOG shell variable will then contain the text of the selected item.

By default, the dialog box is a "modal" dialog box. This means that the user must complete the dialog interaction prior to doing anything else within uCon. The -m option allows the dialog box to be created in modeless mode; hence the user now has the ability (if -m is used) to transition to other uCon facilities prior to completing the interaction with the dialog box. Note that the -m option is applicable to the following dialog types:

OK, ABORT_RETRY_IGNORE, OK_CANCEL, RETRY_CANCEL, YES_NO and YES_NO_CANCEL.

Note that each of the dialog boxes provides the option to close (upper right corner button). If the dialog box's close button is clicked, the script is terminated at the line that generated the dialog box.

Following are a few of the generated message boxes...

The script line...

DIALOG OK "Continue?"

will generate the dialog box...

The content of $DIALOG after this will always be "OK".

The script line...

DIALOG YES_NO "Are you a republican?"

will generate the dialog box...

If the Yes button is clicked, then $DIALOG will contain "YES". If the No button is clicked, then $DIALOG will contain "NO".

The script line...

DIALOG OK_CANCEL "Ok to continue or cancel now?"

will generate the dialog box...

If the Yes button is clicked, then $DIALOG will contain "YES". If the No button is clicked, then $DIALOG will contain "NO".

The script line...

DIALOG Q_AND_A "Enter a number between 1 and 5:"

will generate the dialog box...

After clicking the continue button, $DIALOG will contain whatever was typed in the editbox. It is important to note that since there may be whitespace in the text returned to $DIALOG, it should be wrapped with double quotes (i.e. "$DIALOG") to still be seen as a single command line argument.

The script line...

DIALOG DDLIST "What do you want to do?" "buy a car" "build a house" "rob a bank"

will generate the dialog box...

After clicking OK, $DIALOG will contain whatever text was in the selected item. Similar to the Q_AND_A dialog above, it is important to note that since there may be whitespace in the text returned to $DIALOG, it should be wrapped with double quotes (i.e. "$DIALOG") to still be seen as a single command line argument.

Note: The optional "q_and_a default answer" argument on the command line is only applicable to the "Q_AND_A" dialog type. It is used to pre-load some string into the editbox of the Q_AND_A dialog.

The $DIALOG variable will contain whatever the user types into the text box in the dialog. The user is required to type something. If the box is empty when the button is clicked, an error dialog will be generated to let the user know that something must be entered.

Refer to EXAMPLE_3 on the main scripting page for a working example of the DIALOG command.