Visual Studio Tools for Office: Using Visual Basic 2005 with Excel, Word, Outlook, and InfoPath

2017-07-07 02:10:07

The Explorer object represents an Outlook Explorer windowthe main window in Outlook that displays views of folders. It is possible to open multiple Explorer windows; you 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 selected folder in the Explorer window, the view being used to display the list of items in that folder, and the 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 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 selected folder. Then it checks to see whether the Contacts folder is selected. If that folder isn't selected, the code 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

Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim exp As Outlook.Explorer = Me.ActiveExplorer() If exp IsNot Nothing Then MsgBox(String.Format("{0} is selected.", _ exp.CurrentFolder.Name)) Dim folder As Outlook.MAPIFolder folder = Me.Session.GetDefaultFolder( _ Outlook.OlDefaultFolders.olFolderContacts) If Not exp.IsFolderSelected(folder) Then exp.SelectFolder(folder) End If MsgBox(String.Format("{0} is selected.", _ exp.CurrentFolder.Name)) End If End Sub End Class

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 and then choosing View > Arrange By > Current View > Define Views to display the dialog box shown in Figure 11.4.

Figure 11.4. The Custom View Organizer dialog box 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

Public Class ThisApplication Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim exp As Outlook.Explorer = Me.ActiveExplorer() If exp IsNot Nothing Then Dim folder As Outlook.MAPIFolder folder = Me.Session.GetDefaultFolder( _ Outlook.OlDefaultFolders.olFolderInbox) exp.SelectFolder(folder) Dim view As Outlook.View = folder.Views(folder.Views.Count) exp.CurrentView = view MsgBox(String.Format("The view is now {0}.", view.Name)) End If End Sub End Class

In addition to a selected folder and selected view, Outlook items can be 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. The collection also has an Item method that allows you to get to an individual Outlook item that was selected, or you can use the For Each loop 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 16 types of Outlook items (MailItem, ContactItem, and so on).

In Listing 11.7, 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 the late-bound Subject property to get the subject from each selected Outlook item. We know that the Subject property exists on all 16 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 16 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 Class ThisApplication Private WithEvents explorer As Outlook.Explorer Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup explorer = Me.ActiveExplorer() End Sub Private Sub explorer_BeforeFolderSwitch1( _ ByVal NewFolder As Object, _ ByRef Cancel As Boolean) _ Handles explorer.BeforeFolderSwitch Dim selection As Outlook.Selection = explorer.Selection For Each o As Object In selection ' Access late bound Subject property Dim subject As String = CType(o.Subject, String) MsgBox(String.Format( _ "An Outlook Item is selected with subject {0}.", _ subject)) Next End Sub End Class

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.

Table 11.4. Explorer Properties and Methods
Name	Type	Description
Activate()		Makes the Explorer window the active window with focus.
Caption	`String`	Read-only property that returns a `String` value containing the caption of the Explorer window.
Close()		Closes the Explorer window.
Height	`Integer`	Gets and sets the height of the Explorer window in pixels. This can be set only when the WindowState is set to `OlWindowState.olNormalWindow`.
Left	`Integer`	Gets and sets the left position of the Explorer window in pixels. This can be set only when the WindowState is set to `OlWindowState.olNormalWindow`.
Top	`Integer`	Gets and sets the top position of the Explorer window in pixels. This property can be set only when the WindowState is set to `OlWindowState.olNormalWindow`.
Width	`Integer`	Gets and sets the width of the Explorer window in pixels. This can be set only when the WindowState is set to `OlWindowState.olNormalWindow`.
WindowState	optional `Object`	Gets and sets the window state of the Explorer window using the `OlWindowState` enumeration. Can be set to `olMaximized, olMinimized`, and `olNormalWindow`.

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 primary interop assembly (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 new button.

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

Public Class ThisApplication Private WithEvents btn1 As Office.CommandBarButton Private Sub ThisApplication_Startup(ByVal sender As Object, _ ByVal e As System.EventArgs) Handles Me.Startup Dim explorer As Outlook.Explorer = Me.ActiveExplorer() If explorer IsNot Nothing Then Dim bar As Office.CommandBar = explorer.CommandBars.Add( _ "My Command Bar", Temporary:=True) bar.Visible = True btn1 = bar.Controls.Add( _ Office.MsoControlType.msoControlButton, Temporary:=True) btn1.Caption = "My Custom Button" btn1.Tag = "OutlookAddin1.btn1" btn1.Style = Office.MsoButtonStyle.msoButtonCaption End If End Sub Private Sub Btn1_Click(ByVal ctrl As Office.CommandBarButton, _ ByRef cancelDefault As Boolean) Handles btn1.Click MsgBox("You clicked my button!") End Sub End Class

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 box that appears. Figure 11.5 shows the Home Page tab of the Properties dialog box. You can also associate a Web page with a Folder using the MAPIFolder object's WebViewURL property. If you check 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 returns a non-Nothing value only 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 that is not covered further in this book.