27.2. WOrking with Item-Level Events

In addition to the application-level events discussed so far, Outlook also supports a wide variety of item-level events — events that fire when items are manipulated rather than the application as a whole being affected.

You can handle item-level events in Outlook in two ways:

• By declaring an event in a class module and running an initialization procedure, so that VBA then traps the event when it fires. This chapter takes this approach.

• By creating Visual Basic Script (VBScript) code and placing it in the form used by the item. This approach is especially useful for custom forms, but it is more limited than the previous approach, because some of the events that Outlook supports are not available in VBScript.

27.2.1. Declaring an Object Variable and Initializing an Event

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

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 run the code to initialize the object variable automatically. 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.

27.2.2. Understanding the Events That Apply to All Message Items

Many of the item-level events apply to all the message items: the AppointmentItem, ContactItem, DistListItem, DocumentItem, Explorer, Inspector, JournalItem, MailItem, MeetingItem, PostItem, RemoteItem, ReportItem, TaskItem, TaskRequestAcceptItem, TaskRequestDeclineItem, TaskRequestItem, and TaskRequestUpdateItem items. Table 27.1 lists these events.

The events that fire before an action occurs allow you to cancel the action so that it doesn't take place. 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 check that 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 from occurring.

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

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

Table 27.2 lists the events that apply to explorers, inspectors, or 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. 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

27.2.4. Understanding the Events That Apply to Folders

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

27.2.5. Understanding the Events That Apply to Items and Results

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

The following example uses the ItemChange event to monitor when any contact is changed in the Contacts folder. After a change, the event procedure displays a message box asking if the user wants to inform colleagues of the change to the contact. If the user clicks the Yes button, the example creates and sends a message containing the vCard for the contact. The message goes to the Marketing Associates distribution list and has the subject Contact details change: and the name of the contact.

Public WithEvents myContacts As Items

Public Sub Initialize_myContacts
    Set myContacts = Application.GetNamespace("MAPI") _
        .GetDefaultFolder(olFolderContacts).Items
End Sub

Private Sub myContacts_ItemChange(ByVal Item As Object)

    Dim ContactUpdateMessage As MailItem

    If MsgBox("Notify your colleagues of the contact change?", _
        vbYesNo +vbQuestion, "Contact Data Changed") = vbYes Then
        Set ContactUpdateMessage = Application.CreateItem(ItemType:=olMailItem)
        With ContactUpdateMessage
            .To = "Marketing Associates"
            .Subject = "Contact details change: " & Item.Subject
            .Body = "The following contact has changed: " & vbCr & vbCr _
                & Item.Subject

.Attachments.Add Source:=Item, Position:=50
            .Send
        End With
    End If

End Sub

27.2.6. Understanding the Events That Apply to the Outlook Bar

Outlook supports various events that apply to the Outlook bar (see Table 27.5). You may find these events useful if you need to customize the Outlook bar or constrain the user's navigation capabilities. For example, you can use the BeforeNavigate event to check the shortcut to which the user is attempting to navigate. If the user is not permitted to access the folder associated with the shortcut, you can cancel the navigation.

27.2.7. Understanding the Events That Apply to Reminders

Table 27.6 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.

27.2.8. 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.7 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, the 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