Managing Custom Task Panes in Multiple Application Windows

When you create a custom task pane in an application that uses multiple windows to display documents and other items, you need to take extra steps to ensure that the task pane is visible when the user expects it to be.

Custom task panes in all applications are associated with a document frame window, which presents a view of a document or item to the user. The task pane is visible only when the associated window is visible. However, not all applications use document frame windows the same way.

The following application groups have different development requirements:

• Outlook

• Word and InfoPath

• Excel and PowerPoint

For a related video demonstration, see How Do I: Manage Task Panes in Word Add-ins?.

Outlook

When you create a custom task pane for Outlook, the custom task pane is associated with a specific Explorer or Inspector window. Explorers are windows that display the contents of a folder, and Inspectors are windows that display an item such as an e-mail message or a task.

If you want to display a custom task pane with multiple Explorer or Inspector windows, you need to create a new instance of the custom task pane when an Explorer or Inspector window opens. To do this, handle an event that is raised when an Explorer or Inspector window is created, and then create the task pane in the event handler. You can also handle Explorer and Inspector events to hide or display task panes depending on which window is visible.

To associate the task pane with a specific Explorer or Inspector, use the CustomTaskPaneCollection.Add(UserControl, String, Object) method to create the task pane, and pass the Explorer or Inspector object to the window parameter. For more information about creating custom task panes, see Custom Task Panes Overview.

For a walkthrough that demonstrates how to create a task pane for every e-mail message that is opened, see Walkthrough: Displaying Custom Task Panes with E-Mail Messages in Outlook.

Outlook Events

To monitor the state of Explorer windows, you can handle the following Explorer-related events:

• NewExplorer

• Activate

• Close

• Deactivate

To monitor the state of Inspector windows, you can handle the following Inspector-related events:

• NewInspector

• Activate

• Close

• Deactivate

Preventing Multiple Instances of a Custom Task Pane in Outlook

To prevent Outlook windows from displaying multiple instances of a custom task pane, explicitly remove the custom task pane from the CustomTaskPanes collection of the ThisAddIn class when each window is closed. Call the Remove method in an event that is raised when a window is closed, such as ExplorerEvents_10_EventClose or InspectorEvents_10_EventClose.

If you do not explicitly remove the custom task pane, Outlook windows might display multiple instances of the custom task pane. Outlook sometimes recycles windows, and recycled windows retain references to any custom task panes that were attached to them.

Word and InfoPath

Word and InfoPath display each document in a different document frame window. When you create a custom task pane for these applications, the custom task pane is associated only with a specific document. If the user opens a different document, the custom task pane is hidden until the earlier document is visible again.

If you want to display a custom task pane with multiple documents, create a new instance of the custom task pane when the user creates a new document or opens an existing document. To do this, handle events that are raised when a document is created or opened, and then create the task pane in the event handlers. You can also handle document events to hide or display task panes depending on which document is visible.

To associate the task pane with a specific document window, use the CustomTaskPaneCollection.Add(UserControl, String, Object) method to create the task pane, and pass a Window (for Word) or WindowObject (for InfoPath) to the window parameter.

For more information, see Managing Task Panes in Multiple Word and InfoPath Documents.

Word Events

To monitor the state of document windows in Word, you can handle the following events:

• DocumentBeforeClose

• DocumentOpen

• NewDocument

• WindowActivate

• WindowDeactivate

InfoPath Events

To monitor the state of document windows in InfoPath, you can handle the following events:

• NewXDocument

• WindowActivate

• WindowDeactivate

• XDocumentBeforeClose

• XDocumentOpen

Excel and PowerPoint

Excel and PowerPoint create one document frame window for all documents (that is, for workbooks and presentations). When you create a custom task pane in these applications, the task pane is available to every open document in the application. No extra work on your part is required to ensure that the task pane is displayed for each document.

However, depending on which document is active, you might want to hide or display the task pane, or you might want to display different user interface (UI) elements or data in the task pane. To do this, handle events that are raised when a document is created, opened, or activated, and then update the task pane in the event handlers.

Excel Events

To monitor the state of workbooks in Excel, you can handle the following events:

• NewWorkbook

• WindowActivate

• WindowDeactivate

• WorkbookActivate

• WorkbookDeactivate

• WorkbookOpen

PowerPoint Events

To monitor the state of presentations in PowerPoint, you can handle the following events:

• Microsoft.Office.Interop.PowerPoint.EApplication_Event.AfterNewPresentation

• Microsoft.Office.Interop.PowerPoint.EApplication_Event.AfterPresentationOpen

• Microsoft.Office.Interop.PowerPoint.EApplication_Event.NewPresentation

• Microsoft.Office.Interop.PowerPoint.EApplication_Event.PresentationOpen

• Microsoft.Office.Interop.PowerPoint.EApplication_Event.WindowActivate

• Microsoft.Office.Interop.PowerPoint.EApplication_Event.WindowDeactivate

Example

The following code example demonstrates how to hide or display a custom task pane in an event handler for the WorkbookActivate event in an Excel add-in. When each workbook is activated, the task pane is visible only if the workbook is named SalesData.xls; otherwise, the task pane is hidden. To run this example, replace the default ThisAddIn_Startup event handler that Visual Studio Tools for Office generates in the ThisAddIn class with the following code. This example assumes that your project includes a UserControl named UserControl1.

Dim myUserControl As UserControl1
Dim myCustomTaskPane As Microsoft.Office.Tools.CustomTaskPane

Private Sub ThisAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs) _
Handles Me.Startup
    myUserControl = New UserControl1()
    myCustomTaskPane = Me.CustomTaskPanes.Add(myUserControl, "Sales Task Pane")
End Sub 

Private Sub Application_WorkbookActivate(ByVal Wb As Excel.Workbook) _
    Handles Application.WorkbookActivate

    If Wb.Name = "SalesData.xlsx" Then
        myCustomTaskPane.Visible = True 
    Else
        myCustomTaskPane.Visible = False 
    End If 
End Sub

private UserControl1 myUserControl;
private Microsoft.Office.Tools.CustomTaskPane myCustomTaskPane;

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    this.Application.WorkbookActivate += new Excel.AppEvents_WorkbookActivateEventHandler(
        Application_WorkbookActivate);

    myUserControl = new UserControl1();
    myCustomTaskPane = this.CustomTaskPanes.Add(myUserControl, "Sales Task Pane");
}

void Application_WorkbookActivate(Excel.Workbook Wb)
{
    if (Wb.Name == "SalesData.xlsx")
        myCustomTaskPane.Visible = true;
    else
        myCustomTaskPane.Visible = false;
}

See Also

Tasks

How to: Add a Custom Task Pane to an Application

Walkthrough: Displaying Custom Task Panes with E-Mail Messages in Outlook

How to: Display Custom Task Panes with E-Mail Messages in Outlook

Walkthrough: Synchronizing a Custom Task Pane with a Ribbon Button

Concepts

Custom Task Panes Overview

Other Resources

Managing Task Panes in Multiple Word and InfoPath Documents

Change History