| 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 10.1 shows representative Explorer and Inspector windows. Figure 10.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. Listing 10.1. 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. Listing 10.2. 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: 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. Listing 10.3. 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. Listing 10.4. 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 |
|