Managing Custom Task Panes in Multiple Application Windows
Applies to |
|---|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and Microsoft Office applications. Project type
Microsoft Office application
For more information, see Features Available by Application and Project Type. |
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
.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_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:
InfoPath Events
To monitor the state of document windows in InfoPath, you can handle the following events:
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:
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
Other Resources
Managing Task Panes in Multiple Word and InfoPath Documents
Change History
Date |
History |
Reason |
|---|---|---|
September 2008 |
Added link to technical article about managing custom task panes in Word and InfoPath. |
Information enhancement. |