Chapter 10

Handling Window and Content Interaction Events

Chapter Objectives

Estimated time: 60 minutes

A developer can think of documents in two ways. First, there's the content—the text, tables, charts, shapes, pictures, and so on. Second, there's how the user interacts with the content using the mouse, the keyboard, and the tools on the menus and toolbars when a document is displayed in a window. When you start an Office application and open a document, you see the document in a window. You navigate to a specific part of the document, click where you want to add or remove content using the mouse, and then use the keyboard to type text or click buttons on a toolbar to format the content, for example.

When you interact with content through the mouse and keyboard, you trigger, or "fire" events in the background. Each Office application tracks the interaction, determining what document is displayed and what you've selected, clicked, right-clicked, or double-clicked. Once it determines the specific content you're interacting with, the application updates its menus and toolbars, displays a specific dialog box or shortcut menu, or updates a status bar.

As a developer, you can handle the same events the application does, and thus you can customize what happens when the user interacts with the content. This chapter describes the events that the Office application fires; common scenarios that you can address in your solution with them; and ways you can customize the user's experience with custom dialog boxes, shortcut menus, and menu and toolbar customizations.

Quick Guide: Setting Up an Event to Track User Interaction

This quick guide explains how to connect to the Application-level events provided by an Office application to track user interaction with content. What events can you handle? This chapter describes the selection change, double-click, right-click, and the window activate and window deactivate events. As you'll see throughout this chapter, these events enable scenarios like those listed below.

NOTE
All the events described in this chapter are triggered whether the event occurs in the user interface or programmatically through the object model (using Microsoft Visual Basic for Applications).

Set Up an Event

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

  1. Start Microsoft Word, Microsoft Excel, Microsoft PowerPoint, or Microsoft Outlook 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 then 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 Procedure drop-down list shows the events for the Application object.

  3. Select the new object App in the Object drop-down list in the class module and then select WindowSelectionChange in the Procedures drop-down list. Add the following lines within the event procedure:

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

    These three lines are great for debugging your solution and determining exactly when the event procedure is called. After everything is set up in step 5, the event should fire every time you manipulate the content. You use the static integer variable i so 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 in step 2. In this example, the text would be replaced with "WindowSelectionChange."

  4. Click Module on the Insert menu and add the following code in the standard code module:

    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 that you declared the App variable to be in step 2. By default, the class module inserted in step 2 is Class1, but you can change the name of the class module to anything you like.

  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, and then 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 "WindowSelection-Change" followed by a number. Each time an action occurs such that the selection changes in the active document window in Word, the number following the text "WindowSelectionChange" is changed by one.

    No matter what event you write code for, you should use this technique to help you debug and test your solutions. It also helps you determine exactly when an event is fired. Later in this chapter you'll learn more about each event that's fired as a result of a user's interaction with and manipulation of the active document's content. 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 fires.