Working with the Dialog Object

This chapter has briefly considered the Dialogs collection returned by the Application object's Dialogs property. You have also learned about the FileDialog object. Now you learn in more detail how you can use and display Word's built-in dialog boxes by using the Dialog object.

Showing the Dialog Box and Letting Word Execute Actions

After you have a Dialog object, typically by using the Dialog collection's index operator, you can show the dialog box in a variety of ways. The simplest way to show the dialog box associated with a Dialog object is to call the Show method, which displays the dialog box and lets Word execute any action the user takes in the dialog box. The Show method has an optional TimeOut parameter of type Object that takes the number of milliseconds Word will wait before closing the dialog box automatically. If you omit the parameter, Word waits until the user closes the dialog box.

The Show method returns an Integer value that tells you what button the user chose to close the dialog box. If the return value is 1, the user clicked the OK button. If the return value is 2, the user clicked the Close button. If the return value is 0, the user clicked the Cancel button.

Selecting the Tab on a Dialog Box

For tabbed dialog boxes, such as Options, the Dialog object provides a DefaultTab property of type WdWordDialogTab. The DefaultTab property can be set before showing the dialog box to ensure that the dialog box comes up with a particular tab selected. WdWordDialogType is an enumeration that contains values for the various tabs in Word's built-in dialog boxes.

Showing the Dialog Box and Preventing Word from Executing Actions

Sometimes you will want to show a dialog box without letting Word actually execute the action associated with the dialog box. You might want to show the Print dialog box but execute your own custom actions when the user clicks OK in the dialog box, for example.

The Dialog object has a Display method that will show the dialog box while preventing Word from executing the action associated with the dialog box. Just as with the Show method, the Display method takes an optional TimeOut parameter of type Object and returns an Integer value that tells you which button the user clicked to close the dialog box.

After you use the Display method to show a dialog box, you can use the Execute method to apply the action the user took in the dialog box that was shown using the Display method. As an example (one that would likely annoy a Word user), you might show the Print dialog box and detect that a user clicked OK. But then you might prompt again to ask whether the user is sure she wants to print. If the user clicks Yes, you would call the Execute method on the dialog box to print the document, as shown in Listing 8.13.

Listing 8.13. A VSTO Customization That Uses Display and Execute to Confirm Printing

Public Class ThisDocument   Private Sub ThisDocument_Startup(ByVal sender As Object, _     ByVal e As System.EventArgs) Handles Me.Startup     Range.InsertAfter("Test text")     Dim d As Word.Dialog = Application.Dialogs( _       Word.WdWordDialog.wdDialogFilePrint)     Dim result As Integer = d.Display()     If result = -1 Then       Dim r As MsgBoxResult       r = MsgBox("Are you sure you want to print?", _         MsgBoxStyle.YesNoCancel, "Annoying confirmation")       If r = MsgBoxResult.Yes Then         d.Execute()       End If     End If   End Sub End Class 

Getting and Setting Fields in a Dialog Box

It is possible to prefill fields in a dialog box before showing it and to get fields from a dialog box after showing it. Unfortunately, it is rather difficult and inconsistent in availability, and it relies on some obscure functionality that originated from the original programming language for Word, called Word Basic.

The Dialog object you are working with may have several late-bound properties that can be get and set. A late-bound property does not appear in the type definition for the Dialog object, so it cannot be seen using IntelliSense. Therefore, in Visual Basic 2005 a late-bound property can be called directly, but you won't get help from Visual Studio's statement-completion feature when writing the code, as it can't be determined until runtime whether a given property exists.

The available late-bound properties change depending on the type of dialog box that you got from the Dialogs collection. So when you get a wdDialogXMLOptions dialog box, it will have one set of late-bound properties, and when you get a wdDialogFilePrint dialog box, it will have a different set of late-bound properties.

Determining what the late-bound property names are for a particular dialog box involves some searching in older Word Basic help files. To get the Word Basic help files, search the Web for "wrdbasic.exe" to find an installer from Microsoft that installs Word Basic help. After you have installed the Word Basic help file, you can try to find a Word Basic function in the help file that corresponds to the dialog box you are using.

The Word Basic function typically is named as a concatenation of the menu name and command name. The Word Basic function for the Print dialog box in the File menu, for example, is FilePrint. By looking in the Word Basic help file for the FilePrint method, you will find that it has 14 parameters. Table 8.4 shows some of the late-bound properties documented in the Word Basic help file for the FilePrint (and, hence, the Print dialog box).

Table 8.4. Some Late-Bound Properties Associated with the Print Dialog Box

Property Name	Type	What It Does
Range	Selected Integer values	If 1, prints the selection. If 2, prints the current page. If 3, prints the range of pages specified by From and To. If 4, prints the range of pages specified by Pages.
NumCopies	Integer	The number of copies to print.
Pages	String	The page numbers and page ranges to print, such as "1-10, 15", which would print pages 1 through 10 and page 15.

For newer dialog boxes that were not around in Word 95 and are not listed in the Word Basic help file, you can try to figure out how to get to a particular dialog-box option by trial and error. In the XML Options dialog box, for example, which is new to Word 2003 (WdWordDialog.wdDialogXMLOptions), you can determine some of the properties by writing reflection code to try to invoke names that seem reasonable based on the names of the controls in the dialog box. If the code fails, you know that you guessed the wrong property name. If the code succeeds, you have found a property name. In this way, you would discover that AutomaticValidation, IgnoreMixedContent, ShowAdvancedXMLErrors, and ShowPlaceholderText are some of the properties associated with the XML Options dialog box. At this point, however, you are really out there on your own. A search on the Web for "ShowAdvancedXMLErrors," for example, returned no hits; you might be the first person and the last person in the world to use this late-bound property.

Listing 8.14 shows a VSTO customization that prepopulates the Print dialog box with a page range and number of copies to print. It sets and gets the late-bound properties Range, NumCopies, and Pages on the Dialog object. The code in Listing 8.14 will display the Print dialog box without allowing Word to execute any actions. The user can change values in the dialog box. The code shows the values of Range, NumCopies, and Pages after the dialog box has been displayed.

Listing 8.14. A VSTO Customization That Accesses Late-Bound Properties on a Dialog Box

Public Class ThisDocument   Private Sub ThisDocument_Startup(ByVal sender As Object, _      ByVal e As System.EventArgs) Handles Me.Startup      ' Create 20 pages      Dim r As Word.Range = Range()      Dim i As Integer      For i = 1 To 20        r.InsertBreak(Word.WdBreakType.wdPageBreak)      Next      Dim d As Word.Dialog = Application.Dialogs( _        Word.WdWordDialog.wdDialogFilePrint)      ' Set late-bound properties      d.Range = 4      d.NumCopies = 2      d.Pages = "1-10, 15"      Dim result As Integer = d.Display()      ' Get late-bound properties      MsgBox(String.Format("Range is {0}.", d.Range))      MsgBox(String.Format("NumCopies is {0}.", d.NumCopies))      MsgBox(String.Format("Pages is {0}.", d.Pages))   End Sub End Class