ApplicationLevel Events





ApplicationLevel Events

This section covers events that occur at the Application level. This includes both events raised on the Application object and events that are raised on the main Outlook windows. The two primary windows displayed by Outlook are represented in the Outlook object model by the Explorer object and the Inspector object. An Explorer object represents the main Outlook window in which the contents of folders display. An Inspector object represents the Outlook window that appears when you doubleclick an Outlook itemfor example, when you doubleclick a mail item in your inbox. Figure.1 shows representative Explorer and Inspector windows.

1. An Explorer window and an Inspector window.


It is possible to have zero or more Explorer and zero or more Inspector windows open at any time. If you rightclick a document in the My Documents folder and choose Mail Recipient from the Send To menu, for example, Outlook launches with only an Inspector window open. If you launch Outlook by picking it from the Start menu, it typically starts with just the main Outlook window open, which is an Explorer window. If you rightclick a folder within Outlook and choose Open in New Window, doing so creates an additional Explorer window to display that folder. Outlook can also run in a mode with neither an Explorer nor an Inspector window runningfor example, when it is started by the ActiveSync application shipped by Microsoft for syncing phones and PDAs to Outlook.

Startup and Quit Events

Outlook raises several events during startup and shutdown:

  • Application.Startup is raised when Outlook has completely started. This event is raised after add-ins have been loaded so that an add-in can handle this eventthat is, it is not raised before add-ins are loaded (as are some events in Word and Excel).

  • Application.MAPILogonComplete is raised after Outlook has logged on to the mail services to which it is configured to connect.

  • Application.Quit is raised when Outlook is about to exit. This event is raised before add-ins have been unloaded so that an add-in can handle this event. A VSTO Outlook add-in is unloaded before the Quit event is raised and should use the Shutdown event instead.

Note

Quit is the name of both a method and an event on the Application object. Because of this collision, you will have to use the CType operator to cast the Application object to the ApplicationEvents_11_Event interface when adding an event handler dynamically using the AddHandler statement. If you are adding an event handler declaratively using WithEvents and Handles, you do not have to worry about this issue.


The order in which IDTExtensibility2 methods associated with a COM add-in (described in Chapter 23, "Developing COM AddIns for Word and Excel") and Outlook's Startup, Quit, and MAPILogonComplete events occur is shown here:

  • User launches Outlook.

    - OnConnection method of IDTExtensibility2 is called.

    - OnStartupComplete method of IDTExtensibility2 is called.

    - Startup event is raised.

    - MAPILogonComplete event is raised.

  • User quits Outlook.

    - Quit event is raised.

    - OnBeginShutdown of IDTExtensibility2 is called.

    - OnDisconnection of IDTExtensibility2 is called.

Listing 10.1 shows an add-in that handles these three events dynamically using AddHandler. In most of the other examples in this book, we handle events declaratively using WithEvents and Handles. Listing 10.1 also displays message boxes when the methods of IDTExtensibility2 are called.

Note

For simplicity, the COM add-in listings in this chapter do not include the fix described in Chapter 24, "Creating Outlook AddIns with VSTO," that is required to get Outlook always to shut down reliably when loading a COM add-in.

Even though this book includes some COM add-in samples, our recommendation is that you create VSTO Outlook add-ins rather than COM add-ins to avoid the issues described in Chapter 24.


A COM AddIn That Handles the Application Object's Quit, Startup, and MAPILogonComplete Events

Imports Extensibility
Imports Outlook = Microsoft.Office.Interop.Outlook
Imports System.Windows.Forms
Imports System.Runtime.InteropServices

<GuidAttribute("9D71C9DB-BB7A-45D4-9AE2-13E58D05FD1B"),_
ProgIdAttribute("MyAddin2.Connect")>_
Public Class Connect
  Implements Extensibility.IDTExtensibility2

  Dim applicationObject As Outlook.Application
  Dim addInInstance As Object

  Public Sub OnConnection(ByVal application As Object, _
    ByVal connectMode As Extensibility.ext_ConnectMode, _
    ByVal addInInst As Object, _

    ByRef custom As System.Array) _
    Implements Extensibility.IDTExtensibility2.OnConnection

    applicationObject = CType(application, Outlook.Application)
    addInInstance = addInInst

    AddHandler applicationObject.Startup, _
      AddressOf ApplicationObject_Startup
    AddHandler applicationObject.Quit, _
      AddressOf ApplicationObject_Quit
    AddHandler applicationObject.MAPILogonComplete, _
      AddressOf ApplicationObject_MAPILogonComplete

    MsgBox("OnConnection")

  End Sub

  Public Sub OnDisconnection( _
    ByVal RemoveMode As Extensibility.ext_DisconnectMode, _
    ByRef custom As System.Array) _
    Implements Extensibility.IDTExtensibility2.OnDisconnection

    MsgBox("OnDisconnection")

  End Sub

  Public Sub OnAddInsUpdate(ByRef custom As System.Array) _
    Implements Extensibility.IDTExtensibility2.OnAddInsUpdate
  End Sub

  Public Sub OnStartupComplete(ByRef custom As System.Array) _
    Implements Extensibility.IDTExtensibility2.OnStartupComplete

    MsgBox("OnStartupComplete")

  End Sub

  Public Sub OnBeginShutdown(ByRef custom As System.Array) _
    Implements Extensibility.IDTExtensibility2.OnBeginShutdown

    MsgBox("OnBeginShutdown")

  End Sub

  Public Sub ApplicationObject_Startup()
    MsgBox("Startup Event")
  End Sub

  Public Sub ApplicationObject_MAPILogonComplete()
    MsgBox("MAPILogonComplete Event")
  End Sub

  Public Sub ApplicationObject_Quit()
    MsgBox("Quit Event")
  End Sub

End Class

The order in which a VSTO Outlook add-in's Startup and Shutdown event handlers and Outlook's Startup, Quit, and MAPILogonComplete events occur is shown here:

  • User launches Outlook.

    - VSTO Startup event is raised.

    - Outlook Application object's Startup event is raised.

    - Outlook Application object's MAPILogonComplete event is raised.

  • User quits Outlook.

    - Outlook Application object's Quit event is raised. The VSTO add-in system uses this event to control how the add-in unloads, so you may not see this event. Your code should handle the Shutdown event instead.

    - VSTO Shutdown event is raised.

Activation Events

When an Explorer or Inspector window becomes the active window (activates) or loses focus to another window (deactivates), events are raised:

  • Explorer.Activate is raised on an Explorer object when the window it corresponds to becomes the active window.

  • Inspector.Activate is raised on an Inspector object when the window it corresponds to becomes the active window.

    Note

    Activate is the name of both a method and an event on the Explorer and Inspector object. Because of this collision, you will have to use the CType operator to cast the Explorer object to the ExplorerEvents_10_Event interface and the Inspector object to the InspectorEvents_10_Event when adding an event handler dynamically using the AddHandler statement. If you are adding an event handler declaratively using WithEvents and Handles, you do not have to worry about this issue.


  • Explorer.Deactivate is raised on an Explorer object when the window it corresponds to loses focus to another window.

  • Inspector.Deactivate is raised on an Inspector object when the window it corresponds to loses focus to another window.

Listing 10.2 shows a VSTO Outlook add-in that handles Activate and Deactivate events for the Explorer object. In this listing, the events are handled declaratively using WithEvents and Handles.

Note

For simplicity, future VSTO Outlook add-in listings in this chapter omit the Imports lines of code at the beginning of the VSTO This Application class and the Shutdown event handler.


A VSTO AddIn That Handles the Explorer Object's Activate and Deactivate Events

Imports Outlook = Microsoft.Office.Interop.Outlook

Public Class ThisApplication

  Private WithEvents explorer As Outlook.Explorer

  Private Sub ThisApplication_Startup(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Startup

    explorer = Me.ActiveExplorer

  End Sub

  Private Sub Explorer_Activate() Handles explorer.Activate
    Debug.Print(String.Format( _
      "The explorer with caption {0} was activated.", _
      explorer.Caption))
  End Sub

  Private Sub Explorer_Deactivate() Handles explorer.Deactivate
    Debug.Print(String.Format( _
      "The explorer with caption {0} was deactivated.", _
      explorer.Caption))
  End Sub

End Class

New Window Events

When a new Explorer or Inspector window is created, Outlook raises an event:

  • Explorers.NewExplorer is raised when a new Explorer window is created. The newly created Explorer is passed as a parameter to this event.

  • Inspectors.NewInspector is raised when a new Inspector window is created. The newly created Inspector is passed as a parameter to this event.

Listing 24.1 in Chapter 24, "Creating Outlook AddIns with VSTO," shows an example of handling these events.

Window Events

When an Explorer or Inspector window is maximized, minimized, moved, or resized, events are raised by Outlook. All these events can be canceled to prevent the change to the window from occurring:

  • Explorer.BeforeMaximize is raised on an Explorer object when the window it corresponds to is about to be maximized. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to true by your event handler to prevent Outlook from maximizing the window.

  • Inspector.BeforeMaximize is raised on an Inspector object when the window it corresponds to is about to be maximized. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to true by your event handler to prevent Outlook from maximizing the window.

  • Explorer.BeforeMinimize is raised on an Explorer object when the window it corresponds to is about to be minimized. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to true by your event handler to prevent Outlook from minimizing the window.

  • Inspector.BeforeMinimize is raised on an Inspector object when the window it corresponds to is about to be minimized. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to TRue by your event handler to prevent Outlook from minimizing the window.

  • Explorer.BeforeMove is raised on an Explorer object when the window it corresponds to is about to be moved. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to TRue by your event handler to prevent Outlook from moving the window.

  • Inspector.BeforeMove is raised on an Inspector object when the window it corresponds to is about to be moved. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to true by your event handler to prevent Outlook from moving the window.

  • Explorer.BeforeSize is raised on an Explorer object when the window it corresponds to is about to be resized. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to TRue by your event handler to prevent Outlook from resizing the window.

  • Inspector.BeforeSize is raised on an Inspector object when the window it corresponds to is about to be resized. Outlook passes by reference a Boolean cancel parameter. The cancel parameter can be set to TRue by your event handler to prevent Outlook from resizing the window.

Close Events

When an Explorer or Inspector window is closed, Outlook raises an event:

  • Explorer.Close is raised on an Explorer object when the window it corresponds to has been closed.

  • Inspector.Close is raised on an Inspector object when the window it corresponds to has been closed.

Note

Close is the name of both a method and an event on the Explorer and Inspector object. Because of this collision, you will have to use the CType operator to cast the Explorer object to the ExplorerEvents_10_Event interface and the Inspector object to the InspectorEvents_10_Event when adding an event handler dynamically using the AddHandler statement. If you are adding an event handler declaratively using WithEvents and Handles, you do not have to worry about this issue.


Listing 24.1 in Chapter 24, "Creating Outlook AddIns with VSTO," shows an example of handling these events.

View and Selection Change Events

As you navigate from folder to folder in an Explorer window, Outlook displays a view of the items in the folder you have selected. The user can also change the view for a particular folder by using the View menu and choosing a different view from the Current View submenu of the Arrange By menu. Outlook raises events when the view changes or the selection changes:

  • Explorer.BeforeViewSwitch is raised on an Explorer object when the user changes the view for a particular folder by using the View menu. This event is not raised when the user simply switches from folder to folder, thereby changing the view (but the ViewSwitch event is raised). Outlook passes a newView parameter that is of type Object. This parameter can be cast to a String value representing the name of the view about to be switched to. Outlook also passes by reference a Boolean cancel parameter. The cancel parameter can be set to true by your event handler to prevent Outlook from switching to the view the user selected.

  • Explorer.ViewSwitch is raised on an Explorer object when the view changes either because the user changed the view using the View menu or because the user selected another folder.

  • Inspector.SelectionChange is raised on an Explorer object when the selection in the Explorer window changes.

  • Explorer.BeforeFolderSwitch is raised on an Explorer object before the active folder changes. Outlook passes a newFolder parameter of type Object. This parameter can be cast to a MAPIFolder that represents what the new active folder will be. Outlook also passes by reference a Boolean cancel parameter. The cancel parameter can be set to true by your event handler to prevent Outlook from switching to the folder the user selected.

  • Explorer.FolderSwitch is raised on an Explorer object when the active folder changes.

Listing 10.3 shows a VSTO Outlook add-in that handles these events.

A VSTO AddIn That Handles View and Selection Change Events

Public Class ThisApplication

  Private WithEvents explorer As Outlook.Explorer

  Private Sub ThisApplication_Startup(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Startup

    explorer = Me.ActiveExplorer

  End Sub

  Private Sub Explorer_BeforeViewSwitch( _
    ByVal NewView As Object, _
    ByRef cancel As Boolean) Handles explorer.BeforeViewSwitch

    MsgBox(String.Format("About to switch to {0}.", NewView))

  End Sub

  Private Sub Explorer_ViewSwitch() Handles explorer.ViewSwitch
    Dim view As Outlook.View = explorer.CurrentView
    If view IsNot Nothing Then
      MsgBox(String.Format( _
        "The view switched. Current view is now {0}.", _
        view.Name))
    End If
  End Sub

  Private Sub Explorer_SelectionChange() _
    Handles explorer.SelectionChange

    MsgBox(String.Format( _
      "Selection changed. {0} items selected.", _
      explorer.Selection.Count))

  End Sub

  Private Sub Explorer_BeforeFolderSwitch( _
    ByVal NewFolder As Object, _
    ByRef cancel As Boolean) Handles explorer.BeforeFolderSwitch

    Dim folder As Outlook.MAPIFolder = _
      CType(NewFolder, Outlook.MAPIFolder)

    MsgBox(String.Format("The new folder will be {0}.", _
      folder.Name))

  End Sub

  Private Sub Explorer_FolderSwitch() _
    Handles explorer.FolderSwitch
    MsgBox("Folder switch")
  End Sub

End Class

Folder Change Events

Given a collection of folders in Outlook, several events are raised when folders in that collection change:

  • Folders.FolderAdd is raised on a Folders collection when a new folder is added. Outlook passes a folder parameter of type MAPIFolder representing the newly added folder.

  • Folders.FolderRemove is raised on a Folders collection when a folder is deleted.

  • Folders.FolderChange is raised on a Folders collection when a folder is changed. Examples of changes include when the folder is renamed or when the number of items in the folder changes. Outlook passes a folder parameter of type MAPIFolder representing the folder that has changed.

Listing 10.4 shows an add-in that handles folder change events for any subfolders under the Inbox folder. To get to a Folders collection, we first get a NameSpace object. The NameSpace object is accessed by calling the Application.Session property. The NameSpace object has a method called GetDefaultFolder that returns a MAPIFolder object to which you can pass a member of the enumeration OlDefaultFolders to get a standard Outlook folder. In Listing 10.4, we pass olFolderInbox to get a MAPIFolder for the Inbox. Then we connect our event handlers to the Folders collection associated with the Inbox's MAPIFolder object.

A VSTO AddIn That Handles Folder Change Events

Public Class ThisApplication

  Private WithEvents folders As Outlook.Folders

  Private Sub ThisApplication_Startup(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Startup

    Dim ns As Outlook.NameSpace = Me.Session
    Dim folder As Outlook.MAPIFolder = _
      ns.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderInbox)
    folders = folder.Folders

  End Sub

  Private Sub Folders_FolderAdd( _
    ByVal folder As Outlook.MAPIFolder) _
    Handles folders.FolderAdd

    MsgBox(String.Format("Added {0} folder.", folder.Name))

  End Sub

  Private Sub Folders_FolderChange( _
    ByVal folder As Outlook.MAPIFolder) _
    Handles folders.FolderChange

    MsgBox(String.Format("Changed {0} folder. ", folder.Name))

  End Sub

  Private Sub Folders_FolderRemove() _
    Handles folders.FolderRemove
    MsgBox("Removed a folder.")
  End Sub

End Class



 Python   SQL   Java   php   Perl 
 game development   web development   internet   *nix   graphics   hardware 
 telecommunications   C++ 
 Flash   Active Directory   Windows