Understanding Office Primary Interop Assembly Events

Understanding Office Primary Interop Assembly Events

Programming with events in the Office Primary Interop Assemblies (PIAs) often involves creating an event handler for an event. Because the PIAs expose several interfaces for each event and for different versions of Microsoft Word, it can be a challenge to determine which event interface to use. In addition, the process for implementing an event handler differs slightly in Microsoft Visual Basic and C#.

To help you sort out these issues, this topic offers some guidelines for working with events in the Office PIAs.

classidClass Class Events

Avoid using events that appear in the Object Browser as members of the classidClass class, such as the ApplicationClass class. Using these classes has the potential to cause ambiguities with members that share the same name, such as the Microsoft.Office.Interop.Word._Application.Quit(System.Object,System.Object,System.Object) method and Microsoft.Office.Interop.Word.ApplicationEvents4_Event.Quit event.

Instead, use events that are members of the classidEventsx_Event interfaces, such as the AppEvents_Events interface in Microsoft Excel or the ApplicationEvents4_Event interface in Microsoft Word.

For more information, see Understanding Office Primary Interop Assembly Classes and Interfaces.

Version-Specific Event Interfaces in Microsoft Word

If you are working with application-level events in Microsoft Word, use the event interface that corresponds to the version of Word that you want to target. The following table shows the event interfaces and their corresponding Word versions.

Event Interface	Word Version
ApplicationEvents_Event	Word 97
ApplicationEvents2_Event	Word 2000
ApplicationEvents3_Event	Word 2002
ApplicationEvents4_Event	Word 2003

If you are targeting only one version of Word, use the event interface that matches that version. However, if you intend your code to support multiple versions, use the earliest interface that exposes the event you want. For example, to write code that uses the Quit event, and that will run in Word 2000 and subsequent versions, use the ApplicationEvents2_Event interface.

Event Handler Differences in Visual Basic and C#

The Visual Basic and C# programming languages have different mechanisms for creating event handlers. In either language, start by declaring variables that use the appropriate application and event interfaces, and then associate an event with your handler. In Visual Basic, use the AddHandler statement to associate an event with an event handler. In C#, use the corresponding event handler delegate.

The following Visual Basic and C# examples associate the Quit event in Microsoft Word 2000 and subsequent versions with an event handler named handlerQuit. The handler displays a message when Microsoft Word closes. The examples assume that you have added a reference to the Microsoft Word PIA and created a form with two command buttons, btnRunWord and btnQuitWord.

' Visual Basic example.
Private wd As Microsoft.Office.Interop.Word.Application
Public wdEvents As _
  Microsoft.Office.Interop.Word.ApplicationEvents2_Event

Private Sub btnRunWord_Click(ByVal sender As System.Object, _
  ByVal e As System.EventArgs) Handles btnRunWord.Click

    ' Start Word in a small window next to the application form.
    wd = New Microsoft.Office.Interop.Word.Application
    wd.Visible = True
    wd.WindowState=_
      Microsoft.Office.Interop.Word.WdWindowState.wdWindowStateNormal
    wd.Left = Me.Left + 200
    wd.Top = 200
    wd.Height = 300
    wd.Width = 300

    ' Create a Quit event handler.
    wdEvents = CType(wd, Word.ApplicationEvents2_Event)
    AddHandler wdEvents.Quit, AddressOf Me.handlerQuit

End Sub

Private Sub btnQuitWord_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles btnQuitWord.Click

    ' Quit Word when the btnQuit button is clicked.
    wd.Quit()

End Sub

Private Sub handlerQuit()

    ' Display a message when Word quits.
    MessageBox.Show("Good-bye Word!")
    wd = Nothing
    GC.Collect()
    GC.WaitForPendingFinalizers()

End Sub

// C# example.
private Microsoft.Office.Interop.Word.Application wd;
private Microsoft.Office.Interop.Word.ApplicationEvents2_Event wdEvents;

private void btnRunWord_Click(object sender, System.EventArgs e)
{
    // Start Word in a small window next to the application form.
    wd = new Microsoft.Office.Interop.Word.Application();
    wd.Visible = true;
    wd.WindowState=Microsoft.Office.Interop.Word.WdWindowState.
      wdWindowStateNormal;
    wd.Left = This.Left + 200;
    wd.Top = 200;
    wd.Height = 300;
    wd.Width = 300;

    // Create a Quit event handler.
    wdEvents = 
      (Microsoft.Office.Interop.Word.ApplicationEvents2_Event)wd;
    wdEvents.Quit +=
      new Microsoft.Office.Interop.Word.
      ApplicationEvents2_QuitEventHandler(handlerQuit);
}

private void btnQuitWord_Click(object sender, System.EventArgs e)
{
    // Quit Word when the btnQuit button is clicked.
    object missing = System.Type.Missing;
    wd.Quit(ref missing, ref missing, ref missing);
}

private void handlerQuit()
{
    // Display a message when Word quits.
    MessageBox.Show("Good-bye Word!");
    wd = null;
    GC.Collect();
    GC.WaitForPendingFinalizers();
}

See Also

Concepts

Overview of Classes and Interfaces in the Office Primary Interop Assemblies
Office Primary Interop Assembly Reference Documentation Conventions
Office Primary Interop Assembly Code Examples