Begin Dialog...End Dialog

Syntax

Begin Dialog UserDialog [HorizPos, VertPos,] Width, Height, Title$
[, .DialogFunction]
Series of dialog box definition instructions
End Dialog

Remarks

Encloses the instructions that define a dialog box you create within a macro. A dialog box definition consists of a series of instructions that define different elements of the dialog box, such as the OK button, Cancel button, and so on. Dialog box elements are also known as dialog box controls.

The easiest way to create a dialog box is to use the Dialog Editor. With the Dialog Editor, you can use the mouse to design the dialog box. The Dialog Editor then creates the WordBasic code needed to define the dialog box. For information on creating and working with dialog boxes, see Chapter 5, "Working with Custom Dialog Boxes," in Part 1, "Learning WordBasic."

Note

Every custom dialog box must contain at least one command button so the user can close the dialog box. For that reason, a dialog box definition must include either an OKButton, a CancelButton, or a PushButton instruction; otherwise, a WordBasic error will occur when the macro is run.

Argument	Explanation

HorizPos, VertPos	The horizontal and vertical distance of the upper-left corner of the dialog box from the upper-left corner of the Word window, in increments of 1/8 and 1/12 of the System font (Windows) or the dialog font (Macintosh). If HorizPos and VertPos are not specified, Word centers the dialog box within the Word window.
Width, Height	The width and height of the dialog box, in increments of 1/8 and 1/12 of the System font (Windows) or the dialog font (Macintosh).
Title$	The text that is displayed in the title bar of the dialog box. If you do not specify HorizPos and VertPos, or if you do specify .DialogFunction, you can omit Title$. If Title$ is not specified, the application name is used.
.DialogFunction	The name of a dialog function associated with the dialog box; used for dialog boxes that update dynamically while the dialog box is displayed.

You can use the tab key to move between controls in a dialog box. The order of the instructions in a dialog box definition determines the tabbing order in the dialog box. By default, the dialog control represented by the first instruction in the dialog box definition will be selected when the dialog box is displayed. However, you can override this default by using the DlgFocus statement in a dialog function. You can also use the Dialog statement to specify the default button for a dialog box.

Example

This example defines and displays a dialog box (shown after the instructions) that includes every dialog box control available. Note that the Picture instruction refers to a Windows metafile graphic in the CLIPART folder, installed by Word. On the Macintosh, substitute the path and filename HD:WORD 6:CLIP ART:BIRD.

Once you have defined a dialog box with Begin Dialog¼End Dialog, you need two additional instructions to display it: a Dim instruction that defines a dialog record in which the dialog box's values are stored, and a Dialog instruction that displays the dialog box. Note that a dialog function is required to display a document in the FilePreview control. For information on dialog functions, see Chapter 5, "Working with Custom Dialog Boxes," in Part 1, "Learning WordBasic."

Sub MAIN
Dim MyList$(2)
MyList$(0) = "Blue"
MyList$(1) = "Green"
MyList$(2) = "Red"
Begin Dialog UserDialog 612, 226, "Every Dialog Box Control", \
    .DlgFunction
    ComboBox 8, 76, 176, 111, MyList$(), .ComboBox1
    CheckBox 198, 79, 180, 16, "&Check Box", .CheckBox1
    ListBox 195, 102, 189, 83, MyList$(), .ListBox1
    DropListBox 417, 5, 179, 108, MyList$(), .DropListBox1
    Text 417, 186, 35, 13, "&Text"
    TextBox 417, 199, 179, 18, .TextBox1
    GroupBox 7, 4, 177, 65, "&Group Box"
    OptionGroup  .OptionGroup1
        OptionButton 17, 16, 148, 16, "Option Button &1"
        OptionButton 17, 33, 148, 16, "Option Button &2"

END BREAK

        OptionButton 17, 50, 148, 16, "Option Button &3"
    Picture 199, 7, 181, 62, "C:\WINWORD\CLIPART\BIRD.WMF", 0, .Picture1
    FilePreview 417, 31, 179, 148, .fileprev
    PushButton 10, 199, 108, 21, "&PushButton"
    CancelButton 131, 199, 108, 21
    OKButton 253, 199, 108, 21
End Dialog
Dim sampleDlg As UserDialog
DisableInput 1
button = Dialog(sampleDlg)
DisableInput 0
End Sub
Function DlgFunction(identifier$, action, suppvalue)
    'A dialog function is required to display
    'a document in the FilePreview control.
End Function

See Also

CancelButton, CheckBox, ComboBox, Dialog, Dim, DropListBox, FilePreview, GroupBox, ListBox, OKButton, OptionButton, OptionGroup, Picture, PushButton, Text, TextBox