Custom Task Panes

Task panes are user interface panels that are typically docked to one side of a window in a Microsoft Office application. Custom task panes give you a way to create your own task pane and provide users with a familiar interface to access your solution's features. For example, the interface can contain controls that run code to modify documents or display data from a data source.

A custom task pane differs from the actions pane. The actions pane is part of document-level customizations for Microsoft Office Word and Microsoft Office Excel. For more information, see Actions Pane Overview.

Users of applications in the Microsoft Office system are already familiar with using task panes such as the Styles and Formatting task pane in Word. Custom task panes behave like other task panes in the Microsoft Office system. Users can dock custom task panes to different sides of the application window, or they can drag custom task panes to any location in the window. You can create an add-in that displays multiple custom task panes at the same time, and users can control each task pane individually.

The user interface of a custom task pane that you create by using the Office development tools in Visual Studio is based on Windows Forms controls. You can use the familiar Windows Forms Designer to design the user interface for a custom task pane. You can also use the data binding support in Windows Forms to bind a data source to controls on the task pane.

Instantiate the custom task pane by passing the user control to the CustomTaskPaneCollection object in your add-in. This collection returns a new CustomTaskPane object that you can use to modify the appearance of the task pane and respond to user events.

All custom task panes that are created by using the Office development tools in Visual Studio contain a UserControl object. This user control provides the user interface of your custom task pane. You can create the user control at design time or at run time. If you create the user control at design time, you can use the Windows Forms Designer to construct the user interface of your task pane.

After you create a user control that contains the user interface of the custom task pane, you have to instantiate a CustomTaskPane. To do this, pass the user control to the CustomTaskPaneCollection in your add-in by calling one of the Add methods. This collection is exposed as the CustomTaskPanes field of the ThisAddIn class. The following code example is intended to be run from the ThisAddIn class.

Some Office applications require explicit instructions for when to create or display your task pane when more than one window is open. This makes it important to consider where to instantiate the custom task pane in your code to ensure that the task pane appears with the appropriate documents or items in the application. For more information, see Managing Custom Task Panes in Application Windows.

If you want to automate the application from the user control, you can directly access the object model by using Globals.ThisAddIn.Application in your code. The static Globals class provides access to the ThisAddIn object. The Application field of this object is the entry point into the object model of the application.

By default, the task pane is not visible. To make the task pane visible, you must set the Visible property to true.

Users can close a task pane at any time by clicking the Close button (X) in the corner of the task pane. However, there is no default way for users to open the custom task pane again. If a user closes a custom task pane, that user cannot view the custom task pane again unless you provide a way to display it.

If you create a custom task pane in your add-in, you should also create a UI element, such as a button, that users can click to display or hide your custom task pane. If you create a custom task pane in a Microsoft Office application that supports customizing the Ribbon, you can add a control group to the Ribbon with a button that displays or hides your custom task pane. For a walkthrough that demonstrates how to do this, see Walkthrough: Synchronizing a Custom Task Pane with a Ribbon Button.

If you create a custom task pane in a Microsoft Office application that does not support customizing the Ribbon, you can add a CommandBarButton that displays or hides your custom task pane.

You can control the size and location of a custom task pane by using properties of the CustomTaskPane object. You can make many other changes to the appearance of a custom task pane by using properties of the UserControl object that is contained in the custom task pane. For example, you can specify a background image for a custom task pane by using the BackgroundImage property of the user control.

The following table lists the changes you can make to a custom task pane by using CustomTaskPane properties.

You might want your add-in to respond when the user modifies the custom task pane. For example, if the user changes the orientation of the pane from vertical to horizontal, you might want to reposition the controls.

The following table lists the events that you can handle to respond to changes that the user makes to the custom task pane.

After you create a custom task pane, the CustomTaskPane object remains in memory as long as your add-in is running. The object remains in memory even after the user clicks the Close button (X) in the corner of the task pane.

To clean up resources used by the task pane while the add-in is still running, use the Remove or RemoveAt methods. These methods remove the specified CustomTaskPane object from the CustomTaskPanes collection, and they call the Dispose method of the object.

The Visual Studio Tools for Office runtime automatically cleans up resources used by the custom task pane when the add-in is unloaded. Do not call the Remove or RemoveAt methods in the ThisAddIn_Shutdown event handler in your project. These methods will throw an ObjectDisposedException, because the Visual Studio Tools for Office runtime cleans up resources used by the CustomTaskPane object before ThisAddIn_Shutdown is called. For more information about ThisAddIn_Shutdown, see Events in Office Projects

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:

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