[ Go to January 1997 Table of Contents ]

Applications /
Jim Boyce

Write the Perfect Script
You'll earn rave reviews when you create snazzy dialog boxes using Word macros.

I ended my column last month with a cliff-hanger. I described how to create and display a dialog box using WordBasic statements in a macro, but didn't have space left to include much of the actual macro code. Your patience will be rewarded in this month's column, where I offer up some macro code to create a useful dialog box.

If you mastered last month's column, you might want to skim down to the last paragraph on this page. If you need a quick recap, we'll pick up with the Dim statement and Dialog() function. You can use the Dim statement to create a dialog box record that can contain the dialog box's data, and the Dialog() function How To: Applicationsto display the dialog box. You can also store the return value of the Dialog() function to a variable. That variable, in turn, can reveal which button was clicked on the dialog box (OK or Cancel, for example). This enables you to write the macro to process the dialog box accordingly, such as branch to the end of the macro if the Cancel button is selected.

Last month I also explained that each control on the dialog box is identified by a unique field name such as .TextBox1 for a text box and .OptionButton1 for an option button. Within the macro, you manipulate and read the contents or states of the dialog box controls using these field names. For example, assume you've defined a dialog box record using the variable name Dlg. Also, assume you've used the Dialog(Dlg) function to display the dialog box so the user can fill in its blanks. After the dialog box closes, you want to store the contents of the text box named .TextBox1 from that dialog box record to a variable named Stuff$. To do this, use the following statement, specifying the name of the dialog box record and the control's field name:

Stuff$ = Dlg.TextBox1

You can then employ the Stuff$ variable to retain the value of TextBox1 or use it elsewhere. Equally important, you can use a similar method to preload the values and states of dialog box controls. For example, assume that before you display the dialog box, you want to place the text Hello World in TextBox1. You'd use the following statements:

Dlg.TextBox1 = "Hello World"

ReturnValue = Dialog(Dlg)

Again, Dlg is the name of the dialog box record, and TextBox1 is the field name of the control in which you want to place the text. The second statement displays the dialog box and stores the function's return value, indicating the button that was pushed, in the variable ReturnValue.

Every Word document has associated data called document statistics. These data fields include the document's filename, directory path in which the file is located, number of characters in the document, file size and other information. In Word 6.0, this data corresponds to the information in the Document Statistics dialog box. You can access these read-only values within a macro with the DocumentStatistics statement. In Word 7.0, you can use the same statement, or the GetDocumentProperty() and GetDocumentProperty$() functions to retrieve these same types of values, as well as custom-defined properties. For this example, we'll stick with DocumentStatistics. For a list of the DocumentStatistics statement's arguments, highlight the word DocumentStatistics in a macro and press F1.

Approved access

To access document statistics within a macro, first define a dialog record to contain the Document Statistics dialog box data. Then use the GetCurValues statement to update the data. After it's updated, you can retrieve values from the Document Statistics dialog box, even without displaying the dialog box. Here's a sample macro code fragment that retrieves the filename and path of the current document, then displays the information in a message box, all without ever displaying the Document Statistics dialog box:

Dim Dlg2 As Document Statistics

GetCurValues Dlg2

MsgBox "Current file is " + Dlg2.Directory + "\" + Dlg2.FileName

In this example, you're defining a dialog box record named Dlg2, updating the contents of the record, then pulling pieces of information out of the record to display in the message box. The + symbols link the text to form the message string.

Last month's column outlined the dialog box structure. Our goal is to insert some text at the beginning of the report based on the information we enter in the dialog box. In addition, the macro will attach a template to the document based on your selection between the Financial, Marketing or Technical option buttons. Finally, we want the macro to insert an optional Web address at the top of the document to indicate where it is stored on the Internet.

To illustrate how document statistics work, we'll pull the title and author name from the Document Statistics dialog box. Your custom dialog box won't be able to bring up a title and author name until you save the document. Therefore, in this example, you have to save the document and enter the document summary data before running the macro.

First, choose Tools/Macro, select the macro you started for last month's column, then choose Edit. (If you didn't build the macro last month, check my column in the December issue or visit http://www.winmag.com.) Scroll through the macro and place the cursor after the End Dialog statement. See the sidebar (at left) to define the two dialog box records you'll need and to update the Document Statistics dialog box (lines 1-3)

Next, preload the Report Title, Author and Document Title text boxes with the corresponding data from the document statistics dialog (lines 4-6)

You're now ready to display the dialog box and retrieve the information from it. The next two lines of code (7 and 8) display the dialog box and store the return code to a variable. The macro then tests the value of the variable. If the variable was zero, indicating the Cancel button was selected, the macro exits without doing anything else.

The GoTo statement (line 8) causes the macro to jump to the OuttaHere label, which we'll add at the end of the macro. First, add some code to determine which option button is selected and attach a template accordingly (lines 9-16). Note that line 9 uses the OptionGroup1 field. The Dialog Editor automatically created this group to keep together the three option buttons. This lets you evaluate all three option buttons at one time, rather than separately. If the field's value is 0, the first option button is selected (in this case, OptionButton1). A value of 1 indicates the next option button was clicked, and a value of 2 indicates the third option button was the one selected.

The names I've specified in quotes for the document templates (lines 11, 13 and 15) refer to templates I've created and which exist in the Templates folder. You'll reference the names of templates that you have created.

Next, add some code to insert the text from the dialog box at the top of the document (lines 17-23)

That was simple enough. Now test the state of the check box to determine whether or not to insert the Web address. If the value of the check-box field is 1, the check box is checked. A value of 0 indicates it's cleared and a value of -1 indicates it's grayed. In this case, we're only interested in whether it's checked, so we'll test for a value of 1 (lines 24-27)

That takes care of the text. You probably would add statements with each of the previous Insert statements to format the text according to your preferences. For instance, you might format the report title as bold, either directly or through a paragraph style. That's why I placed the Select Case structure to attach the template early in the macro, rather than at the end. Because the macro has already been attached, you can format the text using the styles from the attached template.

You need only one more step to complete the macro. Just before the End Sub statement, create an OuttaHere (line 28) label for the GoTo statement you added previously. This will enable the macro to exit without doing anything else if you choose Cancel in the dialog box.

You now have a quick-and-dirty dialog box that can retrieve data from the document statistics as well as the user. If, when testing the dialog box, you receive a statement that reads "Word cannot open this document template," it's because the option buttons (Financial, Marketing and Technical) have dummy templates. You can either create templates for these option buttons, or omit the FileTemplates statements to correct the error. Download this month's macro here: DLGMACRO.TXT.

Contributing Editor Jim Boyce is the lead author of Windows NT Advanced Technical Reference (Que, 1996). Contact Jim in the "Applications" topic of WINDOWS Magazine's areas on America Online and CompuServe, or care of the editor at the e-mail addresses here.

Master this Macro

1 Dim Dlg1 As UserDialog

2 Dim Dlg2 As DocumentStatistics

3 GetCurValues Dlg2

4 Dlg1.TextBox1 = Dlg2.Title

5 Dlg1.TextBox2 = Dlg2.LastSavedBy

6 Dlg1.TextBox3 = Dlg2.FileName

7 ReturnValue = Dialog(Dlg1)

8 If ReturnValue = 0 Then Goto OuttaHere

9 Select Case Dlg1.OptionGroup1

10 Case

11 FileTemplates .Template = "finance.dot"

12 Case 1

13 FileTemplates .Template = "market.dot"

14 Case 2

15 FileTemplates .Template = "technic.dot"

16 End Select

17 StartOfDocument

18 Insert Dlg1.TextBox1

19 InsertPara

20 Insert Dlg1.TextBox2

21 InsertPara

22 Insert Dlg1.TextBox3

23 InsertPara

24 If Dlg1.CheckBox1 = 1 Then

25 Insert Dlg1.TextBox4

26 InsertPara

27 End If

28 OuttaHere:

29 End Sub

Add this code to last month's macro to create a nifty dialog box. Line numbers are for informational purposes only.

Copyright 1997 CMP Media Inc.

(From Windows Magazine, January 1997, page 269.)