Setting Up a Document Event

All the event procedures used to handle document events in Word, Excel or PowerPoint have one thing in common: the document being created, opened, saved, printed, or closed is passed in as the first argument in the event procedure. The naming of the first argument passed into each event procedure is consistent. In Word, the argument is declared as a Document object and is named Doc. In Excel, the argument is declared as a Workbook object and is named Wb. In PowerPoint, the argument is declared as a Presentation object and is named Pres. The following example lists the event procedures you use to respond to the action of opening a document in Word, Excel, and PowerPoint, respectively:

Sub App_DocumentOpen(ByVal Doc As Document)

Sub App_WorkbookOpen(ByVal Wb As Workbook)

Sub App_PresentationOpen(ByVal Pres As Presentation)

Event Naming Convention

In each application the event name follows the name of the document object. The document object in Word, Excel, and PowerPoint is Document, Workbook, and Presentation, respectively, and each appears in the name of document events for each application.

If the word Before is prefixed to the event name, it indicates that the event procedure is called before the action is actually carried out by Word, Excel, or PowerPoint, giving you the opportunity to prevent the application from carrying out the action's default behavior. For example, in Word and Excel, if a document that is being saved doesn't contain a particular property, you can alert the user and cancel the save event. As the previous table shows, PowerPoint doesn't provide any document events that can be cancelled.

Set Up an Event Procedure

The following steps show a simple tip for debugging and testing your solution and for determining exactly when an event procedure is called. Always remember to create a new class module and declare an object of type Application with events before the application's events can be used.

NOTE
You will use the first, second, and fourth steps of the list that follows to set up each of the document event procedures in this chapter. If you complete them once, you don't need to repeat these steps.

  1. Start Word, Excel, or PowerPoint and press ALT+F11 to start the Visual Basic Editor. This example uses Word.

  2. Click Class Module on the Insert menu, add the following code in the class module, and press ENTER.

    3. Public WithEvents App As Application

    Once you press ENTER, the new App object, declared with events, appears in the Object drop-down list in the class module. When you select the new object in the Object drop-down list, the Procedures drop-down list displays the events for the Application object.

  3. Select the object App in the Object drop-down list in the class module and, in the Procedures drop-down list, select any event listed in the table at the beginning of the Quick Guide section. Add the following lines within the event procedure.

    4. Static i As Integer
i = i + 1
Debug.Print "EventProcedureName: " & i

    These three lines are handy for debugging your solution and determining exactly when the event procedure is called. After everything is set up in step 5, every time you create a new document or open, save, print, or close a document, the event should fire. You use the static integer variable i so that when the text from the code line Debug.Print is printed to the Immediate window in the Visual Basic Editor, you can see a change from line to line in the printed text.

    You should change the text EventProcedureName to the procedure name of the event you selected from the Procedures drop-down list.

  4. Click Module on the Insert menu. In the module, named Module1 by default, add the following code:

    5. Dim AppEvents As New Class1

Sub InitEvents()
    Set AppEvents.App = Application
End Sub

    Before an event procedure will run, you must connect the declared object App in the class module to the Application object. Note that the class name Class1 stated just after the New keyword in the declaration statement should be the name of the class module you declared as the App variable in step 2. The class module inserted in step 2 is, by default, Class1, but you can change the name of the class module to anything. If you do, you must also change the class name after the New keyword in the above declaration.

  5. Place the cursor in the InitEvents procedure and press F5 to run the project. After you run the InitEvents procedure, the App object in the class module points to the Word Application object, and the event procedures in the class module will run when the events occur.

  6. Position the Office application window so you can see the Immediate window in the Visual Basic Editor. Perform the action of the event you selected in step 3 above. For example, if you selected the WindowSelectionChange event in Word, start clicking around in the Word document, inserting new content and selecting the text and shapes.

    7. In the Immediate window, you should see the text WindowSelectionChange or the name of the event you used in step 3 to replace the text EventProcedureName. The name of the event is followed by a number. When you perform another action, the number is changed incrementally.

No matter what event you write code for, use this technique to help you debug and test your solutions. It also helps you determine exactly when an event is triggered. The rest of the chapter goes into more depth on each event that is triggered by a user's interaction with and manipulation of content in the active document. You can either use the lists from each of the descriptions for each event or use the technique described in this example to determine when an event triggers.