Working with Dialog Records

You can create a special variable called a dialog record that stores the settings of a Word dialog box. You can use dialog records for Word dialog boxes in the following two ways:

To retrieve or change the settings of dialog box options without displaying the dialog box.
To display a Word dialog box and change the settings of options in the dialog box. Generally, when you display a dialog box, its settings reflect the current state of the active document or of Word itself. But you might want to change the settings displayed in a dialog box. For example, the Summary Info dialog box (File menu) normally shows the name of the document's original author. A macro can place a value in a dialog record for the Summary Info dialog box so that when the dialog box is displayed, the original author's name is automatically replaced with a different name.

Defining a Dialog Record

You use the Dim statement to define a dialog record. Here is the syntax:

Dim DialogRecord As DialogBoxName

DialogRecord can be any name you choose that isn't a reserved word. The limitations are the same as those for string and numeric variables (see "Variables" in Chapter 3, "WordBasic Fundamentals"). DialogBoxName can be any WordBasic statement name that corresponds to a dialog box. For example, the WordBasic statement that corresponds to the Open dialog box on the File menu is FileOpen, so "FileOpen" is a valid DialogBoxName. If you're not sure what the valid DialogBoxName for a dialog box is, see "Language Summary" and "Statements and Functions" in Part 2, "WordBasic Reference."

Here are some examples of dialog records:

Dim FPrec As FormatParagraph            'Define a dialog record "FPrec" for
                            'the FormatParagraph dialog box

Dim Fontrecord As FormatFont            'Define a dialog record "Fontrecord"
                            'for the FormatFont dialog box

Dim TOVrec As ToolsOptionsView        'Define a dialog record "TOVrec"
                            'for the ToolsOptionsView dialog box

As the last example shows, you can sometimes specify the tab as well as the dialog box name for dialog boxes that contain tabs. That is, you can specify "ToolsOptionsView," not merely "ToolsOptions." To check whether you can specify a tab in this way for a particular dialog box, see the entry for the statement that corresponds to the dialog box in Part 2, "WordBasic Reference."

Retrieving and Changing Dialog Box Settings

Once you define a dialog record for a dialog box, you use the GetCurValues statement to place the current values of the dialog box into the dialog record. The following example copies the current settings of the View tab in the Options dialog box (Tools menu) into the TOVrec dialog record:

Dim TOVrec As ToolsOptionsView        'Define a dialog record "TOVrec"
GetCurValues TOVrec                    'Get the current values

You can change or retrieve the values of the dialog box settings stored in a dialog record by referring to them with the following syntax:

DialogRecord.DialogBoxOption

DialogBoxOption is an argument for the WordBasic statement that corresponds to the dialog box whose options are stored in DialogRecord. For the list of valid arguments, see the entry for the corresponding WordBasic statement in Part 2, "WordBasic Reference."

The following example retrieves the current setting of the Picture Placeholders check box on the View tab in the Options dialog box (Tools menu) and places it in the variable picture:

Dim TOVrec As ToolsOptionsView
GetCurValues TOVrec
picture = TOVrec.PicturePlaceHolders

You change the value of an option in a dialog record by assigning it a value, just as you assign a value to any other variable. For example:

Dim TOVrec As ToolsOptionsView
GetCurValues TOVrec
TOVrec.PicturePlaceHolders = 1
ToolsOptionsView TOVrec

In this example, the .PicturePlaceHolders argument is given a value of 1, which corresponds to selecting the Picture Placeholders check box. The final instruction in the example (ToolsOptionsView TOVrec) puts the values stored in the TOVrec into effect. This instruction is required because changing values in a dialog record does not in itself cause changes to occur in Word. Only the WordBasic statement that corresponds to the dialog box can put the changes into effect.

The following WordBasic instruction is equivalent to the four instructions in the previous example:

ToolsOptionsView .PicturePlaceHolders = 1

As you can see, it's not very efficient to use a dialog record to change the value of a single option in a dialog box. But if you create a dialog record to retrieve dialog box values, you can use the dialog record to change a value conditionally. The most common use of this technique is to "toggle" a dialog box option.

Using a Dialog Record to Toggle a Check Box

To toggle something means to reverse its current "state" or value. You can toggle a check box in a dialog box because it has two "opposite" values — selected and cleared. The same is true of some Word commands. For example, when you choose the Ruler command from the View menu, Word hides the ruler if it was displayed or displays the ruler if it was hidden. The current state of the ruler (displayed or hidden) is reversed each time.

Using the appropriate dialog record, you can create a macro to toggle any check box. You can then assign the macro to a shortcut key or menu for quick access. The following macro toggles the Paragraph Marks check box on the View tab in the Options dialog box (Tools menu) to show or hide paragraph marks:

Sub MAIN
    Dim TOVrec As ToolsOptionsView    'Define a dialog record "TOVrec"
    GetCurValues TOVrec                'Get the current values
    If TOVrec.Paras = 1 then            'If on
        TOVrec.Paras = 0                'turn off
    Else                                'Otherwise
        TOVrec.Paras = 1                'turn on
    End If
    ToolsOptionsView TOVrec            'Reset the dialog
End Sub

The following macro uses a slightly different technique to show or hide hidden text:

Sub MAIN
    Dim TOVrec As ToolsOptionsView            'Define a record "TOVrec"
    GetCurValues TOVrec                         'Get the current values
    TOVrec.Hidden = Abs(TOVrec.Hidden - 1)    'Reverse state
    ToolsOptionsView TOVrec                     'Reset the dialog
End Sub

This macro uses the expression Abs(TOVrec.Hidden - 1) to toggle the value of the Hidden Text check box on the View tab in the Options dialog box. Here's how it works. The Hidden Text check box can have the value 0 (zero) if it is not selected or 1 if it is selected:

If the check box is not selected, then TOVrec.Hidden - 1 is equivalent to 0–1, or –1. The Abs() function makes the negative number positive, so the final result of Abs(TOVrec.Hidden - 1) is 1, which selects the check box.
If the check box is selected, then TOVrec.Hidden - 1 is equivalent to 1–1, or 0 (zero). The Abs() function has no effect in this case, and the final result of Abs(TOVrec.Hidden - 1) is 0 (zero), which clears the check box.

Displaying a Dialog Box

Once you have created a dialog record, you can use the Dialog statement or Dialog() function to display the corresponding dialog box. This is useful if you want your macro to present a dialog box so that a user can set the options he or she wants before the macro continues. The following example displays the Options dialog box (Tools menu) with the View tab showing and then runs ToolsOptionsView after the user closes the dialog box.

Dim TOVrec As ToolsOptionsView    'Define a dialog record "TOVrec"
GetCurValues TOVrec                'Place current values in record
Dialog TOVrec                    'Display dialog box
ToolsOptionsView TOVrec            'Run ToolsOptionsView with new settings

Note that the GetCurValues instruction is necessary. Without this instruction, the macro would display the dialog box with no values — it would not reflect the current state of Word. The ToolsOptionsView instruction is necessary for the settings that the user chooses in the dialog box to have an effect. If this instruction were left out, the user could change settings and then choose the OK button, but Word would not carry out the command.

If you want to modify dialog box settings before displaying the dialog box for the user, you just change the settings of the dialog record options before running Dialog or Dialog(). The following example creates a dialog record for the Summary Info dialog box (File menu) and changes the contents of the Author box:

Dim FSIrecord as FileSummaryInfo        'Define a dialog record "FSIrecord"
GetCurValues FSIrecord                'Get the current values
FSIrecord.Author = "Louis Caspary"    'Place a name in the Author box
Dialog FSIrecord                        'Display Summary Info dialog box
FileSummaryInfo FSIrecord            'Do FileSummaryInfo instruction

The Dialog instruction displays the Summary Info dialog box with the name "Louis Caspary" in the Author box, as shown in the following illustration.

Checking How a Dialog Box Is Closed

When a macro displays a dialog box, it also needs to test how the user closes the dialog box. If the user chooses the OK button, the macro should carry out the command associated with the dialog box. If the user chooses the Cancel button, the macro should not carry out the command. The way you check how a dialog box is closed depends on whether you use the Dialog statement or the Dialog() function to display a dialog box:

If a dialog box is displayed with the Dialog() function, the Dialog() function returns a value corresponding to the button used to dismiss the dialog box. You can then use that value in a conditional statement to determine how the macro should proceed.
If a dialog box is displayed with the Dialog statement and the user chooses the OK button or the Close button, Word moves to the next statement in the macro. But if the user chooses the Cancel button, Word generates an error that you can handle with an On Error statement.

Here is an example that uses the Dialog() function and an If conditional to test whether the user chooses the OK button or the Cancel button to dismiss a dialog box:

Dim FSIrecord as FileSummaryInfo        'Define a dialog record "FSIrecord"
GetCurValues FSIrecord                'Get the current values
FSIrecord.Author = "Louis Caspary"    'Place a name in the Author box
choice = Dialog(FSIrecord)            'Display dialog and return button
If choice = -1 Then                     'If "OK" then
    FileSummaryInfo FSIrecord        'do FileSummaryInfo with changes
End If

The OK button returns a value of –1; the Cancel button returns 0 (zero). In this example, the value returned by Dialog(FSIrecord) is stored in the variable choice. If the user chooses the OK button, then the macro runs the FileSummaryInfo statement — the WordBasic statement corresponding to the Summary Info dialog box. Otherwise, nothing happens.

In the following example, the On Error Goto statement is used to trap the error generated by the Cancel button when the Dialog statement is used to display the Open dialog box:

Dim FOrecord as FileOpen                'Define a dialog record "FOrecord"
GetCurValues FOrecord                'Get the current values
On Error Goto trap                    'Go to the "trap" label if the user
                                    'chooses the Cancel button
Dialog FOrecord                        'Display the Open dialog box
FileOpen FOrecord                    'Carry out FileOpen with changes
Goto bye                                'Go to the "bye" label
trap:                                'Label for On Error Goto statement
MsgBox "Macro cannot proceed."        'Error message
bye:                                    'Label for Goto statement

This more elaborate example uses an On Error Goto instruction to present a message to the user if he or she chooses the Cancel button. The MsgBox instruction informs the user that the macro cannot continue because the user did not open a file. For more information on error trapping, see Chapter 7, "The Well-Behaved Macro."