Working with the Explorer Object





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

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.4.

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.

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.

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

Figure 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.

Figure. 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.

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

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.



 Python   SQL   Java   php   Perl 
 game development   web development   internet   *nix   graphics   hardware 
 telecommunications   C++ 
 Flash   Active Directory   Windows