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.
Applies to: The information in this topic applies to application-level projects for the following applications: Excel 2007 and Excel 2010; InfoPath 2007 and InfoPath 2010; Outlook 2007 and Outlook 2010; PowerPoint 2007 and PowerPoint 2010; Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.
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, InfoPath, and PowerPoint 2010
Excel and PowerPoint 2007
.gif "link to video")
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:
To monitor the state of Inspector windows, you can handle the following Inspector-related events:
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_Event.Close or InspectorEvents_10_Event.Close.
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, InfoPath, and PowerPoint 2010
Word, InfoPath, and PowerPoint 2010 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 Microsoft.Office.Interop.Word.Window (for Word), Microsoft.Office.Interop.InfoPath.WindowObject (for InfoPath), or Microsoft.Office.Interop.PowerPoint.DocumentWindow (for PowerPoint) to the window parameter.
For more information, see Managing Task Panes in Multiple Word and InfoPath Documents. This article is specifically about Word and InfoPath, but the concepts in it also apply to PowerPoint 2010, because this release of PowerPoint has a single-document interface.
Word Events
To monitor the state of document windows in Word, you can handle the following events:
InfoPath Events
To monitor the state of document windows in InfoPath, you can handle the following events:
PowerPoint Events
To monitor the state of document windows in PowerPoint 2010, you can handle the following events:
Excel and PowerPoint 2007
Excel and PowerPoint 2007 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:
PowerPoint Events
To monitor the state of presentations in PowerPoint 2007, you can handle the following events:
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 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