Using the Startup Event

The Startup event, which takes no arguments, occurs when Outlook starts. In other words, every time the user starts Outlook, any code you might have written in the Sub Application_Startup() procedure will automatically execute.

The Startup event is useful for making sure that Outlook is correctly configured for the user to start work. Say that someone always starts off by writing notes, and the first note is always a reminder about time cards. The following example creates a new NoteItem object (a note), assigns text to its Body property, and uses the Display item to display it (see Figure 27.2):

Private Sub Application_Startup()
    Dim myNoteItem As NoteItem
    Set myNoteItem = Application.CreateItem(ItemType:=olNoteItem)
    myNoteItem.Body = "Please start a new time card for the day."
    myNoteItem.Display
End Sub

You can also put the Startup event to good use by writing code with the Set command to connect an object variable to a real object it is supposed to represent. More on this later in this chapter, in the section titled “Declaring an Object Variable and Initializing an Event.”

Using the Quit Event

The Quit event occurs when Outlook is shut down. This event is triggered three possible ways:

• By the user choosing Exit in the File tab of the Ribbon
• By the user clicking the red X icon in the upper right of the Outlook window
• By the programmer using the Quit method of the Application object in VBA

By the time that the Quit event fires (is triggered), all of Outlook's windows have already been closed and all global variables have been released, so there's little left for a programmer to access via code in this event procedure. One possibility, however, is to display a parting message to the user, as in the following example, which displays a message on the workday that precedes a national holiday to remind the user of the holiday:

Private Sub Application_Quit()
 
    Dim strMessage As String
    Select Case Format(Date, "MM/DD/YYYY")
        Case "01/18/2019"
            strMessage = "Next Monday is Martin Luther King Day."
        Case "02/15/2019"
            strMessage = "Next Monday is President's Day."
        Case "05/23/2019"
            strMessage = "Next Monday is Memorial Day."
        Case "07/03/2019"
            strMessage = "Friday is Independence Day." & _
                " Monday is a company holiday."
        Case "08/29/2019"
            strMessage = "Next Monday is Labor Day."
        'other National Holidays here
    End Select
 
Msgbox "No holidays this week."
If strMessage = "" Then Exit Sub
 
MsgBox strMessage, vbOKCancel + vbExclamation, “Don't Forget…”
 
End Sub

Note that to test this macro, you need to quit Outlook. What's more, this macro can be tested only on the dates listed or by suppressing the Exit Sub code line (commenting it out) like this:

'If strMessage = "" Then Exit Sub

Using the ItemSend Event

The ItemSend event occurs when an item is sent, either by the user issuing a Send command (for example, by clicking the Send button in a Message window) or by executing the Send method in VBA code. The syntax for the ItemSend event is as follows:

Sub expression_ItemSend(ByVal Item As Object, Cancel As Boolean)

Here, expression is a required expression that returns an Application object. Item is a required argument that specifies the item that's being sent. Cancel is an optional Boolean argument that you can set to False to prevent the item from being sent.

The following example examines the Subject property of the Item object being sent. If the Subject property is an empty string, the message box prompts the user to add a subject line, and the Cancel = True statement cancels the sending of the item:

Private Sub Application_ItemSend(ByVal Item As Object, Cancel As Boolean)
    If Item.Subject = "" Then
        MsgBox "Please add a subject line to this message before sending it."
        Cancel = True
    End If
End Sub

Remember to test event procedure macros like these; you can't just press F5 (the way you test ordinary macros). You must instead do something in Outlook to fire the event. In this example, you must attempt to send an email message without its Subject field filled in.

Using the NewMail Event

The NewMail event occurs when one or more new mail items arrives in the Inbox. The NewMail event can be useful for sorting messages automatically. You can also specify custom rules to sort messages automatically. The NewMail event takes no arguments.

The following example displays a message box that offers to show the Inbox when new mail arrives, triggering the NewMail event:

Private Sub Application_NewMail()
    If MsgBox("You have new mail. Do you want to see your Inbox?", _
        vbYesNo + vbInformation, "New Mail Alert") = vbYes Then
 
Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Display
    End If
End Sub

Using the AdvancedSearchComplete and the AdvancedSearchStopped Events

Outlook provides two events for working with advanced searches created using the AdvancedSearch method. The AdvancedSearchComplete event fires when the AdvancedSearch method is run via VBA (in macro code, not by the user) and finishes searching. The AdvancedSearchStopped event fires when the AdvancedSearch method is run via VBA, and is stopped by using the Stop method of the search.

The syntax for the AdvancedSearchComplete event is as follows:

Private Sub expression_ AdvancedSearchComplete(ByVal SearchObject As Object)

Here, expression is a required expression that returns an Application-type object variable that has been declared with events in a class module. SearchObject is the Search object that the AdvancedSearch method returns.

The following example uses the AdvancedSearchComplete event to return the number of search results that were found by the AdvancedSearch method:

Private Sub Application_AdvancedSearchComplete(ByVal SearchObject As Search)
    MsgBox "The search has finished running and found " & _
        SearchObject.Results.Count & " results.", vbOKOnly + vbInformation, _
        "Advanced Search Complete Event"
End Sub

The following example uses the AdvancedSearchStopped event to inform the user that the search has been stopped:

Private Sub Application_AdvancedSearchStopped(ByVal SearchObject As Search)
    MsgBox "The search was stopped by a Stop command.", vbOKOnly
End Sub

Using the MAPILogonComplete Event

The MAPILogonComplete event occurs when the user has successfully logged on to Outlook. You can use the MAPILogonComplete event to ensure that Outlook is configured correctly for the user or simply to display some information in a message. The MAPILogonComplete event takes no arguments.

The following example of a MAPILogonComplete procedure displays a message about current trading conditions when the user has successfully logged on to Outlook. The code includes a commented line indicating where the String variables strPubDownBegin and strPubForecast would be declared and assigned data in a real-world implementation of this example:

Private Sub Application_MAPILogonComplete()
 
    Dim strMsg As String
 
    'strPubDowBegin and strPubForecast declared and assigned strings here
 
    strMsg = "Welcome to the UltraBroker Trading System!" & vbCr & vbCr
    strMsg = strMsg & "Today's starting value is " & strPubDowBegin & "." _
        & vbCr & vbCr
    strMsg = strMsg & "Today's trading forecast is " & strPubForecast & "."
    MsgBox strMsg, vbOKOnly + vbInformation, _
        "UltraBroker Trading System Logon Greeting"
End Sub

This macro displays a message box, but it's underneath the blue Outlook startup splash graphic. To see it, drag the splash out of the way. Unfortunately, there's no simple way to force a message box to display anywhere other than directly in the middle of the screen.

Using the Reminder Event

The Reminder event fires immediately before a reminder for a meeting, task, or appointment is displayed to the user. You can use the Reminder event to take an action related to the reminder. Because the reminder itself is usually by itself adequate for reminding the user, the Reminder event tends to be more useful when accessing Outlook programmatically than when a user is working interactively with Outlook. The syntax is as follows:

Sub expression_Reminder(ByVal Item As Object)

Here, expression is a required expression that returns an Application object, and Item is the AppointmentItem, MailItem, ContactItem, or TaskItem object associated with the reminder.

Using the OptionsPagesAdd Event

The OptionsPagesAdd event occurs when either the Options dialog box (Tools ➢ Options) or the Properties dialog box for a folder, such as the Inbox, is opened. (To open the Properties dialog box for a folder, right-click the folder and then choose Properties from the context menu.) You can use this event to add a custom page (which is contained in a COM [Component Object Model] add-in that you have created) to the Options dialog box or the Properties dialog box. The syntax for the OptionsPagesAdd event is as follows:

Sub expression_OptionsPagesAdd(ByVal Pages As PropertyPages, _
    ByVal Folder As MAPIFolder)

Here, expression is a required expression that returns an Application object or a NameSpace object. Pages is a required argument that gives the collection of custom property pages added to the dialog box. Folder is a required argument used when expression returns a MAPIFolder object. Folder returns the MAPIFolder object for which the Properties dialog box is being opened.

Declaring an Object Variable and Initializing an Event

Follow these steps to declare an object variable and initialize an event:

1. Use a class module to contain your object-variable declaration, in one of the following three ways:
   • Use the built-in ThisOutlookSession module. In the Project Explorer, expand the project name (it's in boldface and by default is named Project1). Expand the Microsoft Outlook Objects item, and double-click the ThisOutlookSession item to open its Code window.
   • Create a new class module by right-clicking the project name in the Project Explorer and choosing Insert ➢ Class Module from the context menu. The VBA Editor automatically opens a Code window for the class.
   • If a class module already exists, double-click it in the Project Explorer.
2. In the declarations area at the beginning of your class module (at the top of the Code window), declare a variable to represent the object to which the event applies. Use the WithEvents keyword to specify that this object has events.

   The following example creates a public variable named myPublicContactItem:

   Public WithEvents myPublicContactItem As ContactItem

3. Initialize the object variable by setting it to represent the appropriate object. The following example sets our myPublicContactItem variable to represent the first item in the default contacts folder:

   Set myPublicContactItem = Application.GetNamespace("MAPI") _
       .GetDefaultFolder(olFolderContacts).Items(1)

Once you've initialized the object variable, the procedure will run after the event fires.

You can initialize the object variable manually if necessary, and you may find it convenient to do so when you're writing and testing code to handle events. But if you need to handle the event each time Outlook runs—if you want to make the macro a permanent part of your macro collection—it's obviously best to automatically execute the code to initialize the object variable. For example, you might use the Startup event of the Application object (discussed in “Using the Startup Event,” earlier in this chapter) to run event-handling initialization code automatically each time Outlook starts. In other words,

Private Sub Application_Startup()
 
Set objMyPublicContactItem = Application.GetNamespace("MAPI") _
    .GetDefaultFolder(olFolderContacts).Items(1)
 
End Sub

Understanding the Events That Apply to All Message Items

Table 27.1 lists the common message events. I'm using the term message here to refer to the AppointmentItem, MailItem, ContactItem, and TaskItem objects. In other words, Table 27.1 lists the most common events that are available to these four objects.

But be aware that there are additional “item” objects in Outlook, such as the DocumentItem, DistListItem, JournalItem, MeetingItem, and so on. To view these various items, and see descriptions of their events, visit this web page:

https://msdn.microsoft.com/en-us/library/office/ff866465.aspx

Also note that although Table 27.1 describes 16 common events, each of the “item” objects actually has 26 events. As an example, the complete list of events for the MailItem object in Outlook is provided on this web page:

https://msdn.microsoft.com/EN-US/library/office/dn320337.aspx

Note that the Close event applies to the Inspector object and the Explorer object as well as to the objects just mentioned.

The events that fire before an action occurs allow you to cancel the action, preventing it from happening at all. The syntax for these events uses a Boolean argument named Cancel that you can set to True to prevent the action from taking place. For example, the syntax for the BeforeDelete event is as follows:

Sub expression_BeforeDelete(ByVal Item As Object, Cancel As Boolean)

Here, expression is a required expression that returns one of the message items to which the event applies (for example, a TaskItem object). The following example uses the BeforeDelete event to see if the TaskItem object that's open in an inspector is marked as complete when the user tries to delete it. If the task is not marked as complete, a message box prompts the user to complete the task, and the example then sets the Cancel argument to True to prevent the deletion:

Private Sub myTaskItem_BeforeDelete(ByVal Item As Object, Cancel As Boolean)
    If myTaskItem.Complete = False Then
        MsgBox "Please complete the task before deleting it.", _
            vbOKOnly + vbExclamation, "Task Is Incomplete"
        Cancel = True
    End If
End Sub

Understanding the Events That Apply to Explorers, Inspectors, and Views

Table 27.2 lists the events that apply to explorers, inspectors, and views. Some events apply to both explorers and inspectors.

If you work on a small screen (for example, a laptop screen), you might prefer to use the NewInspector event to maximize each Inspector window you open and to hide any toolbars you don't need. The first procedure in the following example (which includes the necessary declarations) uses the NewInspector event to make sure the Standard toolbar is displayed, hide the Advanced toolbar, and assign the Inspector object representing the new inspector to the Public object variable myInspector. The second procedure uses the Activate event of the myInspector object to maximize its window by setting the WindowState property to olMaximized.

The net effect of these two event procedures is to configure the toolbars as described earlier and maximize the Inspector window. Put more simply, if you, for example, double-click an email, it opens in a new window. That window is the “inspector” object. The Activate event procedure is necessary because the NewInspector event runs before the Inspector window is displayed, which means the NewInspector event procedure cannot maximize the Inspector window.

Public WithEvents myInspectors As Inspectors
Public WithEvents myInspector As Inspector
 
Private Sub myInspectors_NewInspector(ByVal Inspector As Outlook.Inspector)
    With Inspector
        With .CommandBars
            .Item("Standard").Visible = True
            .Item("Advanced").Visible = False
        End With
        Set myInspector = Inspector
    End With
End Sub
 
Private Sub myInspector_Activate()
    myInspector.WindowState = olMaximized
End Sub

Events That Apply to Folders

Outlook provides three events (see Table 27.3) that apply to folders.

Understanding the Events That Apply to Items and Results Objects

Table 27.4 lists the events that apply to items and results.

The example in the sidebar “How to Test Event-Handler Procedures” earlier in this chapter employs the ItemChange event to monitor when any contact is changed in the Contacts folder.

Understanding the Events That Apply to Reminders

Table 27.5 explains the events that Outlook provides for reminders. You can use these events to take actions when a reminder fires, before the reminder dialog box appears, when the user clicks the Snooze button to dismiss a reminder, or when reminders are added, changed, or removed.

Understanding the Events That Apply to Synchronization

If you write procedures to synchronize Outlook, you may need to use the three events that apply to the SyncObject object, which represents a Send/Receive group for a user. (You can access the SyncObject object by using the SyncObjects property of the NameSpace object to return the SyncObjects collection.) Table 27.6 explains the events that apply to the SyncObject object.

The following example uses the OnError event with the object variable mySyncObject. If an error occurs during synchronization of the SyncObject represented by mySyncObject, this procedure displays an error message giving the error code and description:

Private Sub mySyncObject_OnError(ByVal Code As Long, _
    ByVal Description As String)
 
    Dim strMessage As String
    strMessage = "An error occurred during synchronization:" & vbCr & vbCr
    strMessage = strMessage & "Error code: " & Code & vbCr
    strMessage = strMessage & "Error description: " & Description
    MsgBox strMessage, vbOKOnly + vbExclamation, "Synchronization Error"
 
End Sub