Word: Getting and Setting Values in Custom Dialog Boxes

 Last reviewed: July 30, 1997
Article ID: Q89319
The information in this article applies to:
  • Microsoft Word for Windows, versions 1.0, 1.1, 1.1a, 2.0, 2.0a, 2.0a-CD, 2.0b, 2.0c, 6.0, 6.0a, 6.0c

SUMMARY

Microsoft Word for Windows includes the Dialog Editor program, which you can use to create custom dialog boxes for use in Word for Windows WordBasic macros. You can use custom dialog boxes to obtain user input using common dialog box controls, such as buttons, check boxes, list boxes, combo boxes, and option buttons.

The information below provides a comprehensive explanation of how to use a custom dialog box once it has been created and inserted into a macro. Specifically, it tells you how to set values in the dialog box items and how to get the results from those items after the user closes the dialog box.

MORE INFORMATION

Below are examples of macros that demonstrate how to set default values for and how to get information out of each dialog box item. Each macro example isolates and demonstrates a single item's use.

Note: Microsoft provides macros "as is" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose.

Working with Check Boxes

The following macros display a dialog box with an OK button and a check box. The check box will be selected as the default. When the OK button is chosen a message box will be displayed indicating whether the check box is selected or not.

Word 2.x, 6.x

Sub MAIN
' Here is the dialog box definition created using the Dialog Editor
Begin Dialog UserDialog 320, 144, "Microsoft Word" 
        OKButton 22, 112, 277, 21
        CheckBox 110, 47, 111, 16, "Check Box", .CheckBox1
End Dialog 

Dim dlg As UserDialog     ' create the dialog box from the definition
dlg.CheckBox1 = 1         ' set the default to be checked (optional)
Dialog dlg                ' display the dialog box
choice = dlg.CheckBox1    ' get the check box state (a number)
If choice = 0 Then 
        MsgBox "Not checked!"
Else
        MsgBox "Checked!"
End If 
End Sub
A check box has only 2 states: selected or not selected. The value 1 indicates that the check box is selected and 0 indicates that the box is not selected. If no default value is specified, the check box comes up not selected. The .checkbox1 field (defined in the dialog box definition) will be set to either 1 or 0 indicating whether it is selected.

Word 1.x

Use the same macro as above, but change the "Begin Dialog" line to read: 

   Begin Dialog UserDialog 320, 144

Working with Option Buttons

The following macros display a dialog box with an OK button and an option group containing three option buttons. The third button will be selected as the default button. When the OK button is chosen, a message box will display, indicating which option button was selected.

Word 2.x, 6.x

Sub MAIN
' Here is the dialog box definition created using the Dialog Editor
Begin Dialog UserDialog 320, 144, "Microsoft Word" 
        OKButton 22, 112, 277, 21
        GroupBox 79, 8, 157, 89, "Group Box"   ' (optional)
        OptionGroup  .OptionGroup1
                OptionButton 104, 30, 100, 16, "Option 1"
                OptionButton 104, 50, 100, 16, "Option 2"
                OptionButton 104, 70, 100, 16, "Option 3"
End Dialog 
Dim dlg As UserDialog     ' create the dialog box from the definition
dlg.OptionGroup1 = 2      ' set the default to Option 3 (optional)
Dialog dlg                ' display the dialog box
choice = dlg.OptionGroup1 ' get the chosen option button (a number) Select Case choice 
        Case 0
                MsgBox "Option 1!"
        Case 1
                MsgBox "Option 2!"
        Case 2
                MsgBox "Option 3!"
End Select 
End Sub
Only one option button at a time can be selected in an option group. Each button has a number assigned to it. The first button is always 0, the second is 1, the third is 2, etc. If no default value is specified, the first option button is chosen (having the value 0). The .OptionGroup1 field (defined in the dialog box definition) will be set to the number indicating which button is chosen.

Word 1.x

Use the macro above, but change the "Begin Dialog" line to read: 

   Begin Dialog UserDialog 320, 144

Working with Text Boxes

The following macro displays a dialog box with an OK button and a text box. The word "Hello!" will be displayed as the default text. When the OK button is chosen, a message box will display the text that appeared in the text box when the button was chosen.

Word 2.x, 6.x

Sub MAIN
' Here is the dialog box definition created using the Dialog Editor
Begin Dialog UserDialog 320, 144, "Microsoft Word" 
        OKButton 22, 112, 277, 21
        TextBox 21, 53, 277, 18, .TextBox1
End Dialog 

Dim dlg As UserDialog    ' create the dialog box from the definition
dlg.TextBox1 = "Hello!" ' set the default text to Hello! (optional) 
Dialog dlg               ' display the dialog box
choice$ = dlg.TextBox1   ' get the text typed (a string)
MsgBox choice$ 
End Sub
Text boxes store text strings. If no default string is specified, the text box will be empty. The .TextBox1 field (defined in the dialog box definition) will be set to a string indicating what is contained in the text box.

Word 1.x

Use the same macro as above, but change the "Begin Dialog" line to read: 

   Begin Dialog UserDialog 320, 144

Working with List Boxes

The following macro displays a dialog box with an OK button and a list box that contains a list of different types of fruits. Bananas will be selected as the default fruit. When the OK button is chosen, a message box will display the selected item from the list box.

Word 2.x, 6.x

Sub MAIN
' Create an array to be used to fill a list box.
Dim Fruits$(4) Fruits$(0) = "Apples" Fruits$(1) = "Bananas" Fruits$(2) = "Grapes" Fruits$(3) = "Oranges" Fruits$(4) = "Peaches" 

' Here is the dialog box definition created using the Dialog Editor
Begin Dialog UserDialog 320, 144, "Microsoft Word" 
        OKButton 22, 112, 277, 21
        ListBox 24, 12, 277, 84, Fruits$(), .ListBox1
End Dialog 

Dim dlg As UserDialog    ' create the dialog box from the definition
dlg.ListBox1 = 1         ' set the default to Bananas (optional)
Dialog dlg               ' display the dialog box
choice = dlg.ListBox1    ' get the selected item (an array index)
MsgBox Fruits$(choice) 
End Sub
The information that displays in a list box comes from an array. In the example above, the array Fruits$() is created and filled with a list of fruits. Notice that Fruits$() appears in the ListBox line of the dialog box definition, indicating that it will list values found in this array.

The selected item in a list box is a number indicating which item in the array was picked. The first item is 0, the second is 1, the third 2, and so on. If you don't want any item to be selected in the listbox, set the default value to -1. The .ListBox1 field (defined in the dialog box definition) will be set to a number indicating which item was selected. This number directly corresponds to an item in the specified array and can be used to index the array (as demonstrated in the last MsgBox line).

Word 1.x

Use the same macro as above, but change the "Begin Dialog" line to read: 

   Begin Dialog UserDialog 320, 144

Working with Combo Boxes

The following macro displays a dialog box with an OK button and a combo box that contains a list of different types of fruits. Grapes will be selected as the default fruit (although it doesn't appear in the list). The user can select a fruit or type something unique in the text box part of the combo box. When the OK button is chosen a message box will display the item or text selected in the combo box.

Word 2.x, 6.x

Sub MAIN
' Create an array to be used to fill a combo box.
Dim Fruits$(4) Fruits$(0) = "Apples" Fruits$(1) = "Bananas" Fruits$(2) = "Nectarines" Fruits$(3) = "Oranges" Fruits$(4) = "Peaches" 

' Here is the dialog box definition created using the Dialog Editor
Begin Dialog UserDialog 320, 144, "Microsoft Word" 
        OKButton 22, 112, 277, 21
        ComboBox 24, 12, 277, 84, Fruits$(), .ComboBox1
End Dialog 

Dim dlg As UserDialog    ' create the dialog box from the definition
dlg.ComboBox1 = "Grapes" ' set the default to Grapes (optional) 
Dialog dlg               ' display the dialog box
choice$ = dlg.ComboBox1 ' get the selected item (a string) MsgBox choice$ 
End Sub
The information that is displayed in a combo box comes from an array. In the example above the array Fruits$() is created and filled with a list of fruits. Note that Fruits$() appears in the Combobox line of the dialog box definition, indicating that it will list values found in this array.

The selected item in a combo box is a text string value equivalent to the item found in the list. This differs from a list box which uses a numeric value that indexes the filling array. The reason for this difference is that the user can type in the text box portion of the combo box a value different from any value found in the list. The combo box is more like a text box, but provides a list of values that can be chosen to conveniently use.

If no default value is specified, the combo box displays with no item selected, and the text box portion of the combo box is empty. If you don't want any item to be selected in the listbox set the default value to -1. The .ComboBox1 field (defined in the dialog box definition) will be set to a string indicating what is contained in the text box part of the combo box.

Word 1.x

Use the same macro as above, but change the "Begin Dialog" line to read: 

   Begin Dialog UserDialog 320, 144

Working with OK, Cancel, and Command (Push) Buttons

The following macro displays a dialog box with an OK, Cancel, and three other push buttons. When a button is chosen, a message box will display, indicating which button was chosen.

Word 2.x, 6.x

Sub MAIN
' Here is the dialog box definition created using the Dialog Editor
Begin Dialog UserDialog 109, 129, "Microsoft Word" 
        OKButton 10, 6, 88, 21
        CancelButton 10, 30, 88, 21
        PushButton 10, 54, 88, 21, "One"
        PushButton 10, 78, 88, 21, "Two"
        PushButton 10, 102, 88, 21, "Three"
End Dialog 

Dim dlg As UserDialog    ' create the dialog box from the definition
choice = Dialog(dlg)     ' display the dialog box
Select Case choice 
        Case -1
                MsgBox "OK!"
        Case 0
                MsgBox "Cancel!"
        Case 1
                MsgBox "One!"
        Case 2
                MsgBox "Two!"
        Case 3
                MsgBox "Three!"
End Select 
End Sub
The functional form of the Dialog command returns a value indicating which button was chosen in the dialog box. The OK button is always -1, and the Cancel button is always 0. The number assigned to a command button is determined by the order in which the PushButton statement appears in the dialog box definition. The first command (push) button will be 1, the second 2, the third 3, and so on.

The functional form of the Dialog command is not required when using buttons. The Dialog line above could read 

   Dialog dlg
(as the other examples illustrate) and still function correctly. However, there would be no way of determining which button was chosen.

There is a way to set which button will be the default button selected when the ENTER key is chosen. This is implemented as an optional parameter to the Dialog command and is not documented.

For more information on setting the default button in a dialog box, query on the following words in the Microsoft Knowledge Base: 

   Defaultbutton and custom and Dialog and

Word 1.x

Sub MAIN
' Here is the dialog box definition created using the Dialog Editor
Begin Dialog UserDialog 109, 129 
        OKButton 10, 6, 88, 21
        CancelButton 10, 30, 88, 21
End Dialog

On Error Goto CancelPressed 

Dim dlg As UserDialog    ' create the dialog box from the definition
Dialog dlg     ' display the dialog box
MsgBox "OK!" Goto Bye CancelPressed: MsgBox "Cancel!" Bye: 
End Sub
Note: Versions 1.0, 1.1, and 1.1a of Word for Windows do not support the use of command buttons and the function format of the Dialog command. If the OK button is chosen, the macro will run uninterrupted. If the Cancel button is chosen, Word will generate an error that can be trapped with the On Error message. In the example above, Word will jump to the CancelPressed command if the Cancel button is chosen.

Reference(s):

"Microsoft Word for Windows User's Guide," version 2.0, pages 787-792

"Microsoft Using WordBASIC," version 2.0, pages 68-80

"Microsoft WordBASIC Macro Developers Kit," version 2.0, pages 74-96

KBCategory: kbmacro
KBSubcategory:
Additional query words: 1.x 1.0 1.10 1.10a 2.0 2.0a winword2
winword 6.0 6.0a 6.0c 2.0a-CD 2.0b properties property controls
control list check combo dropdown macrode.exe checkbox listbox textbox drop
down pushbutton highlight
Keywords : kbmacro
Version : 1.x 2.x 6.0 6.0a 6.0c
Platform : WINDOWS

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: July 30, 1997
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.