Custom Task Panes Overview

Article
11/16/2012

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and Microsoft Office applications. Project type Application-level projects Microsoft Office application Excel 2007 InfoPath 2007 Outlook 2007 PowerPoint 2007 Word 2007 For more information, see Features Available by Application and Project Type.

The information in this topic applies only to the specified Visual Studio Tools for Office projects and Microsoft Office applications.

Project type

Application-level projects

Microsoft Office application

Excel 2007
InfoPath 2007
Outlook 2007
PowerPoint 2007
Word 2007

For more information, see Features Available by Application and Project Type.

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.

You can create a custom task pane only in an application-level add-in for one of the Microsoft Office applications listed above. You cannot create a custom task pane in a document-level customization. For more information, see Features Available by Application and Project Type.

Note

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.

Benefits of Custom Task Panes

Custom task panes let you integrate your features into a familiar user interface. You can create a custom task pane quickly by using Visual Studio tools.

Familiar User Interface

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.

Windows Forms Support

The user interface of a custom task pane that you create by using Visual Studio Tools for Office 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.

Creating a Custom Task Pane

You can create a basic custom task pane in two steps:

Create a user interface for your custom task pane by adding Windows Forms controls to a UserControl object.
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.

For a step-by-step procedure, see How to: Add a Custom Task Pane to an Application.

Creating the User Interface

All custom task panes that are created by using Visual Studio Tools for Office 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.

Instantiating the Custom 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.

myUserControl1 = New MyUserControl
myCustomTaskPane = Me.CustomTaskPanes.Add(myUserControl1, "My Task Pane")
myCustomTaskPane.Visible = True

myUserControl1 = new MyUserControl();
myCustomTaskPane = this.CustomTaskPanes.Add(myUserControl1, "My Task Pane");
myCustomTaskPane.Visible = true;

The Add methods return a new CustomTaskPane object. You can use this object to modify the appearance of the task pane and to respond to user events.

Controlling the Task Pane in Multiple Windows

Custom task panes 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.

To determine which window displays the custom task pane, use the appropriate Add method overload when you create the task pane:

To associate the task pane with the active window, use the CustomTaskPaneCollection.Add(UserControl, String) method.
To associate the task pane with a document that is hosted by a specified window, use the CustomTaskPaneCollection.Add(UserControl, String, Object) method.

Outlook, Word, and InfoPath 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 Multiple Application Windows.

Accessing the Application from the Task Pane

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.

For more information about the Application field of the ThisAddIn object, see Programming Application-Level Add-Ins. For a walkthrough that demonstrates how to automate an application from a custom task pane, see Walkthrough: Automating an Application from a Custom Task Pane. For more information about the Globals class, see Global Access to Objects in Visual Studio Tools for Office Projects.

Managing the User Interface of the Task Pane

After you create the task pane, you can use properties and events of the CustomTaskPane object to control the user interface of the task pane and to respond when the user changes the task pane.

Making the Custom Task Pane Visible

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.

Modifying the Appearance of the 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.

Task	Property
To change the size of the task pane	Height Width
To change the location of the task pane	DockPosition
To hide the task pane or make it visible	Visible
To prevent the user from changing the location of the task pane	DockPositionRestrict

Programming Custom Task Pane Events

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.

Task	Event
To respond when the user changes the location of the task pane.	DockPositionChanged
To respond when the user hides the task pane or makes it visible.	VisibleChanged

Cleaning Up Resources Used by the 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 Visual Studio Tools for Office Project Events.