Custom task panes

Applies to: Visual Studio Visual Studio for Mac

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.

Applies to: The information in this topic applies to VSTO Add-in projects for Outlook. For more information, see Features available by Office application and project type.

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

Create a custom task pane

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

1. Create a user interface for your custom task pane by adding Windows Forms controls to a UserControl object.

2. Instantiate the custom task pane by passing the user control to the CustomTaskPaneCollection object in your VSTO 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 more information, see How to: Add a custom task pane to an application.

Create the user interface

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.

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

Control 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 Add method.

• To associate the task pane with a document that is hosted by a specified window, use the Add method.

  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 Manage custom task panes in application windows.

Access 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 Program VSTO Add-ins. For a walkthrough that demonstrates how to automate an application from a custom task pane, see Walkthrough: Automatic an application from a custom task pane. For more information about the Globals class, see Global access to objects in Office projects.

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

Make 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 VSTO 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: Synchronize 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.

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

Program custom task pane events

You might want your VSTO 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.

Clean up resources used by the task pane

After you create a custom task pane, the CustomTaskPane object remains in memory as long as your VSTO 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 VSTO 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 VSTO 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.

Manage 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, InfoPath, and PowerPoint

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

• NewExplorer

• Activate

• Close

• Deactivate

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

• NewInspector

• Activate

• Close

• Deactivate

Prevent 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 Close or 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

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.

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

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

PowerPoint events

To monitor the state of document windows 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

See also

• How to: Add a custom task pane to an application
• Walkthrough: Automate an application from a custom task pane
• Walkthrough: Synchronize a custom task pane with a Ribbon button
• Walkthrough: Display custom task panes with email messages in Outlook