Programming Microsoft Outlook and Microsoft Exchange, Second Edition (DV-MPS Programming)

To help you develop COM add-ins as well as other applications, the object model has been updated in Outlook 2000 with over 100 new methods and properties and a bunch of new events that your applications can hook into. Figure 8-7 shows the hierarchy for the Outlook 2000 object model. In the rest of this chapter, we'll look at some of the objects, methods, properties, and events, and I'll give you hints for using them in your own applications. For more information on the Outlook 2000 object model, consult the help file named vbaoutl9.chm on the companion CD.

NOTE

Figure 8-7. The Outlook 2000 object model hierarchy.

Objects and Collections

Outlook 2000 contains some collections and objects that consist of item types you can create, such as distribution lists, as well as user interfaces, such as custom property pages.

DistListItem Object

The DistListItem object represents a distribution list in a Contacts folder, which allows your users to do away with personal address books. The DistListItem object can hold multiple recipients both from the address list in Exchange Server as well as from one-off addresses.

You can use the CreateItem method on the Application object to create a new DistListItem object, or you can add the DistListItem object to a Contacts folder by using the Add method of the Items collection for the folder. The following code shows you how to use both methods to create a DistListItem object:

The DistListItem object inherits many of the methods and properties that other Outlook items also inherit, but it also has some unique methods and properties, which are described in the following sections.

To add new members to your DistListItem object, you use the AddMembers method. Before you call this method, however, you must create a new Recipients collection to hold the names you want to add to the distribution list. The easiest way to create the new Recipients collection is to create a new mail item and use the Recipients collection available on the mail item. Then you can populate the collection and create the new DistListItem object as shown here:

To remove members from your DistListItem object, you use the RemoveMembers method. This method is similar to the AddMembers method in that you need to pass it to a valid Recipients object that contains the members you want to remove. The following code shows you how to use this method:

The DistListItem object contains a property named DLName. This property can be used to set or return the name of the distribution list. The following code finds all the distribution lists in your Contacts folder and returns their names in a message box:

Sometimes you'll want to know how many users are on a distribution list before you mail items to it. To retrieve the count for the number of users contained in a distribution list object, you must use the MemberCount property. Note that this count does not include the member count for nested distribution lists in your original list. For example, if you have a distribution list with 20 members, and one of those members is a distribution list with 50 members, the MemberCount property will return 20, not 70. The following code finds all the distribution lists in your Contacts folder and returns a sum of all the MemberCount properties:

SyncObject Object and SyncObjects Collection

Outlook 2000 allows users to set up quick synchronization folder groups. These synchronization groups, or profiles, allow users to configure different synchronization scenarios, such as which folders get synchronized offline and which filters apply to those folders. Users can then select the proper profile for their connection speed or synchronization preferences.

The Outlook SyncObjects collection contains all the synchronization profiles set up for the current user. Your program can start or stop any of these synchronization profiles using the methods of the SyncObject object. You can also monitor the progress of the synchronization by hooking into the events provided by the SyncObject object, named SyncStart, Progress, OnError, and SyncEnd. Let's look at how to use the SyncObjects collection and the SyncObject object.

The SyncObjects collection contains one property, named the Count property, and one method, named the Item method, that you can use to find out more information about the SyncObject objects contained in the collection. The Item method allows you to identify an object in the collection by specifying a numeric or named index. By using the Item method, you can quickly retrieve a SyncObject object. The Count property returns the number of SyncObject objects contained in the collection.

The next code example shows you how to use both the Item method and the Count property. First, the code finds a SyncObject object named slow modem, and then it displays the number of synchronization profiles the user currently has set up. Note that you cannot create or delete SyncObject objects programmatically. Only the user can do this through the Outlook user interface.

Once you find a SyncObject object, you might want to start or stop the synchronization process. You can do this by using the Start and Stop methods of the SyncObject object, as shown here:

The SyncObject object provides four events that your application can hook into to track the progress of a synchronization process: SyncStart, SyncEnd, Progress, and OnError. To implement these events, you must first declare a variable using the Dim statement in Visual Basic that defines a SyncObject object and uses the keyword WithEvents. The SyncStart event is fired when Outlook starts synchronizing using a particular SyncObject. The SyncEnd event is fired immediately after Outlook finishes synchronizing. The OnError event is fired when Outlook encounters an error when synchronizing. The OnError event procedure is passed both the error code and the description of the error as a string.

The final event, Progress, is fired periodically by Outlook to report on the progress of synchronization. Four parameters are passed to the Progress event procedure: State, Description, Value, and Max:

• State is a Long data type that indicates the status of the synchronization. State can have the value olSyncStopped (0) or olSyncStarted (1).
• Description is a string that describes the current state of synchronization.
• Value is a variable of Long data type that indicates the current value in the synchronization process. Value can be the number of items synchronized in the folder.
• Max is a Long parameter that indicates the maximum value for the third parameter. The ratio of the third parameter (the value) to the fourth parameter (the maximum) represents the percent of the synchronization process that is complete.

The following code shows you how to use these events in your application. These events are not available from VBScript behind an Outlook form.

Outlook Bar Object Model

One of the most significant enhancements to the Outlook 2000 object model is the Outlook Bar objects, which allow you to manipulate the Outlook Bar shortcuts as well as the user interface. With Outlook 2000, Outlook Bar shortcuts hold not only file and folder shortcuts but also URL shortcuts to Web pages, and you can customize Outlook to meet the needs of your applications. Let's take a look at the objects and collections for the Outlook Bar object model. Figure 8-8 shows how the objects in the Outlook Bar object model work together.

Figure 8-8. The relationship between the objects and collections in the Outlook Bar object model.

Panes Collection

The Panes collection enables developers to access the available Outlook application window panes. Although Outlook supports three panes—the OutlookBar, the FolderList, and the Preview panes—only the OutlookBar pane is accessible as an object in the Panes collection. If you try to access either of the other two panes, you will receive an error.

The Panes collection is retrieved from an Explorer object by using the new Pane property on that object. Once you retrieve the Panes collection, you can use the Item method of the Pane object and pass in either the numeric index or the name of the desired Pane object. To retrieve the OutlookBarPane object, you should pass in the text OutlookBar to the Item method.

The Panes collection also supports the Count property. Use this property to retrieve the number of Pane objects in the collection.

OutlookBarPane Object

After passing the text OutlookBar to the Item method of the Panes collection, Outlook returns an OutlookBarPane object. The OutlookBarPane object contains events and properties that let you control and monitor the Outlook Bar. These are the four properties you will use on the OutlookBarPane object:

• Contents. This read-only property returns the OutlookBarStorage object for the current OutlookBarPane object. From the returned object, you can retrieve the shortcuts and groups for the Outlook Bar.
• CurrentGroup. This property returns or sets the current group displayed in the Outlook Bar. You must pass a valid OutlookBarGroup object as the value for this property.
• Name. This read-only property returns a string that indicates the name of the current OutlookBarPane object.
• Visible. This property returns or sets the visibility of the OutlookBarPane object. Visible takes a Boolean value that specifies whether you want to show the Outlook Bar in the user interface.

The following code shows you how to use the OutlookBarPane object in your applications:

The OutlookBarPane object also provides two events that you can capture when users work with the Outlook Bar: BeforeGroupSwitch and BeforeNavigate. The BeforeGroupSwitch event is fired whenever the user or object model attempts to switch to a new visible group. The BeforeGroupSwitch event procedure takes two parameters, Group and Cancel. If you set the Cancel parameter to True, the switch is canceled. The Group parameter is an OutlookBarGroup object containing the Outlook group that the user is trying to navigate to. The following code shows you how to use BeforeGroupSwitch and cancel it when a user tries to navigate to a specific Outlook group.

The BeforeNavigate event fires when the user attempts to click on an Outlook Bar shortcut. The BeforeNavigate event procedure takes two parameters, Shortcut and Cancel. Shortcut is an OutlookBarShortcut object, the Outlook Bar shortcut the user is trying to navigate to, and Cancel is a Boolean, which you can set to True to cancel the navigation. The following code example shows you how to use BeforeNavigate:

OutlookBarStorage Object

The OutlookBarStorage object is a container for the objects in an OutlookBarPane object. This object contains only one property—the Groups property—which you will use in your applications. The Groups property returns an OutlookBarGroups collection, which enables you to scroll through the groups on the Outlook Bar. The following code shows you how to use the Groups property to retrieve the OutlookBarGroups collection and then scroll through each group in the collection:

OutlookBarGroups Collection

The OutlookBarGroups collection contains OutlookBarGroup objects that represent all the Outlook groups on your Outlook Bar. Use this collection to count and add new groups to the Outlook Bar. This collection supports one property, Count, which you can use to retrieve the number of groups in the collection, as shown in the following code:

This collection also supports three methods—Add, Item, and Remove. The Add method adds a new, empty OutlookBarGroup object to the collection and returns a reference to this new OutlookBarGroup object. The Add method takes two parameters: one is a string that specifies the name of the group to add; the other is optional and specifies a number indicating the insertion position for the new Outlook group. The top of the bar is at position 1.

The Item method allows you to retrieve an OutlookBarGroup object by name or by index. The Remove method allows you to delete an OutlookBarGroup object by specifying the index of the object you want to remove.

The following example uses all three of these methods together. It creates a new OutlookBarGroup object, finds the object by using the Item method, and deletes the object by using the Remove method.

The OutlookBarGroups collection is interesting because it supports three events that you can hook into: BeforeGroupAdd, BeforeGroupRemove, and GroupAdd. These three events enable you to trace when users try to add or remove certain Outlook groups and, if desired, cancel the user's action of removing or adding an Outlook group.

The BeforeGroupAdd event is fired before a new group is added to the Outlook Bar through either the user interface or code. The BeforeGroupAdd event procedure is passed a Boolean parameter named Cancel which, if set to True, will not be added to the new group by Outlook. The next code snippet shows you how to use the BeforeGroupAdd event to cancel a user's attempt to add an Outlook group. Note that because the group hasn't been created yet, a reference to the new group is not passed the BeforeGroupAdd event procedure, so you have no way of knowing which group the user is trying to add. However, since the GroupAdd event passes you the group the user added, you can write code in that event procedure to remove the group if the user is not allowed to add it.

The BeforeGroupRemove event is fired before a group is removed from an Outlook Bar. You can hook into this event with your custom applications to prevent users from deleting Outlook groups you created programmatically. The BeforeGroupRemove event procedure is passed two parameters. The first is an OutlookBarGroup object, which corresponds to the Outlook group that a program or user is trying to remove. The second is the Cancel Boolean parameter, which you can set to True to cancel the removal of the Outlook group. The following code checks to see whether the user is trying to remove her Outlook Shortcuts group, and when it finds out that she is, the code cancels the action:

The GroupAdd event fires when a new group has been added successfully to the Outlook Bar. The GroupAdd event procedure is passed an OutlookBarGroup object, so you know which group has been added. If the user adds the new group using the Outlook user interface, the group will be named New Group because this is the default name for newly created Outlook groups. The following code displays a message box that shows the name of the Outlook group you added:

OutlookBarGroup Object

The OutlookBarGroup object represents an Outlook group on your Outlook Bar. The OutlookBarGroup object supports three properties and no methods. Use these three properties to access information about the Outlook group as well as shortcuts inside the Outlook group:

• Name. This property returns or sets the name of the OutlookBarGroup using a string.
• Shortcuts. This property returns the set of Outlook shortcuts contained in the group as an OutlookBarShortcuts collection.
• ViewType. This property returns or sets the way icons are displayed in the Outlook Bar. This property can be two values, either olLargeIcon (1) or olSmallIcon (2).

The following example shows you how to use all these properties. It loops through the OutlookBarGroups collection, and then retrieves each OutlookBarGroup object and displays information about it.

OutlookBarShortcuts Collection

The OutlookBarShortcuts collection contains a set of OutlookBarShortcut objects and represents the shortcuts in an OutlookBarGroup object. This collection supports the Count property, which returns the number of OutlookBarShortcut objects in the collection.

This collection also supports three methods so that you can manipulate it: Add, Item, and Remove. The first method, Add, allows you to create a new shortcut in your Outlook group. The return value for Add is the new OutlookShortcut object you created. This method takes three parameters. The first parameter is a Variant that is the target for the shortcut. The target can be either a MAPIFolder object or a string that specifies a URL. Outlook 2000 supports placing URL shortcuts on your Outlook Bar. The second parameter is a string that specifies the name of the shortcut you are creating. The final parameter is an optional parameter that specifies the insertion position of the new shortcut. A value of 0 specifies to insert the shortcut at the top of the Outlook group. The following code example adds both a folder and a URL shortcut to a newly created Outlook group using the Add method:

The second method, Item, allows you to specify the index number or the name of the shortcut you want to retrieve from the collection. The third method, Remove, takes the index of the OutlookBarShortcut object you want to remove from the collection. The following code shows you how to find and remove all shortcuts that point to the Inbox:

The OutlookBarShortcuts collection supports these events: BeforeShortcutAdd, BeforeShorcutRemove, and ShortcutAdd. The BeforeShortcutAdd event fires before a new shortcut is added to the Outlook Bar. The BeforeShortcutAdd event procedure is passed a parameter named Cancel, which you can set to True to cancel the attempted addition of the shortcut. The following code shows you how to hook into this event and cancel the action of a user trying to add a new shortcut to his Outlook Shortcuts group. Note that you are not passed the new Outlook shortcut object because the event is fired before the new shortcut is created.

The second event supported by the OutlookBarShortcuts collection is the BeforeShortcutRemove event, which fires before a shortcut is removed from a group in the Outlook Bar. The BeforeShortcutRemove event procedure is passed two parameters: an OutlookBarShortcut object that corresponds to the shortcut the user or program is trying to remove; and Cancel, which is a Boolean parameter that you can set to True to cancel the removal. The following code shows you how to use this event to prevent a user from removing his Calendar shortcut from the Outlook Shortcuts group:

The third event supported by the OutlookBarShortcuts collection is ShortcutAdd. This event fires after a new Outlook shortcut has been added to the Outlook Bar. This event passes to you, as an OutlookBarShortcut object, the newly added shortcut. The following example shows you how to hook into this event:

OutlookBarShortcut Object

The OutlookBarShortcut object represents an Outlook shortcut on your Outlook Bar. Use this object to inquire about the target a shortcut points to. You make the inquiry by using the Target property. The Target property returns a Variant object; the data type of this Variant is determined by the target for the shortcut. If the shortcut points to a folder, the data type is MAPIFolder. If the shortcut points to a file system folder, the data type is Object. If the shortcut points to a URL or a file system path, the data type is String. You can see how to use this object in the Account Tracking application we examine in Chapter 10.

Selection Collection Object

To provide your applications with the ability to identify what the user has selected in an Explorer window in Outlook, the Outlook object model has added a Selection collection object. The Selection object contains the set of items that a user has selected in the user interface. For example, you could use this collection to validate that the user has selected the proper item to enable your application to continue. You could also use it to dynamically add menu options and toolbar buttons when a user selects a certain item.

You must use the Item method with the object's index as a parameter to retrieve a specific object in the collection. The object is returned to you as an Object variable, so if you want to call a specific method or property on the object, you should coerce the object to a specific data type first.

This collection supports the Count property, which returns the number of items selected in a collection. You could use the Count property to determine the number of items the user has currently selected.

NOTE

Explorers Collection

An Explorer object represents the window in which the contents of a folder are displayed. To make it easier for you to access these Explorer windows in your application, Outlook provides an Explorers collection below the Application object. The Explorers collection contains all the Explorer objects in your application, even those that are not visible.

The Explorers collection also contains the Count property, which you can use to find out how many Explorer objects are in the collection. The Count property could be used to identify any open Explorers that need to be closed before exiting your application. This is important because Outlook cannot terminate properly when Explorers are running.

The Explorers collection contains two methods, Add and Item. By using the Add method, you can create a new Explorer object and specify the folder to display in that Explorer's window. The Add method takes two parameters. The first parameter is either a MAPIFolder object or a string containing a path to the folder. The second parameter is an optional Long data type that specifies the display mode for the folder. This value can be olFolderDisplayNormal (0), olFolderDisplayFolderOnly (1), or olFolderDisplayNoNavigation (2). The Add method returns the newly created Explorer object. This new Explorer object is initially hidden, and you must call the Display method to reveal it. The following code shows you how to use the Add method.

The Item method of the Explorers collection is used to access an individual Explorer object in the collection by passing the object's index. The following example shows you how to do this:

The Explorers collection includes a single event, NewExplorer, which you use for tracking a newly created Explorer object that has not been made visible yet. This event passes you an Explorer object that is being opened or created. The following code shows you how to use the NewExplorer event:

Inspectors Collection

An Inspector object represents the window in which an Outlook item is displayed. To make it easier for you to find out which Inspector objects are available in your application, the Outlook object model added an Inspectors collection. This collection can contain Inspector objects that are not currently visible to the user as well as Inspector objects that are. The Inspectors collection is accessed from the Application object in Outlook.

The Inspectors collection contains one property, the Count property. This property returns to you the number of Inspector objects in the collection.

The Inspectors collection also contains two methods, Add and Item. The Add method takes one parameter, which is a valid Outlook Item object, to display in the new Inspector. This method returns an Inspector object. You must call the Display method on the returned Inspector object to display the item. The following code example shows you how to use this method:

The Item method allows you to access an Inspector object in the collection. You must pass the numeric index of the Inspector object you want to retrieve.

Links Collection and Link Object

Because Outlook 98 journals are not supported in Exchange Public Folders, users are not allowed to share their journal information with others. To make group tracking activities possible, Outlook 2000 supports a feature named Activity Tracking. Activity Tracking is the ability to associate, with a contact, items and documents so that Outlook can search folders that you specify for any linked items. To enable Activity Tracking, open a contact and select the Activities tab. A sample Activities contact is shown in Figure 8-9.

Figure 8-9. The Activities tab for a specific contact. Outlook will find all linked items for a specified contact.

Outlook can search both private and public folders. To specify which folders Outlook should search, right-click on the Contacts folder and select Properties. In the Contact Properties dialog box, click on the Activities tab. On this tab, you'll see a list of searchable folders you specified. You can also add new folders to the search criteria as shown in Figure 8-10.

Your ability to use Activity Tracking would be limited if the Outlook object model didn't support working with these links programmatically. For this reason, a Links collection and a Link object have been added to the Outlook object model.

Figure 8-10. The Activities tab for a folder. From here, you can add new folders for Outlook to search for linked items to the contacts in the folder.

The Links collection contains a set of Link objects that comprise other items linked to a particular Outlook item. You can use the methods and properties of this collection to add, delete, or count the number of links to the particular item.

The Links collection contains three methods: Add, Item, and Remove. The first method, Add, creates a new Link object in the collection. You must pass to this method the object that you want to link to, and currently that object must be an Outlook Contact object. You would use the Links collection and the Add method, then, on the mail items, task items, and other types of Outlook items. The following example shows you how to use the Add method:

The second method of the Links collection, the Item method, allows you to quickly retrieve an item in the collection by using either its index or its name. The following code shows you how to retrieve a Link object in the collection by using the name of the contact that the link refers to:

The third method supported in the Links collection is Remove. This method allows you to remove a link from the collection by specifying the index of the Link object. The next bit of code shows you how to find and remove a specific Link object in the collection. Note that a user or application can associate an Outlook item with multiple contact items as links. This means that a single task could be linked to more than one contact.

The Link object contains properties but no methods. Of all the properties, you will probably use only three in your applications: Item, Name, and Type. The Item property returns the Outlook item that is represented by the Link object. For Outlook 2000, this property always returns an Outlook Contact item, which you can then manipulate in your code. The following example shows you how to use the Item property:

The Name property returns the name of the contact that the Link object is representing. This name is the display name for the contact. The Type property returns the Outlook item type represented by the Link object. As of publication, the only valid type is olContact.

PropertyPages Collection, PropertyPage Object, and PropertyPageSite Object

For information on the PropertyPages collection, the PropertyPage object, and the PropertyPageSite object, refer to the Account Tracking application enhancements in Chapter 10.

Methods, Properties, and Events for Existing Objects

Outlook 2000 adds more capabilities to existing objects in the Outlook object model. These enhancements include new methods and properties for the objects as well as a host of new events that your applications can use to receive notifications from Outlook.

Application Object

Recall that the Application object is the topmost object in the Outlook object model, so you must create an Application object before you create any other objects. Let's take a look at some of the methods, properties, and events of the Application object.

The ActiveWindow method returns the object that represents the topmost Outlook window on the desktop. The return type for this object can be either an Explorer object or an Inspector object. If there is no currently open Explorer or Inspector object, this method returns nothing. Use this method to determine which object the current user is viewing and, if necessary, change the state of that object. The following code shows you how to use the ActiveWindow method:

The AnswerWizard property returns an AnswerWizard object for the application. If you want more information on the AnswerWizard object model, see the Office 2000 documentation.

The COMAddIns property returns a COMAddIns collection that represents all COM add-ins currently loaded and connected in Outlook. You can use this collection to quickly access COM add-ins and their exposed objects. The following example shows you how to use the COMAddIns property:

The Explorers property returns the Explorers collection. The Inspectors property returns the Inspectors collection. For more information on these collections, see the "Objects and Collections" section earlier in this chapter.

The LanguageSettings property returns a LanguageSettings object that you can use to retrieve language-related information about Outlook. For example, you can retrieve the install language, the user interface language, and the help language for Outlook. For COM add-ins, you can use this information to load the proper resource string for a user interface according to the language of the user.

The ProductCode property returns a string that is the globally unique identifier (GUID) for the Outlook product. If you need to identify Outlook in your COM add-ins or applications, this GUID can be used to identify it.

The ItemSend event fires whenever an attempt is made to send an item by using Outlook. This event returns an object, which is the item the user or application is trying to send, and a Boolean named Cancel. If you set Cancel to True, Outlook will stop the send action and leave the Inspector open for the user. If you do cancel the send, you should display an explanation in a message box so that users know what they need to add or delete to successfully send the item. The following code checks to see whether a user added a subject and a category to his message before he is able to send the item. Note that the ItemSend event does not fire when a user posts an item to a folder. In this case, you should monitor the folder for the ItemAdd event.

The NewMail event fires when a new item is received in the Inbox of the current user. This event does not pass any parameters. Note that there is no one-to-one correspondence between the number of arriving messages and the number of times this event fires; the Inbox could receive many new messages but Outlook might fire this event only once. The following code shows you how to use the NewMail event:

For information on the OptionsPagesAdd event, see the Account Tracking application in Chapter 10.

The Quit event is fired when Outlook begins to close. Using this event, you can persist any settings or other information as well as destroy any objects that are left open by your application.

The Reminder event is fired immediately before a reminder is displayed. This event passes one parameter, which is an object that corresponds to the item firing the reminder. You cannot cancel this event, so you are notified only that a reminder is going to appear. The following example shows you how to use the Reminder event:

The Startup event is fired after Outlook and any of its COM add-ins have been loaded. You can use this event to initialize VBA programs you created with Outlook.

NameSpace Object

The NameSpace object has been enhanced incrementally in Outlook 2000. The main enhancements you are mostly likely to use in your applications are the ability to dynamically add a .pst file to the NameSpace object, and the ability to create custom property pages for folders. Let's examine more closely the additions to the NameSpace object.

The SyncObjects property returns the SyncObjects collection for the NameSpace object. For more information on the SyncObjects collection, see the "Object and Collections" section earlier in the chapter.

The AddStore method allows you to dynamically connect an existing .pst file to Outlook and to create a new .pst file. This method takes one parameter, which is a path to the .pst file you want to access or create. If you pass in a path for the .pst file and the .pst file doesn't exist, Outlook will create the file. You can then retrieve the information in the .pst file by using the Outlook object model. The following example shows you how to use the AddStore method to access an existing .pst file on the hard drive:

For more information on this event, please see the enhanced Account Tracking application in Chapter 10.

Explorer Object

One of the most frequent requests by Outlook developers is to have more granular control over the way Explorers and Inspectors are graphically displayed on the screen. With Outlook 2000, you can not only control the location of your Explorer and Inspector windows but also receive events from these objects that describe what the user is doing with the user interface. Let's take a look at the additions to the Explorer object in Outlook 2000.

The Caption property returns the string for the Explorer window text. This property is read-only.

The CurrentView property returns or sets the view for the Explorer. When you set this property, you will cause the BeforeViewSwitch and ViewSwitch events to fire on the Explorer object. Since Outlook supports only a single initial view of a folder, you can use this property to customize per-user settings for the initial view. To do this, use the FolderSwitch event for the Explorer object. When this event fires, check the current folder and current user. Based on the current folder and current user, set the CurrentView property appropriately. The following code snippet shows an example of this functionality:

The Height property returns or sets the height of the Explorer window in pixels. You can use this property to dynamically change the height of your Explorer window.

The Left property returns or sets the distance from the left edge of the screen to the left edge of the Explorer window in pixels.

The Panes property returns the Panes collection for the Explorer object. For more information on the Panes collection, see the "Objects and Collections" section earlier in the chapter.

The Selection property returns a Selection collection, enabling you to access the items currently selected by the user. For more information on the Selection collection, see the "Objects and Collections" section earlier in the chapter.

The Top property returns or sets the distance, in pixels, from the top edge of the screen to the top edge of the Explorer window.

The Width property returns or sets the width of the Explorer window in pixels. The next code sample uses the Top, Width, Left, and Height properties to move an Explorer window around the screen. Notice how the code first sets the WindowState property to olNormalWindow. Outlook will return an error if the window is already maximized or minimized when you try to set these properties.

The WindowState property returns or sets the window state. The possible values for this property include olMaximized (1), olMinimized (2), and olNormalWindow (3).

The Activate method activates an Explorer object by bringing it to the foreground and giving it keyboard focus. You can use this method to highlight a specific Explorer or Inspector window for your application.

The IsPaneVisible method returns a Boolean that specifies whether a particular pane is visible in the Explorer window. You pass in the desired pane as a parameter to this method. The possible values you can pass are olOutlookBar (1), olFolderList (2), and olPreview (3). Use the IsPaneVisible method in conjunction with the ShowPane method, which is described next.

The ShowPane method either hides or displays a specific pane in your Explorer window. You must pass to this method the pane you are interested in as well as a Boolean parameter that is either set to True to display the pane or set to False to hide the pane. The following code example shows you how to use the IsPaneVisible method with the ShowPane method to hide and display panes in an Explorer window:

The Activate event is fired when an Explorer or an Inspector window becomes the active window. You can use this event to see whether a specific Explorer or Inspector window is made the active window and then customize the toolbar for that window. The following code shows you how to use this event:

The BeforeFolderSwitch event occurs before the Explorer navigates to the new folder. This event passes to you, as an object, the folder the user is trying to navigate to as well as a Boolean parameter named Cancel. To keep the user on the current folder and prevent the user from navigating to the new folder, set Cancel to True. If the user navigates to a folder in the file system, the BeforeFolderSwitch event will not pass an object for that folder. For an example of this event in action, look at the Account Tracking application in Chapter 10.

The BeforeViewSwitch event fires when a user tries to switch views. This event passes the name of the view the user is trying to change to as well as the Boolean variable Cancel. To cancel the view change and maintain the user's current view, set the Cancel variable to True. The following code sample shows you how to use the BeforeViewSwitch event:

This event is fired when the Explorer or Inspector window is no longer the active window. This event does not pass any parameters.

This event fires after a user successfully switches folders. This event does not pass any parameters.

This event is fired after the user selects a different item in the current view. This event does not pass any parameters. The next code sample shows you how to use this event with the Selection collection:

This event fires when the user successfully changes the view in the Explorer window. This event does not pass any parameters.

This event fires when the Explorer window is being closed. Most likely, you will listen for this event only when developing COM add-ins that need to correctly destroy Explorer objects or the variables that reference them.

Inspector Object

Since the properties, methods, and events for the Inspector object we have seen are the same as their Explorer object counterparts, I'm not going to dive into the details of these. I have listed them, however, below. For more information about them, reference the descriptions of the additions to the Explorer object.

• Caption property
• Height property
• Top property
• Width property
• WindowState property
• Activate method
• Activate event
• Deactivate event
• Close event

Folders Collection

The Folders collection contains three new events that you can use in your applications: FolderAdd, FolderChange, and FolderRemove.

The FolderAdd event fires when a folder is added to the Folders collection. This event passes the added folder as a MAPIFolder object. You cannot cancel this event. You might want to hook into this event to prompt the user to add the folder to a specific group on the Outlook Bar. The following code uses the FolderAdd event:

The FolderChange event fires when something is changed in the specified Folders collection, such as deleting all the items in the folder. This event passes the changed folder as a MAPIFolder object, but it does not pass the actual folder property that was changed. You have to figure out which property was changed programmatically. You can't cancel this event. The following code shows you how to use the FolderChange event.

The FolderRemove event fires when a folder is removed from the collection. It does not pass any parameters, so if you need to know which folder was removed, your code has to figure this out. Outlook will only notify you that some folder was removed. You can't cancel the FolderRemove event.

MAPIFolder Object

The MAPIFolder object provides three interesting properties: WebViewAllowNavigation, WebViewOn, and WebViewURL. All three are described in Chapter 10 in the context of the Account Tracking application enhancements.

Items Collection

Recall that the Outlook Items collection is a collection of objects in a particular folder. The type of object the Items collection contains depends on the items in the folder. For example, in your Calendar folder, the Items collection will most likely contain AppointmentItem objects. The following sections highlight the enhancements to the Items.

The ItemAdd event fires when a new item is added to the folder. This event returns, as an object, the item added to the collection for the folder. Remember that before you attempt to call methods or properties on a returned object, you should check which type of object was returned. The type of object returned might not be the type you expected and could cause unwanted behavior in your application. For an example of how to use this event, see the Account Tracking application in Chapter 10.

The ItemChange event is fired when an item in the collection is changed in any way. The event passes to you, as an object, the item that was changed; it does not pass you the changed property. This means that you use your code to determine what was changed on the item. For an example of using this event, see the Account Tracking application later in Chapter 10.

The ItemRemove event is fired when an item is removed or deleted from the collection. This event does not pass any parameters. This means that your code must figure out which items were deleted from the collection.

Characteristics of Item Types

The following section describes some characteristics of all the item types in Outlook, such as the PostItem, the MailItem, and the AppointmentItem objects. The events we'll discuss can be used with Visual Basic/VBA and from VBScript, so the examples are written using VBScript.

Links Property

The Links property returns the Links collection for the object. For more information on the Links collection, refer to the "Methods, Properties, and Events for Existing Objects" section earlier in this chapter.

AttachmentAdd Event

The AttachmentAdd event fires after an attachment has been added to an Outlook item. This event passes the attachment as an Attachment object. Once the object is passed, you can perform tasks, such as checking the attachment for viruses, before the user sends the item. You cannot, however, cancel or stop the user from adding an attachment to the item. The following VBScript example shows you how to use this event:

AttachmentRead Event

The AttachmentRead event fires after an attachment has been opened for reading and passes the attachment as an Attachment object. You can use this event to perform certain actions when the user opens the attachment, such as making a backup copy of the attachment or marking this attachment as checked out for a document management solution. The following example shows you how to prompt the user to save changes when the user opens an attachment to read it:

BeforeAttachmentSave Event

The BeforeAttachmentSave event fires before an attachment is saved with the item. Since this event is supported in both VBScript and Visual Basic/VBA, you must follow the appropriate syntax. When you use this event from VBScript behind your Outlook form, the BeforeAttachmentSave event passes the attachment that is trying to be saved as an Attachment object. If you're using Visual Basic or VBA, this event passes both the attachment as well as a Boolean parameter named Cancel. To abort the save, set Cancel to True. The following two code examples show you a VBScript version and a Visual Basic/VBA version of this event, respectively. Notice how the VBScript version is a function and the Visual Basic/VBA version is a subroutine.

BeforeCheckNames Event

The BeforeCheckNames event fires before Outlook starts resolving names for the recipients of an item. You can use this event to check the names of the recipients from another data source such as a database. This event, like the BeforeAttachmentSave event, has two different syntaxes depending on whether you are calling the event from VBScript or Visual Basic/VBA. In VBScript, this event is implemented as a function that you can cancel by setting the name of the function to False. In Visual Basic/VBA, you are passed a Boolean parameter named Cancel. To cancel the name resolution, you set Cancel to True. The two following examples show you the VBScript version and the Visual Basic/VBA version: