Export (0) Print
Expand All

Custom Task Panes Overview

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005

    -or-

    Visual Studio Team System

    -or-

    Visual Studio 2005 Professional Edition

  • VSTO 2005 SE installed in the development environment

  • 2007 Microsoft Office system

Task panes are user interface panels that are typically docked to one side of a window in a Microsoft Office application. Almost all Microsoft Office applications include built-in task panes. 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 use Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE) to create custom task panes for the following applications:

  • Microsoft Office Excel 2007

  • Microsoft Office InfoPath 2007

  • Microsoft Office Outlook 2007

  • Microsoft Office PowerPoint 2007

  • Microsoft Office Word 2007

NoteNote

A custom task pane differs from the actions pane. Custom task panes are part of application-level add-in projects. The actions pane is part of document-level customizations for Microsoft Office Word 2003 and Microsoft Office Excel 2003. 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 normal 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 VSTO 2005 SE 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:

  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 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. For a walkthrough that demonstrates how to create a custom task pane that automates an application in the Microsoft Office system, see Walkthrough: Automating an Application from a Custom Task Pane.

Creating the User Interface

All custom task panes created by using VSTO 2005 SE 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.

If you want to automate the application from the user control, you can directly access the object model by using the static Globals class. This class provides access to the ThisAddIn object, which is the entry point into the object model of the application. For more information, see Global Access to Objects in the Project.

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.

If you use the Microsoft.Office.Tools.CustomTaskPaneCollection.Add(System.Windows.Forms.UserControl,System.String) method, your custom task pane is automatically associated with the active window in the Microsoft Office application. If you want to associate the task pane with a specific window, you can use Microsoft.Office.Tools.CustomTaskPaneCollection.Add(System.Windows.Forms.UserControl,System.String,System.Object). For more information, see Behavior of Custom Task Panes in Different Application Windows.

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.

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 that is typically in the corner of every window and application. However, there is no default way for users to display custom task panes. 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 custom Ribbon tab with a button that displays or hides your custom task pane. For more information, see Ribbon Extensibility Overview.

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 a Custom Task Pane

You can control the size or 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

Behavior of Custom Task Panes in Different Application Windows

The behavior of custom task panes in application windows differs between Microsoft Office applications.

Excel 2007 and PowerPoint 2007

When you create a custom task pane for Excel 2007 and PowerPoint 2007, the custom task pane is visible for every workbook or presentation that is open in the application. Task panes in these applications are associated with the window that hosts workbooks and presentations, and the same instance of this window is shared by all workbooks and presentations.

Word 2007 and InfoPath 2007

When you create a custom task pane for Word 2007 or InfoPath 2007, the custom task pane is visible only for a single document. Task panes in these applications are associated with the window that hosts documents, but there is a different instance of this window for every document.

To determine which document displays the custom task pane, use the appropriate Add method:

  • If you use the Microsoft.Office.Tools.CustomTaskPaneCollection.Add(System.Windows.Forms.UserControl,System.String) method, the custom task pane is visible only for the document that is active when you call the method.

  • If you use the Microsoft.Office.Tools.CustomTaskPaneCollection.Add(System.Windows.Forms.UserControl,System.String,System.Object) method, the custom task pane is visible only for the document that is hosted by the window that you specify by using the window parameter.

If you want to display a custom task pane for multiple documents, you can create a new instance of the custom task pane when the user creates a new document or opens an existing document. For example, you can create handlers for the NewDocument or DocumentOpen events in a Word 2007 add-in to create a new instance of your custom task pane that is visible with the new or opened document.

Outlook 2007

When you create a custom task pane for Outlook 2007, the custom task pane is associated with an Explorer window or an Inspector window.

To determine which window displays the custom task pane, use the appropriate Add method:

  • If you use the Microsoft.Office.Tools.CustomTaskPaneCollection.Add(System.Windows.Forms.UserControl,System.String) method, the custom task pane is visible only for the Explorer window or Inspector window that is active when you call the method.

  • If you use the Microsoft.Office.Tools.CustomTaskPaneCollection.Add(System.Windows.Forms.UserControl,System.String,System.Object) method, the custom task pane is visible only for the Explorer window or Inspector window that you specify by using the window parameter.

If you want to display a custom task pane for multiple Explorer or Inspector windows, you can create a new instance of the custom task pane when a new Explorer or Inspector window opens. For example, you can create handlers for the Microsoft.Office.Interop.Outlook.ExplorersEvents_NewExplorer or Microsoft.Office.Interop.Outlook.InspectorsEvents_NewInspector events to create a new instance of your custom task pane that is visible with the Explorer or Inspector.

Preventing Multiple Instances of a Custom Task Pane

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 Microsoft.Office.Interop.Outlook.InspectorEvents_10_Event.Close or Microsoft.Office.Interop.Outlook.ExplorerEvents_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.

See Also

Community Additions

ADD
Show:
© 2014 Microsoft