Writing application event procedures

Note that the “big picture” view of what we're about to do is this:

We want to respond to events.

We need an application variable (declared with WithEvents) to receive the events.

We need a class module to serve as a container for the application variable. 

1.

Create an Addin; that is, a .dot file stored in Word's startup directory so that it is global.

2.

Open the Addin, and in the VB Editor, select Insert + Class Module.

Rename the Class Module from Class1 to ThisApplication.

Note: The Class Module and all the variables in this article can be called whatever you like; but I have tried to make all the names as meaningful as possible.

I like “ThisApplication” because it shows that it is functionally analogous to the built-in “ThisDocument” class module.  But note that your “ThisApplication” object is simply a container. It doesn't actually represent an application. It represents all the properties of the Class Object, whatever we define those properties to be.

3.

Insert the following code in the Class Module:

Option Explicit

Public WithEvents oApp As Word.Application

This specifies that oApp is an object variable which will be used to respond to the events triggered by the ActiveX object Word.Application.

By declaring it publicly, you have made oApp a property of the class object ThisApplication. 

At this point you are simply declaring what type of object oApp is (its type being a Word Application object), and declaring the fact it will respond to events. You are not actually assigning the oApp variable to the Word application yet – that comes later. So the oApp object doesn't actually exist yet (and no area of memory has been set aside for it yet).

The WithEvents keyword can only be used in Class Modules and can only refer to ActiveX –  i.e. OLE-compliant – objects.

4.

Now select Insert + Module.

In the Module, insert the following code:

Option Explicit

Dim oAppClass As New ThisApplication

Where “ThisApplication” is the name of your Class Module. The statement creates an object variable oAppClass which references (is a pointer to) the class object ThisApplication which you created earlier.

Using the keyword “New” in the declaration creates a new instance of the class object – that is, it loads an instance of the class into memory and makes the variable oAppClass point to the newly created instance.

From now on, you can refer to this new instance of the class by using the oAppClass variable.

Now add the following code in the same Module:

Public Sub AutoExec()
    Set oAppClass.oApp = Word.Application
End Sub

The oApp object is a property of the class object oAppClass, because you declared it as a public variable in the Class Module in step 3.

The above code creates an instance of the oApp object (loads it into memory), and makes it actually refer to the Word.Application object. In effect it makes the oApp object exist. 

To put it another way, you have now assigned the actual Active-X Word Application to the variable, whereas previously you had only declared what type of variable it was going to be.

By calling your procedure AutoExec, you make it run automatically when your Addin loads – and your Addin will automatically load when Word loads.

5.

Now run the AutoExec macro, by clicking in it and pressing F5, to initialise the oApp object.

6.

Switch to your ThisApplication Class Module. You'll see two list boxes on the toolbar. If you pull down the one on the left, and change it from “(General)” to “oApp”, a procedure called oApp_Quit() will be created. If you then pull down the list box on the right, you'll see several other application events to choose from (and you can delete the oApp_Quit() procedure later, if you don't want it):

Note that (rather confusingly) these are all Application events (even though some of them refer to documents doing things) as distinct from Document events such as Document_Close. Because it is an Application event, for instance, a procedure called oApp_DocumentBeforeClose will fire when any document closes; whereas because it is a Document event, a Document_Close procedure will only fire when documents based on the template that the Document_Close procedure is stored in are closed.

7.

Having inserted the event procedure you want using the listboxes, add your code, and you're done.