Dialog, Dialog()

Syntax

Dialog DialogRecord [, DefaultButton] [, TimeOut]

Dialog(DialogRecord [, DefaultButton] [, TimeOut])

Remarks

The Dialog statement and Dialog() function are both used to display the dialog box specified by DialogRecord in a preceding Dim instruction. The dialog box displayed can be a Word dialog box or one that you define within a macro.

If you use the Dialog statement to display a dialog box and the user chooses the Cancel button, Word generates an error that an On Error instruction can trap. If you don't want or need to trap the error, you can use the Dialog() function to display the dialog box. In addition to displaying the dialog box, the Dialog() function returns a value corresponding to the button chosen. The return values are the same as those used to specify DefaultButton.

When you display a dynamic dialog box, use DisableInput to make the ESC key cancel the dialog box properly. For more information, see DisableInput.

Argument	Explanation

DialogRecord	The name given to the dialog record in the Dim instruction.
DefaultButton	The default command button: – 2 No default command button –1 The OK button 0 (zero) The Cancel button > 0 (zero) A command button, where 1 is the first PushButton instruction in the definition, 2 is the second, and so on The default command button is chosen if the user presses ENTER when a dialog box control other than a command button has the focus. Unless you specify otherwise, the OK button is the default command button. DefaultButton is used only with custom dialog boxes. For DefaultButton to have any effect, the instruction for the specified button must be preceded in the dialog box definition by an instruction for a nonbutton dialog box control that can receive the focus, such as a list box or check box. (Note that because a text control cannot receive the focus, it does not meet this criterion.) Otherwise, the first button in the dialog box definition is the default command button. If the dialog box definition has a dialog function associated with it, DefaultButton may be overridden by a DlgFocus$ statement. For information on creating dialog functions, see Chapter 5, "Working with Custom Dialog Boxes," in Part 1, "Learning WordBasic."
TimeOut	The amount of time, in milliseconds, the dialog box is displayed. If 0 (zero) or omitted, the dialog box is displayed until the user closes it.

Note

A macro can use any number of custom dialog boxes, but WordBasic supports only one custom dialog record at a time (you can define any number of dialog records for Word dialog boxes). This means that you can't define a series of custom dialog records, intending to use them later in the macro. Each custom dialog record overwrites the previous one. If your macro uses more than one custom dialog box and you need to store the values contained in a dialog record that will be overwritten, save the values in regular variables. For more information about using custom dialog records, see Chapter 5, "Working with Custom Dialog Boxes," in Part 1, "Learning WordBasic."

Examples

This example uses the Dialog() function to display the Font dialog box (Format menu) so the user can set different character-formatting options. The instruction x = Dialog(dlg) returns a value corresponding to the button the user chooses and removes the need for error handling. If the user chooses the OK button, the last instruction in the example, If x = -1 Then FormatFont dlg, implements the options that the user selected in the dialog box; if the user chooses the Cancel button, the options chosen are ignored. Without this statement, nothing happens, even though the dialog box has been displayed and the user has chosen the OK button.

Dim dlg As FormatFont
GetCurValues dlg
x = Dialog(dlg)
If x = -1 Then FormatFont dlg

The following example is the same as the previous one, except that it uses the Dialog statement to display the dialog box and includes error handling. If the user chooses the Cancel button, the resulting error is trapped and a message is displayed.

Dim dlg As FormatFont
GetCurValues dlg
On Error Goto trap
Dialog dlg
FormatFont dlg
Goto skiptrap
trap:
MsgBox "Dialog box closed -- no changes"
skiptrap:

The following example displays a simple custom dialog box with text box and command button controls. Since the text box control is the first control defined in the dialog box definition, it has the focus when the dialog box is displayed. The x = Dialog(dlg, 1) instruction makes the Find button the default command button (instead of the OK button).

Begin Dialog UserDialog 346, 90, "Social Security Macro"
    TextBox 9, 22, 192, 18, .secnum    
    Text 9, 6, 183, 13, "Social Security Number:"
    OKButton 249, 4, 88, 21
    CancelButton 249, 28, 88, 21
    PushButton 249, 52, 88, 21, "Find..."
End Dialog
Dim dlg As UserDialog
x = Dialog(dlg, 1)

See Also

Begin Dialog¼End Dialog, Dim, GetCurValues