Using Dynamic Dialog Boxes

A dynamic dialog box is one whose contents can change while it is displayed. Many dialog boxes built into Word are dynamic in this sense. For example, the Open dialog box (File menu) is a dynamic dialog box: If you double-click a folder, Word updates the list of files to show the files in the folder you double-clicked.

What Can You Do with a Dynamic Dialog Box?

Here are some examples that demonstrate the capabilities of dynamic dialog boxes. The macros that produce the sample dialog boxes shown in this section are stored in the EXAMPLES.DOT template (Windows) and the MACRO EXAMPLES template (Macintosh) on the Microsoft Word Developer's Kit disk.

Change button names and other text

It can be useful to change the names of buttons and other controls in a dialog box in response to an action. When you choose the Start button in the StopWatch custom dialog box shown in the following illustration, the Start button becomes the Stop button, and the Pause button is enabled. While the dialog box is displayed, the text label that displays the time is updated every second.

Update lists

In a dynamic dialog box, the list of items in a list box can change in response to a user's actions. For example, in the File Browser custom dialog box, shown in the following illustration, the user can double-click a directory in the Directories list box, and the list of files and directories changes in the two list boxes.

Show or hide parts of the dialog box

You can create a dialog box with more than one "panel" of controls, in which one panel is displayed and one or more other panels are hidden. This sort of dialog box is similar to the dialog boxes built into Word that have "tabs" with which you can display different controls. In the Master Document Macro custom dialog box, you can click the Master Document or Subdocuments option buttons to display two different panels of controls.

Display a built-in dialog box

It is sometimes useful to provide access from within a custom dialog box to a dialog box built into Word. In the Close File custom dialog box, shown in the following illustration, you can choose the Word Count button to check the word count of the file before closing it. When you dismiss the Word Count dialog box, you return to the Close File dialog box. Note that you cannot display a second custom dialog box while the Close File dialog box is displayed; only one custom dialog box can be displayed at a time.

Enable and disable controls

With a dynamic dialog box, you can enable and disable controls as appropriate. In the Add File custom dialog box shown in the following illustration, the Info To Record option buttons are disabled by default but are enabled if the user selects the Record Addition In Log check box.

How to Make a Dialog Box Dynamic

A dynamic dialog box begins with a standard dialog box definition. You then add three elements to make the dialog box dynamic:

• A dialog function. The dialog function responds to events and changes the appearance of the dialog box. The dialog function, in short, is what makes a dialog box dynamic. All the instructions that are carried out while the dialog box is displayed are either placed within this function or in subroutines and user-defined functions called from this function.
• A dialog function argument in the Begin Dialog instruction that calls the dialog function.
• Identifiers for any dialog box controls that the dialog function acts on or gets information from. Most of the instructions in a custom dialog box definition already include identifiers for the controls they describe.

How a Dialog Function Works

When Word reads the Dialog or Dialog() instruction that displays the dialog box, it calls the dialog function and begins initializing the dialog box. Initialization happens between the time the dialog function is called and the time the dialog box appears on the screen. Word calls the dialog function and says, in effect, "Is there anything you'd like to do before the dialog box is displayed?" The dialog function can do nothing or can respond in some way.

Typical actions that a dialog function might take during initialization include disabling or hiding dialog box controls. By default, dialog box controls are enabled, so if you want a control to be disabled when a dialog box is first displayed, it must be disabled during initialization. Likewise, all dialog box controls are shown by default rather than hidden, so if you want to create a dialog box with more than one panel of controls, any controls that you don't want to show when the dialog box is first displayed must be hidden during initialization.

After initialization, Word displays the dialog box. When the user takes an action, such as selecting an option button, Word calls the dialog function and passes values to the function to indicate the kind of action taken and the control that was acted upon. For example, if the dialog box contains a list of graphics filenames, and you click one of the filenames, the dialog function will be called and could respond by displaying the selected graphics file in a picture control.

Word also calls the dialog function when the dialog box is "idle" — that is, while the user is not acting on the dialog box. In fact, as soon as the dialog box begins initializing and for as long as it is displayed, Word sends a continuous stream of idle messages to the dialog function — more than one a second. This stream is interrupted only when the user acts on the dialog box in some way. Most dialog functions are designed to ignore idle messages, but they can be used to continuously update a dialog box (as in the StopWatch custom dialog box example described earlier in this section).

Calling the Dialog Function

The link between the dialog box and its function is established in the dialog box definition. Specifically, a .FunctionName argument is added to the Begin Dialog instruction, where .FunctionName matches the name of the dialog function. Here's the syntax for the instruction:

Begin Dialog UserDialog [HorizPos, VertPos,] Width, Height, Title$, .FunctionName

Dialog Box Control Identifiers

A dialog function needs an identifier for each dialog box control that it acts on or gets information from. Normally, the dialog function uses string identifiers, but it can also use numeric identifiers. For information on numeric identifiers, see "Numeric Identifiers," which follows.

String identifiers are the same as the identifiers used with a dialog record. If you use the Dialog Editor to create a dialog box, the Dialog Editor automatically creates an identifier for any control that can store a value in a dialog record. For example, in the following instruction, .CheckBox1 is the string identifier created by the Dialog Editor:

CheckBox 398, 24, 109, 16, "Check Box", .CheckBox1

Don't confuse a dialog box control's label and its identifier. An identifier begins with a period (.) and is the last argument in a dialog box control instruction. In the previous instruction, "Check Box" is a check box label and .CheckBox1 is its identifier.

Unlike other elements of WordBasic, string identifiers are case-sensitive. When an instruction in a dialog function refers to an identifier, it must match the case of the identifier.

Numeric Identifiers

Numeric identifiers are an alternative way of referring to dialog box controls. You can use numeric identifiers to improve the performance of a dialog function when a dialog box contains many controls. But instructions that use numeric identifiers are more difficult to read than instructions that use string identifiers.

Numeric identifiers are numbers, starting at 0 (zero), that correspond to the positions of dialog box control instructions within a dialog box definition. The following example shows the numeric identifiers for four dialog box controls. Note that the numeric identifier is not included in the instruction for a dialog box control; the number associated with a control is determined by the control's place within the dialog box definition. If the position of the control changes, so does its numeric identifier. For example, in the following dialog box definition, the Text instruction is first and so has a numeric identifier of 0 (zero). If you moved the instruction so that it was the last one in the dialog box definition, it would have an identifier of 3 (assuming no new instructions were added).

Begin Dialog UserDialog 370, 92, "Fax Info"
    Text 14, 7, 96, 13, "Fax Number:"        'Numeric identifier is 0
    TextBox 14, 23, 160, 18, .Fax$            'Numeric identifier is 1
    OKButton 270, 6, 88, 21                    'Numeric identifier is 2
    CancelButton 270, 30, 88, 21                'Numeric identifier is 3
End Dialog

Dialog Function Syntax

A dialog function is just like any other user-defined function except that it takes three required arguments. The syntax is as follows:

Function FunctionName(ControlID$, Action, SuppValue)
Series of instructions to determine a value
FunctionName = value
End Function

The function will generate an error if one of the three mandatory arguments — ControlID$, Action, and SuppValue — is missing or if an additional argument is added. The arguments are variables, however, and you can use any variable name you want. For example, you could use id$ instead of ControlID$ as the name for the first argument.

A dialog function returns a value when the user chooses a command button — the OK button, Cancel button, or a push button. Word acts on the value returned by either closing the dialog box associated with the function or continuing to display it. By default, the dialog function returns 0 (zero), which causes Word to close the dialog box, regardless of which button was chosen. But if you assign a nonzero value to the dialog function, the dialog box remains displayed. By keeping the dialog box displayed, the dialog function allows the user to carry out more than one command from the same dialog box. For examples, see "Responding to a Double-Click" and "Responding to a Push Button" later in this chapter.

The DialogFunctionDemo macro, stored in the EXAMPLES.DOT template (Windows) and the MACRO EXAMPLES template (Macintosh) on the Microsoft Word Developer's Kit disk, displays the values of the arguments passed to a dialog function while a custom dialog box is displayed. You may find this macro, along with the following discussion, a useful starting place when you begin to work with dialog functions.

Here is a closer look at each dialog function argument.

ControlID$

Receives the identifier string of the dialog box control associated with a call to the dialog function. For example, if the user selects a check box, the dialog function is called and the ControlID$ argument receives the identifier for the check box.

Action

Identifies the action that calls the dialog function. There are six possible actions that can call the dialog function, each with a corresponding Action value.

SuppValue

Receives supplemental information about a change in a dialog box control. The information SuppValue receives depends on which control calls the dialog function. The following SuppValue values are passed when Action is 2 or 3.

Dialog Functions and Variables

Like variables in other user-defined functions, variables defined in a dialog function lose their values when the function ends. A dialog function is available for as long as a dialog box is displayed, so it's easy to imagine that variables in the dialog function last that long as well. But the dialog function is called not once but many times while the dialog box is displayed, and the dialog function's variables lose their values after each call. If you need variables used in a dialog function to last as long as a dialog box is displayed, you must use the Dim statement to declare them as shared variables.

Dialog Function Techniques

This section provides examples that demonstrates how to carry out common dialog function tasks. These examples use a set of WordBasic statements and functions used only within dialog functions. You can recognize these statements and functions in that they all begin with "Dlg." For example, DlgEnable and DlgFocus are two statements used only in dialog functions. For a complete list of these statements and functions, see "Statements and Functions Used in Dialog Functions" later in this chapter. The macros shown in this section are stored in the EXAMPLES.DOT template (Windows) and the MACRO EXAMPLES template (Macintosh) on the Microsoft Word Developer's Kit disk.

Responding to Clearing or Selecting a Check Box

When the user selects or clears a check box, Word calls the dialog function. In the following example, a dialog function causes an option button group to be enabled or disabled when the user selects or clears the Record Addition In Log check box.

Word passes these values to the dialog function when the user selects or clears a check box: an Action value of 2, a ControlID$ value containing the identifier for the check box, and a SuppValue that indicates whether the check box is selected or cleared.

The following dialog function uses a Select Case control structure to check the value of Action. (The SuppValue is ignored in this function.) An If conditional then checks the value of the ControlID$. If the identifier is "RecordAddition" — the identifier assigned to the Record Addition In Log check box — DlgEnable either enables or disables the option buttons. Because the option buttons are disabled when the dialog box is first displayed and the check box is cleared, selecting the check box corresponds to enabling the option buttons.

Sub MAIN
Begin Dialog UserDialog 376, 158, "Add File ", .EnableFunction
    Text 8, 10, 73, 13, "Filename:"
    TextBox 8, 26, 160, 18, .Filenametext
    CheckBox 8, 56, 203, 16, "Record Addition in Log", .RecordAddition
    GroupBox 8, 79, 356, 70, "Info to Record:", .Group
    OptionGroup  .InfoChoice
        OptionButton 18, 100, 189, 16, "Author Information", .Authorinf
        OptionButton 18, 118, 159, 16, "File History", .History
    OKButton 277, 8, 88, 21
    CancelButton 277, 32, 88, 21
End Dialog
Dim dlg As UserDialog
DisableInput 1
x = Dialog(dlg)
DisableInput 0
End Sub

Function EnableFunction(id$, action, suppval)
Select Case action
Case 1                                'Dialog box initializes
    DlgEnable "Group", 0                'Disable group box
    DlgEnable "InfoChoice", 0        'Disable option buttons
Case 2                                'User selects a dialog box option
    If id$ = "RecordAddition" Then
        DlgEnable "Group"            'Enable/disable group box
        DlgEnable "InfoChoice"        'Enable/disable option buttons 
    End If
Case Else
End Select
End Function

Responding to Selecting an Item in a List Box, Drop-Down List Box, or Combo Box

Word calls the dialog function associated with a dialog box when the user selects an item in a list box, drop-down list box, or combo box. The dialog function can identify the item selected and act accordingly. In the following example, the dialog box presents a list of graphics and displays the graphic corresponding to the selected name. When the user selects a different name, the dialog function changes the graphics display.

In the following dialog function, the If conditional tests for an Action value of 2, which indicates that the user has acted on a control. A nested If conditional then tests ControlID$ to see if the user acted on the list box, which has the identifier "ListBox1." Then the DlgText$() function is used to return the text of the item selected in the list box. The text is the name of a graphic stored in an AutoText entry, which the DlgSetPicture instruction then displays. The dialog box definition that defines the dialog box is not shown in this example.

Function ShowPicture(id$, action, suppval)
If action = 2 Then     'The user selects a control
    If id$ = "ListBox1" Then
        picturename$ = DlgText$("ListBox1")
        DlgSetPicture "Picture1", picturename$, 1
    End If
End If
End Function

Responding to a Double-Click

In most built-in dialog boxes in Word, you can double-click an option button or an item in a list to close the dialog box and carry out the settings of the dialog box. Double-clicking is usually a shortcut for selecting an item and then choosing the OK button. Custom dialog boxes work this way by default.

In some Word dialog boxes, though, double-clicking an item in a list does not close the dialog box. For example, in the Open dialog box (File menu), when you double-click a folder, Word displays the files in that folder and does not close the dialog box. Using a dialog function, you can make a custom dialog box behave in the same way. The following example shows how a custom dialog box allows the same action.

Here is the dialog function, with some instructions removed for clarity:

Function FileBrowserFunction(id$, action, suppval)
If action = 2 Then
    If id$ = "OK" And DlgFocus$() = "listdirs" Then
        'Series of instructions to update the directory and file lists
        FileBrowserFunction = 1
    End If
End If
End Function

The first If conditional tests for an Action value of 2, meaning that the user has acted on a control. The nested If conditional then tests for two conditions: when the ControlID$ value is "OK" (the identifier for the OK button) and when the focus is on the Directories list box (whose identifier is "listdirs"). This compound condition is met only when the user double-clicks an item in the Directories list box (if the user clicks just once, the ControlID$ is "listdirs" rather than "OK").

The final key instruction is FileBrowserFunction = 1. By default, when the user chooses a command button such as the OK button, Cancel button, or a push button, Word closes the dialog box. In this case, when the user double-clicks an item in a list box, it has the same effect. But a dialog box remains displayed if the dialog function returns a nonzero value; that is the purpose of the FileBrowserFunction = 1 instruction.

The technique described here works not only with the OK button, but with any default command button specified with the DefaultButton argument of a Dialog() instruction. The dialog box does not need to contain an OK button. For more information on setting a default command button, see "Displaying the Dialog Box" earlier in this chapter or Dialog in Part 2, "WordBasic Reference."

Responding to a Push Button

In the following example, the user can choose the Word Count button to display the built-in Word Count dialog box; the Close File custom dialog box remains displayed and will be available when the user closes the Word Count dialog box. Note that you cannot display a second custom dialog box while the Close File dialog box is displayed; only one custom dialog box can be displayed at a time.

Here is the dialog function, with some instructions removed for clarity. The key instruction that allows the Close File dialog box to remain displayed after the Word Count button is chosen is CloseFileFunction = 1, which causes the dialog box to remain displayed.

Function CloseFileFunction(id$, action, suppval)
If action = 2 Then
    If id$ = "wordcount" Then
        'Series of instructions to display the Word Count dialog box
        CloseFileFunction = 1
    End If
End If
End Function

Responding to Typing in a Text Box or Combo Box

After the user types in a text box or combo box and uses the mouse or the TAB key to move to a different dialog box control, Word calls the dialog function and passes the following values:

• A ControlID$ value equal to the identifier of the text box or combo box
• An Action value of 3 (rather than 2, as with all the other controls)
• A SuppValue value indicating the number of characters the user typed

In the following example, the dialog function is called when the user leaves the first text box. If the user does not type a valid social security number, the dialog function displays a message box.

Here is the dialog function:

Function TestNumber(id$, action, suppval)
    If action = 3 Then            
            If id$ = "socsecnum" And suppval <> 11 Then
                MsgBox "Not a valid " + Chr$(13) + \
                         "social security number."
                wrongnumberflag = 1
            End If
    ElseIf action = 4 Then        
            If wrongnumberflag = 1 Then
                DlgFocus "socsecnum"
                wrongnumberflag = 0
            End If
    End If
End Function

Note that the function tests for Action values 3, corresponding to a text change, and 4, corresponding to a change of focus. When an Action 3 value is passed, the function uses the SuppValue argument to test the number of characters in the text box. If the number of characters doesn't correspond to the number required for a correct social security number, the dialog function displays a message box and sets the variable wrongnumberflag to 1. Immediately after the Action 3 value is passed, an Action value of 4 is passed. If wrongnumberflag is set to 1, the dialog function returns the focus to the social security text box and resets wrongnumberflag to 0 (zero). You cannot use the DlgFocus statement when Action has a value of 3, because the Action 4 value that follows overrides it, changing the focus back to wherever the user intended to move it. Hence the wrongnumberflag variable is needed to indicate whether the focus should be changed when the Action 4 value is passed.

Responding to a Change in the Focus

Whenever the user moves the focus from one dialog box control to another, Word calls the dialog function and passes the following values:

• A ControlID$ value equal to the identifier for the control that is gaining the focus
• An Action value of 4
• A SuppValue value corresponding to the numeric identifier for the control that lost the focus

In the following example, the dialog function changes the "banter" text (the text that appears at the bottom of the dialog box) according to which control has the focus. For example, when the focus is on the Phone Number text box, the dialog function changes the banter text to read "Please enter a phone number."

The following instructions would be added to the Action 4 instructions in the TestNumber dialog function (shown in the previous example) to include the banter text functionality:

If id$ = "socsecnum" Then
    DlgText$ "Text1", "Please enter a social security number."
ElseIf id$ = "phone" Then
    DlgText$ "Text1", "Please enter a phone number."
End If

Displaying More Than One Panel of Controls

Dialog functions let you define more than one panel of controls in a dialog box. By organizing controls into panels, you can present a large number of controls in a single dialog box. This example shows a two-panel dialog box.

To create a two-panel dialog box, you use the Dialog Editor to design two separate dialog boxes corresponding to the two panels of the single dialog box; you then merge the two dialog box definitions into a single definition. When Word first displays the dialog box, one of the panels must be hidden; you'll have a mess if both panels are displayed at the same time.

When the dialog box in the following illustration is first displayed, it shows the Subdocuments controls, which means that the Master Document controls must be hidden while the dialog box is being initialized.

To hide the controls in the Master Document panel, the dialog function calls a subroutine named ShowHidePanel:

Sub ShowHidePanel(FirstCtrl, LastCtrl, ShowOrHide)
For count = FirstCtrl To LastCtrl
    DlgVisible count, ShowOrHide
Next        
End Sub

In this subroutine, a For¼Next loop and a DlgVisible instruction are used to show or hide controls in a panel. The instructions to define the Master Document controls are grouped together in the dialog box definition. They have the numeric identifiers 13 through 18 (the first Master Document control is the thirteenth instruction within the dialog box definition). The For¼Next loop counts from FirstCtrl to LastCtrl—13 to 18, in this case. For each iteration, the DlgVisible instruction shows or hides the control with the numeric identifier count. If the ShowOrHide variable is 1, DlgVisible shows the controls; if it is 0 (zero), DlgVisible hides them.

In Word version 6.0 for the Macintosh and Windows NT and in Word version 7.0, a single DlgVisible instruction can be used to show or hide a range of controls, so a separate subroutine such as ShowHidePanel is not needed. For example, to hide the Master Document controls in the preceding example, the dialog function would simply run the following instruction:

DlgVisible 13, 18, 0

For more information, see DlgVisible in Part 2, "WordBasic Reference."

To switch panels while the dialog box is displayed, the dialog function must hide the panel of controls currently displayed and show the other panel. Here is the If conditional that checks which panel is selected. Note that Case 2 matches an Action value of 2, which indicates that the user has acted on a control.

Case 2
    If identifier$ = "masterdocs" Then
        ShowHidePanel 13, 18, 1            'Show master doc controls
        ShowHidePanel 7, 12, 0            'Hide subdoc controls
    ElseIf identifier$ = "subdocs" Then
        ShowHidePanel 13, 18, 0            'Hide master doc controls
        ShowHidePanel 7, 12, 1            'Show subdoc controls
    End If

The If conditional calls the ShowHidePanel subroutine and uses it to show or hide the panels as appropriate.

Numeric identifiers and For¼Next loops provide an efficient way to manipulate panels of controls. Since the numeric identifier of a control depends on its place within the dialog box definition, you must be careful about changing the order of instructions within the dialog box definition.

The wizards that come with Word use this technique to manage the panels of a wizard dialog box. For a detailed description of managing panels in wizards, see "Creating a Wizard" in Chapter 9, "More WordBasic Techniques."

Tip

Many Word dialog boxes with tabs "remember" which tab was selected when the dialog box was last closed. The theory is that the user is most likely to want to use the panel of controls that was last displayed. You can achieve this effect in WordBasic by storing the final dialog box setting in a settings file. For information on using settings files, see Chapter 9, "More WordBasic Techniques."

Updating Text Continuously in a Dialog Box

You can use a dialog function to update a dialog box continuously. In the example shown and described here, the dialog function updates the text item displaying the time elapsed every second.

Here is the dialog function, with all but one Case in the Select Case control structure removed for clarity:

Function Stopwatch(id$, action, suppval)
Select Case action
    Case 5
        If startflag = 1 Then
            newnow = (Now() - oldnow)
            thissecond$ = LTrim$(Str$(Second(newnow)))
                If thissecond$ <> thissecondold$ Then
                    thishour$ = Str$(Hour(newnow))
                    thisminute$ = LTrim$(Str$(Minute(newnow)))
                    fullstring$ = thishour$ + ":" + thisminute$ + ":"\
                                     + thissecond$
                    DlgText$ "Text1", fullstring$
                    thissecondold$ = thissecond$
                End If
        End If
        Stopwatch = 1
    Case Else
End Select
End Function

Word begins sending "idle" (Action 5) messages to the dialog function as soon as the dialog box is initialized. As long as no other action takes place, Word continues sending this idle message until the dialog box is closed. However, the text should only update after the user chooses the Start button. Therefore, all the statements following Case 5 depend on whether startflag is equal to 1 (earlier in the dialog function, startflag is set to 1 when the user chooses the Start button); if startflag is not equal to 1, the text is not updated.

A second point to observe is that Word sends idle messages to the dialog function at the rate of more than one a second. If the text were updated each time it received the idle message, the text would be jittery. The second If conditional therefore tests whether the time has changed and only updates the text every second. Note that startflag and thissecondold$ must be declared as shared variables before the main subroutine; if they were not declared as shared variables, they would lose their value each time the dialog function was called.

Storing and Loading Dynamic Dialog Box Settings

It's often useful to store a dialog box's settings when the user closes it and to load the settings the next time the dialog box is displayed so that the settings are the same as the ones the user last saw. For example, the dialog box for the Master Document macro, shown in the following illustration, contains a number of check boxes whose settings it would be useful to save.

In Windows, you use the SetPrivateProfileString and GetPrivateProfileString$() instructions to store dialog box settings. For information on using these instructions, see "Using Settings Files and Document Variables" in Chapter 9, "More WordBasic Techniques."

On the Macintosh, you can use the DlgStoreValues and DlgLoadValues() instructions to store and load settings. Unlike SetPrivateProfileString and GetPrivateProfileString$(), which require a separate instruction for each setting stored or loaded, a single DlgStoreValues or DlgLoadValues() instruction can store or load all of the settings in a dialog box. For dialog boxes with a large number of settings to store and load, DlgStoreValues or DlgLoadValues() offer a significant improvement in performance. DlgStoreValues and DlgLoadValues() require a dialog function; if you want to use them with a dialog box that would not otherwise need a dialog function, you can simply create a dialog function just for these intstructions.

The following dialog function (with some instructions removed for clarity) shows how DlgStoreValues and DlgLoadValues() can be used to store and load check-box settings:

Function MyDlgFunction(id$, action, suppval)
Select Case action
    Case 1
        success = DlgLoadValues("Dialog Settings", "MasterDocDialog")
    Case 2
        If id$ = "OK" Then 
            DlgStoreValues "Dialog Settings", "MasterDocDialog")
        End If
    Case Else
End Select
End Function

The DlgLoadValues() instruction runs when the dialog box is initialized (Action 1). The DlgStoreValues instruction runs when the the user closes the dialog box by choosing the OK button. Note that if the user closes the dialog box by choosing the Cancel button, the dialog box settings are not stored. By default, DlgStoreValues and DlgLoadValues() store and load most dialog box settings, but you can also control whether or not individual settings are stored and loaded. For more information, see DlgStoreValues and DlgLoadValues() in Part 2, "WordBasic Reference."

Statements and Functions Used in Dialog Functions

WordBasic includes a set of statements and functions that are used only within dialog functions. The statements act on dialog box controls and the dialog functions return information about them. For example, you use the DlgVisible statement to hide or display a dialog box control; DlgVisible() returns a value determined by whether the control is displayed or hidden.

For complete information on these statements and functions, see the corresponding entries in Part 2, "WordBasic Reference."