Explorer Events

Explorer events provide you with a great deal of control over the Outlook user interface. You can now control the size and window state of Explorer windows, respond to selection changes through the new SelectionChange event and the Selection object, and determine when the user has changed her view or the current folder. Outlook 2002 adds a group of events that provide a granular level of control over the Outlook application window. These events are BeforeMaximize, BeforeMinimize, BeforeMove, and BeforeSize. The IsPaneVisible and ShowPane methods allow you to show or hide the Folder List, Outlook Bar, and Preview pane. TheBeforeFolderSwitch and BeforeViewSwitch events are cancelable, so you can prevent the user from moving to a folder or activating a view. If you combine the Explorer events with the new events and programmatic control for the Outlook Bar and Office command bars, you have complete programmatic control over the Outlook user interface. You can customize the Outlook Explorer to suit the requirements of your organization.

Activate

The Activate event occurs when an Explorer window becomes the active window. Be careful not to overload this event procedure with code because the Activate and Deactivate events fire many times during an Outlook session. Each time a user opens an Inspector for an item, the following event sequence occurs:

1. Explorer Deactivate
2. Inspector Activate
3. Inspector Deactivate
4. Explorer Activate

The following code example shows you how to use the Activate event to make a command bar named Contacts visible or invisible, depending on the current folder in the Explorer:

Private Sub objExpl_Activate()
    On Error Resume Next
    If objExpl.CurrentFolder.Name = "Contacts" Then
        objExpl.CommandBars("Contacts").Visible = True
    Else
        objExpl.CommandBars("Contacts").Visible = False
    End If
End Sub

BeforeFolderSwitch

The BeforeFolderSwitch event occurs when the Explorer navigates to a new folder, either as a result of user action or through program code. This event is cancelable, so you can prevent users from navigating to prohibited folders. Of course, you can prevent users from opening prohibited folders through Exchange folder permissions, but with this event, you can also customize the Warning dialog box. The following code tests whether the current user is a member of a distribution list. If not, the user is prevented from switching to a public folder named Salary Guidelines.

Private Sub objExpl_BeforeFolderSwitch(ByVal NewFolder As Object, _
  Cancel As Boolean)
    If NewFolder Is Nothing Then Exit Sub
    Set objAE = Application.GetNamespace("MAPI").CurrentUser
    If IsDLMember("HR Admins",objAE) = False Then
        If NewFolder.Name = "Salary Guidelines" Then
            MsgBox "You do not have permission to access this folder." _
             & vbCr & "If you believe you should have access to this folder," _
            & vbCr & "please contact your departmental HR supervisor.", _ 
              vbCritical
            Cancel = True
        End If
    End If
End Sub

If NewFolder is a folder in the file system, then NewFolder is Nothing. Your code should provide for this possibility.

BeforeViewSwitch

The BeforeViewSwitch event is similar to the BeforeFolderSwitch event, except that it occurs before a view is switched to a new view, either through a user action or programmatically. If a user changes from the Contacts folder to the Tasks folder but does not explicitly change the view with the View selector, the BeforeViewSwitch event will not fire, even though the default views on the two folders have different names. This event is cancelable. The event procedure prevents the user from switching to the view named Message Timeline if there are more than 500 items in the current folder.

Private Sub objExpl_BeforeViewSwitch(ByVal NewView As Variant, _
  Cancel As Boolean)
    If NewView = "Message Timeline" Then
        If objExpl.CurrentFolder.Items.Count > 500 Then
            Cancel = True
        End If
    End If
End Sub

Close

The Close event occurs when an Explorer object closes as a result of a user action or program code. Don't confuse this event with the Close method, which causesthe Explorer window to close. The following example sets several Outlook Bar objects to Nothing when the Explorer window Close event fires:

Private Sub objExpl_Close()
    Set objPane = Nothing
    Set objContents = Nothing
    Set colOutlookBarGroups = Nothing
End Sub

Deactivate

The Deactivate event fires when an Explorer or Inspector window ceases to be the active window, either as a result of user action or through program code. You should treat this event with caution! If you display user interface elements such as a message box in the Deactivate event procedure, Outlook might exhibit unpredictable behavior. The following procedure simply writes a string to the VBA Immediate window when the Deactivate event occurs:

Private Sub objExpl_Deactivate()
    Debug.Print "Explorer Deactivate"
End Sub

You should not display a message box, dialog box, or any other user interface element during the Deactivate event of an Explorer or Inspector object. Showing a user interface element in the Deactivate event may disrupt the activation sequence and make Outlook behave unpredictably.

FolderSwitch

The FolderSwitch event occurs when the current folder changes in the Explorer, either through a user action or a programmatic change. In the following event procedures, a toolbar button is added to the Standard toolbar in the Application Startup event. If Explorer's current folder is Nwind, the FolderSwitch event makes the New Nwind CommandBarButton visible. Otherwise, the button is hidden on the Standard toolbar. This toolbar button is declared as a CommandBarButton using the WithEvents keyword in the Declarations section of ThisOutlookSession.

'Place these in declarations section of ThisOutlookSession
Public WithEvents objExpl As Outlook.Explorer
Public WithEvents objCBB As Office.CommandBarButton

'Instantiate objExpl and objCBB in Application Startup event procedure
 
Private Sub Application_Startup()
    Dim objCB As Office.CommandBar
    Set objExpl = Application.ActiveExplorer
    Set objCB = objExpl.CommandBars("Standard")
    Set objCBB = objCB.Controls.Add(Type:=msoControlButton)
    With objCBB
        .TooltipText = "New Nwind Contact"
        .Style = msoButtonIconAndCaption
        .FaceId = 1099
        .Caption = "New Nwind"
        .Visible = False
    End With
End Sub

'This event procedure hides and unhides the button
Private Sub objExpl_FolderSwitch()
    If objExpl.CurrentFolder = "Nwind" Then
        objCBB.Visible = True
    Else
        objCBB.Visible = False
    End If
End Sub

'Event handler for the button adds a new custom item to the folder
Private Sub objCBB_Click(ByVal Ctrl As Office.CommandBarButton, _
    CancelDefault As Boolean)
    Dim olNwindItem As Outlook.ContactItem
    Set olNwindItem = objExpl.CurrentFolder.Items.Add("IPM.Contact.Nwind")
    olNwindItem.Display
End Sub

SelectionChange

The SelectionChange event answers many requests from Outlook developers for a means to determine which items are currently selected in the Explorer. The SelectionChange event occurs when the selection changes in the current view in the active Explorer window. Be aware that this event does not fire if you iterate over a collection of items in the current folder programmatically. The event is not triggered if the current folder in the Explorer changes due to a user action or code. However, if the user then changes the selection with a mouse click or an arrow key after he changes folders, the SelectionChange event occurs. When the SelectionChange event fires, use the Selection Property object of the Explorer object to return the items that are selected. The following example tests theSelection object to determine whether Contact items are selected and then displays the number of selected contacts in a message box:

Private Sub objExpl_SelectionChange()
    Dim intContacts As Integer
    For i = 1 To objExpl.Selection.Count
        If objExpl.Selection.Item(i).Class = olContact Then
            intContacts = intContacts + 1
        End If
    Next
    If intContacts Then
        MsgBox "You have selected " & intContacts & " contacts.", _
            vbInformation
    End If
End Sub

ViewSwitch

The ViewSwitch event occurs when the view in the Explorer window is switched, either through user action or programmatically. Like the FolderSwitch event, this event helps you to control the Outlook user interface by notifying you when either a view or a folder has changed. The following example uses the ShowPane method to hide or display the folder list depending on the current view:

Private Sub objExpl_ViewSwitch()
    If objExpl.CurrentView = "Message Timeline" Then
        objExpl.ShowPane olFolderList, False
    Else
        objExpl.ShowPane olFolderList, True
    End If
End Sub

New Explorer Events in Outlook 2002

To bring the events available for COM Add-ins to parity with the events used by Exchange Client Extensions, Outlook 2002 introduces a series of Explorer window events. A similar set of window events is available for the Inspector object. The Explorer window events determine when an Explorer window has been minimized, maximized, moved, or sized. Additional events for Explorer enable you to perform copy, cut, and paste operations.

BeforeItemCopy

This event occurs before an item is copied from a folder to the clipboard. When an item is selected in Explorer, BeforeItemCopy corresponds to the Edit Copy command. This event is cancelable.

BeforeItemCut

This event occurs before an item is cut from a folder and moved to the clipboard. When an item is selected in Explorer, BeforeItemCut corresponds to the Edit Cut command. This event is cancelable.

BeforeItemPaste

The BeforeItemPaste event occurs before an item is pasted from the clipboard. This event also occurs when a user attempts to drag an item from one folder and drop it into another. This event is cancelable. The following example prevents a drop (or a paste) operation from being performed on a specific folder:

Private Sub objExpl_BeforeItemPaste(ClipboardContent As Variant, _
    ByVal Target As MAPIFolder, Cancel As Boolean)
    Dim strPath As String

    strPath = "\\Public Folders\All Public Folders" _
        & "\Northwind Contact Management Application\Companies"
    If objExpl.CurrentFolder.FolderPath = strPath Then
        If TypeOf ClipboardContent Is Selection Then
            MsgBox "You cannot drag items from this folder.", _
                vbCritical
            Cancel = True
        End If
    End If
End Sub

BeforeMaximize

This event occurs before the Explorer window is maximized. This event is cancelable.

BeforeMinimize

This event occurs before the Explorer window is minimized and is cancelable.

BeforeMove

This event occurs before the Explorer window is moved and is cancelable.

BeforeSize

This event occurs before the Explorer window is resized. BeforeSize does not fire when a window is restored. This event is cancelable.