Inspectors Collection Events

The Inspectors collection object provides the gateway to item-level events in Outlook 2000 and Outlook 2002. Although this collection object has only one event that occurs when a new Inspector is displayed through either a user action or program code, the NewInspector event lets you instantiate item-level objects declared using the WithEvents keyword. In Outlook 97 and Outlook 98, the only supported events were form-level events for customized Item objects, also known as custom forms. Any form-level item for which you write VBScript code is, by definition, a custom Outlook form. VBScript code in those forms could respond to events such as Item Open, Close, Read, Send, Write, Reply, Reply All, Forward, PropertyChange, CustomPropertyChange, and CustomAction. The important departure Outlook 2000 and Outlook 2002 make from previous versions is that they now enable you to write VBA code in ThisOutlookSession or develop a COM Add-in to respond to item-level events. If you raise events using the item-level objects in the Outlook Object Model, you are no longer constrained by VBScript when you write code for item-level events in Outlook custom forms.

Exceptions to the NewInspector Event

Unfortunately, there are some exceptions to this freedom that should be clearly explained at this point. If an item in a folder does not utilize an Inspector object, then you will not be able to write item-level event code in Visual Basic for this object. Certain e-mail editors do not support an Inspector object or the NewInspector event. For example, if you use Word as your e-mail editor and the format of the message you are composing is plain text, the NewInspector event does not fire in Outlook 2000 because an Inspector object is not added to the Inspectors collection when you create the mail message. The default editor selected on the Mail Format page of the Tools Options dialog box determines whether the default MailItem with the message class IPM.Note supports the Inspector object. The following table indicates which types of MailItems support an Inspector object, depending on your default mail editor and Outlook version.

Format Message	When Your E-Mail Editor Is Outlook 2000	When Your E-Mail Editor Is Word 2000 (Office Mail)	When Your E-Mail Editor Is Outlook 2002	When You E-Mail Editor Is Word 2002
HTML	Supports Inspector	Does not support Inspector	Supports Inspector	Supports Inspector
Rich Text Format (RTF)	Supports Inspector	Supports Inspector	Supports Inspector	Supports Inspector
Plain Text	Supports Inspector	Does not support Inspector	Supports Inspector	Supports Inspector

           

Outlook 2002 fixes the problematic Inspector behavior found in Outlook 2000. Word is the default e-mail editor in Outlook 2002. The NewInspector event will always fire in Outlook 2002 and is not dependent upon the default e-mail editor or the mail format.

There are other circumstances where you cannot instantiate an Inspector object when a user or program code creates or modifies an item in a folder. An Outlook 2002 Office Document item does not support an Inspector object. A DocumentItem object is any document-other than an Outlook item-that exists as an item in an Outlook folder. In common usage, an IPM.Document item will be an Office Document, but it may also be any type of document, an executable file, or an HTML document. Remember that Exchange folders can contain almost any type of Document item. Moreover, Office Document items can be posted or sent directly to a folder either by a user action or by program code. In this instance, the DocumentItem objects do not support an Inspector object. The following table indicates when a DocumentItem object supports an Inspector object.

Document Item	Message Class	Supports Inspector for Outlook Document Item	Supports Inspector for Native Document Item
Web Page	IPM.Document.shtmllfile	Not applicable	No
Word Document	IPM.Document.Word.Document.8	Yes, if created by Outlook 2000 or earlier	No
Excel Worksheet	IPM.Document.Excel.Sheet.8	Yes, if created by Outlook 2000 or earlier	No
PowerPoint Presentation	IPM.Document.PowerPoint.Show.8	Yes, if created by Outlook 2000 or earlier	No
Visio Drawing	IPM.Document.*.VSD	No	No

Earlier versions of Outlook allowed you to create custom forms based on the Outlook Office Document item. These forms wrapped a native Office document (such as a Word document, an Excel worksheet, or a PowerPoint presentation) in an Outlook Inspector. This functionality is not available in Outlook 2002. When you select the Office Document command from the New submenu of the File menu in Outlook 2002, you will see the New Office Document dialog box. When you select an Office Document type in this dialog box, you launch the hosting application and can save the document to the file system, Web storage, or an Exchange folder. You cannot create and design custom Outlook Office Document items in Outlook 2002. Outlook Office Document items still open and function correctly in Outlook 2002, but you must use an earlier version of Outlook if you want to create and design these forms.

If you post an Office document such as an Excel workbook or a PowerPoint presentation directly to a folder, an Inspector object will not be created. The NewInspector event will not fire when you add a native Office document to an Exchange folder. If you post or send an Office Document item created in a version of Outlook earlier than Outlook 2002, the NewInspector event will fire. Posting any other document, whether it is an HTML document, a .zip file, a .pdf file, or any other type of document that can be posted to a public folder, will not cause the NewInspector event to fire.

If an application external to Outlook creates an Outlook Inspector object, the NewInspector event will not fire if an Inspectors collection object has been instantiated by Outlook VBA or an Outlook COM Add-in. An external application is an application that uses Simple MAPI to create an Outlook mail message. This limitation does not apply to applications that use Outlook as an ActiveX Automation Server to create Outlook items. For example, you can send a file as an attachment to an Outlook message by selecting the Mail Recipient MAPI command on the Send To menu of the file's shortcut menu. Right-click the file in Windows Explorer to display the file's shortcut menu. When you select this command, an Inspector window opens and the file is added as an attachment to an Outlook message. However, a NewInspector event will not fire for this message. Similarly, if you use the Send Page By E-Mail or Link By E-Mail commands in Internet Explorer, a NewInspector event will not fire. The following table illustrates when a NewInspector event fires, depending on the calling application. You should realize that the exceptions regarding mail editor settings and message format discussed earlier will also determine whether the NewInspector event fires.

Calling Application	Command	NewInspector Event for Inspectors Collection object
Windows Explorer	Send To extensions such as Mail Recipient MAPI command	No
Internet Explorer	File Send Page By E-Mail or Link By E-Mail	No
Outlook	File New Mail Message	Yes, depending on  default e-mail editor  and message type
Outlook	Create New Item  (either through user action or program code)	Yes
Word, Excel, Visual Basic, Visual C++, or any COM-compliant ActiveX automation controller application	Outlook automation through program code	Yes

NewInspector

The NewInspector event occurs when a new Inspector object is created either through a user action or program code. The NewInspector event fires before the Inspector window is displayed. If you create an item through code and do not display the item, then the NewInspector event does not occur.

As discussed earlier, the NewInspector event is the gateway to item-level events. The following code example shows how to create item-level objects depending on the class of the item returned by the CurrentItem property of the Inspector object. Once you have instantiated these form-level objects in your VBA code, you can raise events on the form-level objects in VBA as long as you have declared the form-level objects using the WithEvents keyword. All of the traditional form-level events, such as Item_Open, Item_Read, Item_Write, and Item_Send, are available for the Item object declared using WithEvents.

The importance of this approach is that these events are now available to you in VBA or in your COM Add-in, rather than in VBScript code written for a custom form.

'Place these declarations in the general section ThisOutlookSession
Public WithEvents objInsp As Outlook.Inspector
Public WithEvents colInsp As Outlook.Inspectors
Public WithEvents objMailItem As Outlook.MailItem
Public WithEvents objPostItem As Outlook.PostItem
Public WithEvents objContactItem As Outlook.ContactItem
Public WithEvents objDistListItem As Outlook.DistListItem
Public WithEvents objApptItem As Outlook.AppointmentItem
Public WithEvents objTaskItem As Outlook.TaskItem
Public WithEvents objTaskRequestItem As Outlook.TaskRequestItem
Public WithEvents objTaskRequestAcceptItem As Outlook.TaskRequestAcceptItem
Public WithEvents objTaskRequestDeclineItem As Outlook.TaskRequestAcceptItem
Public WithEvents objTaskRequestUpdateItem As Outlook.TaskRequestUpdateItem
Public WithEvents objJournalItem As Outlook.JournalItem
Public WithEvents objDocumentItem As Outlook.DocumentItem
Public WithEvents objReportItem As Outlook.ReportItem
Public WithEvents objRemoteItem As Outlook.RemoteItem

Private Sub colInsp_NewInspector(ByVal Inspector As Inspector)
    Dim objItem As Object
    Set objInsp = Inspector
    On Error Resume Next
    Set objItem = objInsp.CurrentItem
    Select Case objItem.Class
        Case olMail
            Set objMailItem = objItem
        Case olPost
            Set objPostItem = objItem
        Case olAppointment
            Set objApptItem = objItem
        Case olContact
            Set objContactItem = objItem
        Case olDistributionList
            Set objDistListItem = objItem
        Case olTask
            Set objTaskItem = objItem
        Case olTaskRequest
            Set objTaskRequestItem = objItem
        Case olTaskRequestAccept
            Set objTaskRequestAcceptItem = objItem
        Case olTaskRequestDecline
            Set objTaskRequestDeclineItem = objItem
        Case olTaskRequestUpdate
            Set objTaskRequestUpdateItem = objItem
        Case olJournal
            Set objJournalItem = objItem
        Case olReport
            Set objReportItem = objItem
        Case olRemote
            Set objRemoteItem = objItem
        Case olDocument
            Set objDocumentItem = objItem 
    End Select
End Sub

The item's class is a better guide to the type of item than the item's message class. For example, all Contact items have a class value of olContact. If you look up the olContact value in the OlObjectClass Enum, olContact has a decimal value of 40. Any contact items, whether they are default contact items with a message class of IPM.Contact or custom contact items with a message class of IPM.Contact.MyCustomContactForm, have an item class value equal to olContact.