Working with the Explorer Object

The Explorer object represents an Outlook Explorer windowthe main window in Outlook that displays views of folders. It is possible to open multiple Explorer windowsyou can right-click a folder in one Explorer window and choose the option Open in New Window. Doing so creates a new Explorer window with the folder you selected to open in a new window as the active folder.

Working with the Selected Folder, View, and Items

The Explorer object has several methods and properties that enable you to work with the currently selected folder in the Explorer window, the view being used to display the list of items in that folder, and the currently selected items.

The CurrentFolder property returns a MAPIFolder object representing the folder selected in the Explorer window. An Explorer window always has a selected folder. To change the selected folder in an Explorer window, you can use the Explorer object's SelectFolder method, which takes as a parameter the MAPIFolder object you want to select. You can also determine whether a particular folder is currently selected by using the Explorer object's IsFolderSelected method, which takes as a parameter the MAPIFolder object you want to check to see whether it is selected. The IsFolderSelected method returns TRue if the folder is selected in the Explorer window and false if it is not.

Listing 11-5 shows some code that displays the name of the currently selected folder. It then checks to see whether the Contacts folder is selected. If it isn't selected, it selects it. Finally, it displays the name of the newly selected folder. Listing 11-5 uses the NameSpace object's GetDefaultFolder method to get a MAPIFolder object for the Contacts folder.

Listing 11-5. A VSTO Add-In That Selects the Contacts Folder

private void ThisApplication_Startup(object sender, EventArgs e) { Outlook.Explorer exp = this.ActiveExplorer(); if (exp != null) { MessageBox.Show(String.Format( "{0} is selected.", exp.CurrentFolder.Name)); Outlook.MAPIFolder folder = this.Session.GetDefaultFolder( Outlook.OlDefaultFolders.olFolderContacts); if (!exp.IsFolderSelected(folder)) { exp.SelectFolder(folder); } MessageBox.Show(String.Format( "{0} is selected.", exp.CurrentFolder.Name)); } }

The CurrentView property returns a View object representing the view that is being used to display the items in the folder. A folder has a number of views that can be used to display its contents such as view by date, by conversation, by sender, and so on. It is also possible to define custom views. You can see the views that are defined for a given folder by selecting that folder in an Explorer window, then choosing View > Arrange By > Current View > Define Views to display the dialog shown in Figure 11-4.

Figure 11-4. The Custom View Organizer dialog shows views associated with a folder.

You can change the view used by an Explorer window by setting the Explorer object's CurrentView property to a View object associated with the folder. Listing 11-6 demonstrates this by selecting the Inbox folder and then setting the view for the Inbox folder to one of the View objects associated with the folder.

Listing 11-6. A VSTO Add-In That Selects the Inbox Folder and Changes the View

private void ThisApplication_Startup(object sender, EventArgs e) { Outlook.Explorer exp = this.ActiveExplorer(); if (exp != null) { Outlook.MAPIFolder folder = this.Session.GetDefaultFolder( Outlook.OlDefaultFolders.olFolderInbox); exp.SelectFolder(folder); Outlook.View view = folder.Views[folder.Views.Count]; exp.CurrentView = view; MessageBox.Show(String.Format( "The view is now {0}.", view.Name)); } }

In addition to a selected folder and selected view, there can also be Outlook items selected in an Explorer window. A user can select multiple items in a folder by Shift-clicking to select a range of items or holding down the Ctrl key while clicking to select discontiguous items. To retrieve the items that are selected in an Explorer window, use the Explorer object's Selection property. The Selection property returns a Selection collection. The Selection collection has a Count property that gives you the number of selected Outlook items. It also has an Item method that allows you to get to an individual Outlook item that was selected, or you can use the foreach keyword to iterate over a Selection collection and get back Outlook items that are selected. Outlook items are returned as type object because they could be any of the 15 types of Outlook items (MailItem, ContactItem, and so forth).

In Listing 11-6, we handle the Application object's BeforeFolderSwitch event to display the items selected in a given folder before Outlook switches to a new folder. We use reflection to get the Subject property from each selected Outlook item. We know that the Subject property exists on all 15 types of Outlook items, so this is a safe property to get for any Outlook item contained in the selection. This simplifies the code so it does not have to have a cast to all 15 Outlook item types before accessing the Subject property.

Listing 11-7. A VSTO Add-In That Iterates over the Selected Outlook Items in a Folder

public partial class ThisApplication { Outlook.Explorer explorer; private void ThisApplication_Startup(object sender, EventArgs e) { Outlook.Explorer explorer = this.ActiveExplorer(); if (explorer != null) { explorer.BeforeFolderSwitch += new Outlook.ExplorerEvents_10_BeforeFolderSwitchEventHandler( Explorer_BeforeFolderSwitch); } } private object GetPropertyHelper(object targetObject, string propertyName) { return targetObject.GetType().InvokeMember(propertyName, System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.GetProperty, null, targetObject, null, System.Globalization.CultureInfo.CurrentCulture); } void Explorer_BeforeFolderSwitch(object newFolder, ref bool cancel) { Outlook.Selection selection = explorer.Selection; foreach (object o in selection) { string subject = (string)GetPropertyHelper(o, "Subject"); MessageBox.Show(String.Format( "An Outlook Item is selected with subject {0}.", subject)); } } #region VSTO generated code private void InternalStartup() { this.Startup += new System.EventHandler(ThisApplication_Startup); } #endregion }

Working with an Explorer Window

Table 11-4 lists several properties and methods used to set and get the position of an Explorer window as well as some other commonly used properties and methods related to the management of the window.

Adding Buttons and Menus to an Explorer Window

The CommandBars property returns a CommandBars object, which is defined in the Microsoft Office 11.0 Object Library PIA object. Outlook uses the same object model used by Word and Excel to work with buttons and menus in an Explorer window. Refer to Chapter 4, "Working with Excel Events," for more information on the CommandBars object hierarchy and examples of using the CommandBar objects. Listing 11-8 shows a VSTO add-in that creates a toolbar and a button and handles the click event for the newly added button.

Listing 11-8. A VSTO Add-In That Adds a Toolbar and Button to an Explorer Window

public partial class ThisApplication { Office.CommandBarButton btn1; private void ThisApplication_Startup(object sender, EventArgs e) { Outlook.Explorer explorer = this.ActiveExplorer(); if (explorer != null) { Office.CommandBar bar = explorer.CommandBars.Add( "My Command Bar", missing, missing, true); bar.Visible = true; btn1 = (Office.CommandBarButton)bar.Controls.Add( Office.MsoControlType.msoControlButton, missing, missing, missing, true); btn1.Click += new Office._CommandBarButtonEvents_ClickEventHandler( Btn1_Click); btn1.Caption = "My Custom Button"; btn1.Tag = "OutlookAddin1.btn1"; btn1.Style = Office.MsoButtonStyle.msoButtonCaption; } } void Btn1_Click(Office.CommandBarButton ctrl, ref bool cancelDefault) { MessageBox.Show("You clicked my button!"); } #region VSTO Designer generated code private void InternalStartup() { this.Startup += new System.EventHandler(ThisApplication_Startup); } #endregion }

Associating a Web View with a Folder

It is possible to associate with an Outlook folder an HTML Web page by right-clicking a folder, choosing Properties, and then clicking the Home Page tab of the dialog that appears. Figure 11-5 shows the Home Page tab of the Properties dialog. You can also associate a Web page with a Folder using the MAPIFolder object's WebViewURL property. If you check the Show home page by default for this folder or set the MAPIFolder object's WebViewOn property to true, users are shown the Web page when they select the folder rather than an Outlook view of the items in the folder.

Figure 11-5. Associating an HTML page with a folder.

You can get to the HTML document object model for the Web page displayed by a folder by using the Explorer object's HTMLDocument property. This property only returns a non-null value if the selected folder is associated with a Web page. Interacting with the HTML document object model of a Web page through this property is an advanced topic and is not covered further in this book.