Returning a value after .Show-ing a built-in Word dialog box

Word allows us to use most of its built-in dialog boxes.

To do that, we use something like

Word.Application.Dialogs(wdDialogFilePageSetup).Show

The .Show method is supposed to return a value to tell you how the user closed the dialog box. Word's object model documentation says:

The following table shows the meaning of the values that the Show method returns.

Return value	Description
-2	The Close button.
-1	The OK button.
0 (zero)	The Cancel button.
> 0 (zero)	A command button: 1 is the first button, 2 is the second button, and so on.

There have always been problems using the built-in dialog boxes. Some don't work at all. Some parameters for some dialog boxes don't work.

Word 2007 and Word 2010 have introduced many new dialog boxes. Few of them return appropriate values when you use the .Show method. For example:

Problems without any workarounds

• Word.Application.Dialogs(wdDialogContentControlProperties).Show always returns 0, whether the user closes the dialog with the OK button or the Cancel button
• Word.Application.Dialogs(wdDialogCreateSource).Show always returns 0, whether the user closes the dialog with the OK button or the Cancel button
• Word.Application.Dialogs(wdDialogFormatStylesCustom).Show always returns -1, whether the user closes the dialog with the OK or the Cancel button
• Word.Application.Dialogs(wdDialogInsertPlaceholder).Show always returns 0, whether the user closes the dialog with the OK or the Cancel button
• Word.Application.Dialogs(wdDialogInsertSource).Show always returns 0, whether the user closes the dialog with the OK or the Cancel button
• Word.Application.Dialogs(wdDialogStyleManagement).Show always returns -1, whether the user closes the dialog with the OK button or the Cancel button
• Word.Application.Dialogs(wdDialogToolsCompareDocuments).Show always returns -1, whether the user closes the dialog with the OK button or the Cancel button

Problems that have workarounds

• Word.Application.Dialogs(wdDialogBuildingBlockOrganizer).Show always returns 0, even though the dialog only has a Close button (and it should, therefore, return -1)
• Word.Application.Dialogs(wdDialogCompatibilityChecker).Show always returns 0, even though the dialog only has an OK button (and it should, therefore, return -1)
• Word.Application.Dialogs(wdDialogDocumentInspector).Show always returns 0, even though you can only dismiss the dialog by clicking the Close button (so it should return -2)
• Word.Application.Dialogs(wdDialogSourceManager).Show always returns 0, even though the dialog only has a Close button (and it should, therefore, return -2)
• Word.Application.Dialogs(wdDialogStyleManagement).Show always returns 0, even though the dialog only has a Close button (and it should, therefore, return -2)

• Word.Application.Dialogs(wdDialogExportAsFixedFormat).Show always returns 0, whether the user closes the dialog with the Publish button or the Cancel button.

  Use Dialogs(wdDialogFileSaveAs) instead. It doesn't work as advertised, either. But at least it distinguishes between cases, and it's consistent.

  Dialogs(wdDialogFileSaveAs) returns:

  • 0 if the user cancels
  • -1 if the user saves in any format other than PDF or XPS
  • -2 if the user saves as a PDF or XPS file

  The return value of -2 is new in Word 2007. In Word 2003 and before, dialogs(wdDialogFileSaveAs) always returned 0 or -1. This has the potential to introduce problems in old code. This code, for example, while poor, worked have worked perfectly well in Word 2003. It would flummox a user in Word 2007 or Word 2010 who saved as a PDF file:

      'Poor code: do not use
      If Not Dialogs(wdDialogFileSaveAs) = -1 Then
          MsgBox "Are you sure you don't want to save the document?"
      End If

Do all the new dialogs have problems?

No. The .Show method for some dialogs introduced in Word 2007 and Word 2010 returns values as advertised. For example:

• dialogs(wdDialogOMathRecognizedFunctions)
• dialogs(wdDialogToolsOptions) and several other *ToolsOptions* dialogs (such as wdDialogToolsOptionsTypography and wdDialogToolsOptionsCompatibility).

Important note

This page presents findings from my experimentation. Your mileage may vary, as they say.

Related pages on other sites

Getting help with calling Word's built-in dialogs using VBA (and why doing so can be much more useful than you'd think) at the Word MVP FAQ site

How to: Use Built-In Dialog Boxes in Word at Microsoft's MSDN site