Export (0) Print
Expand All

Actions Pane 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

  • Microsoft Office 2003

Microsoft Office 2003 introduced the smart documents programmability feature, which enables you to create custom Document Actions task panes that are attached to Microsoft Office Word 2003 documents and Microsoft Office Excel 2003 workbooks. For example, you can use a Document Actions task pane to provide contextual assistance or business logic depending on the position of the cursor in an XML mapped document hosted in Word or Excel. Microsoft Visual Studio 2005 Tools for the Microsoft Office System provides an implementation of a generic actions pane that helps to simplify the developer experience by eliminating the need for XML expansion packs, providing support for Windows Forms controls, and removing the requirement of registration when deploying such solutions.

With the actions pane, you can now provide a context-based display of information that is not reliant upon XML element mappings on the document. Because Windows Forms controls are supported, it is now possible to bind the same data source to controls on the actions pane and controls on the document by writing the same data binding code.

NoteNote

The actions pane differs from custom task panes. Custom task panes are associated with the application, not a specific document. You can add custom task panes to application-level add-ins for the 2007 Microsoft Office system. For more information, see Custom Task Panes Overview.

Actions Pane Features

The ActionsPane is a customizable task pane that is hosted inside the Office task pane along with other built-in task panes such as the XML Source task pane in Excel or the Styles and Formatting task pane in Word. To the end user, an actions pane is much like a smart document task pane. From a developer's perspective, however, the actions pane differs from a smart document solution in the following ways:

  • The programming model is simplified.

    The ActionsPane object is available directly in your Visual Studio Tools for Office project. You simply add controls to the actions pane using ActionsPane.Controls.Add(controlInstance) where controlInstance is an instance of the control. You can create a user control and add it to the actions pane in the same way you create a user control to add to a Windows Form.

  • The actions pane is a Windows Forms control, as well as a container for other managed Windows Forms controls.

    The actions pane can contain the same Windows Forms controls that are available to Windows Forms. Developers can use the familiar Windows Forms designer to design the components for their actions pane.

  • XML expansion pack creation is not required.

    Smart document solutions required the use of an XML expansion pack. The XML expansion pack is the group of files that provide the logic needed for a smart document, such as XML schemas and Extensible Stylesheet Language Transforms (XSLTs). Visual Studio Tools for Office automatically attaches any necessary schemas and expansion packs and updates the registry settings.

  • XML mapping is not required.

    While you can map XML elements to your document and program the actions pane to show and hide controls according to cursor location within the XML nodes, XML mapping is not required. You can code against the actions pane to respond to any event such as host control, application, and document events.

Actions Pane Technology

The actions pane technology builds upon the underlying smart document technology. Because a smart document requires an expansion pack, which consists of a combination of registering COM components, schemas, and a manifest, the actions pane provides a generic schema that is used by all solutions.

Actions Pane Runtime Component

The Visual Studio Tools for Office runtime installs a generic expansion pack named Microsoft Actions Pane that is automatically attached to a document that utilizes the actions pane feature. This expansion pack is located in the XML Expansion Pack tab of the Templates and Add-ins dialog box in Word, and the XML Expansion Pack dialog box in Excel.

The actions pane schema contains no elements or attributes, but it is automatically added to each project to meet the smart document requirement. If a user manually removes the schema from the document, it is automatically added again the next time the project runs.

Actions Pane Advantages

Controls on an actions pane have some advantages over controls on a standard Windows Form or a Word or Excel document.

If you place controls such as a Button on a worksheet, you can set properties to hide the control when you print the document. However, controls on Word documents cannot be hidden. For more information, see How to: Hide Controls on Worksheets when Printing. Controls on the actions pane do not appear within the document when it is printed.

Any Windows Forms control can be placed on the actions pane. There are limitations to the type of Windows Forms controls that can be placed directly on a document. For more information, see Limitations of Windows Forms Controls on Office Documents.

Windows Forms are displayed on top of the document, often hiding the text and forcing user interaction. The actions pane displays the controls but does not obstruct the view of the document. Users can easily switch from interacting with the controls to working in the document.

Displaying Controls on the Actions Pane

You can display controls on the actions pane by adding Windows Forms controls to it. Typically, you add Windows Forms controls to a user control, and then add the user control to the actions pane. The Add New Item dialog box contains an actions pane control that is a user control for the actions pane; you can use this control or a user control with equal results. The ActionsPane object is always available to your solution, but it becomes visible at run time as soon as you explicitly add controls to it. After the actions pane is displayed, you can dynamically add or remove controls in response to the user's actions. For more information, see How to: Add an Actions Pane to Word Documents.

Typically, you add the code to display the actions pane in the Startup event handler of ThisDocument or ThisWorkbook so that the actions pane is visible when the user first opens the document. However, you might want to display the actions pane only in response to a user's action in the document. For example, you might add the code to the Click event of a control on the document.

If the user saves the document while the actions pane is visible, the actions pane is visible each time the document is opened, whether or not the actions pane contains any controls. You should call the Clear method in the Startup event handler of ThisDocument or ThisWorkbook to ensure that the actions pane is unavailable when the document is opened.

Hiding the Actions Pane

Although the ActionsPane has a Hide method and a Visible property, you cannot remove the actions pane from the user interface by using any members of the ActionsPane class itself. Calling the Hide method or setting the Microsoft.Office.Tools.ActionsPane.Visible property to false hides only the controls on the actions pane; it does not hide the task pane. If you want to hide the task pane, set the Microsoft.Office.Core.CommandBar.Visible property of the command bar that represents the task pane to false.

Application.CommandBars["Task Pane"].Visible = false;

Programming Actions Pane Events

You can add multiple user controls to the actions pane and then write code to respond to events on the document by showing and hiding the user controls. You can also use the programmable events on the actions pane controls to respond to user interactions with the controls. Mapping XML schema elements to your document enables you to show certain user controls in the actions pane whenever the insertion point is placed inside one of the XML elements. For more information, see Walkthrough: Changing the Actions Pane According to User Context, How to: Map Schemas to Word Documents Inside Visual Studio, and How to: Map Schemas to Worksheets Inside Visual Studio.

You can also write code to respond to the events of any object, including host control, application, or document events. For more information see Walkthrough: Programming Against Events of a NamedRange Control.

Binding Data to the Actions Pane Controls

The controls on the actions pane have the same data binding capabilities as controls on Windows Forms. You can bind the controls to data sources such as data sets, typed data sets, and XML. For more information, see Data Binding and Windows Forms.

You can bind controls on the actions pane and controls on the document to the same dataset. For example, you can create master/detail relation between the controls on the actions pane and the controls on the Worksheet. For more information, see Walkthrough: Binding Data to Controls on an Excel Actions Pane.

Validating Data in Actions Pane Controls

If you display a message box in the Validating event handler of a control on the actions pane, the event might be raised a second time when focus moves from the control to the message box. To prevent this issue, you should use an ErrorProvider control to display any validation error messages.

User Control Stacking Order

If you are using multiple user controls, you can write code to properly stack the user controls on the actions pane whether it is docked vertically or horizontally. You can set the stacking order of the user controls on the actions pane by using the StackStyle enumeration of the StackOrder property. For more information, see How to: Manage Control Layout on Actions Panes

The StackOrder property can take the following enumerations:

Stacking Style Definition

FromBottom

Stack from the bottom of the actions pane.

FromLeft

Stack from the left of the actions pane.

FromRight

Stack from the right of the actions pane.

FromTop

Stack from the top of the actions pane.

None

No stacking order defined; order is controlled by the developer.

The following code sets the StackOrder property to stack the user controls from the top of the actions pane.

this.ActionsPane.StackOrder = Microsoft.Office.Tools.StackStyle.FromTop;

Anchoring Controls

If the user resizes the actions pane at run time, the controls can resize with the actions pane. You can use the Anchor property of a Windows Forms control to anchor controls to the actions pane. You can also anchor the Windows Forms controls onto the user control in the same manner. For more information, see How to: Anchor Controls on Windows Forms.

Resizing the Actions Pane

You cannot directly change the size of an ActionsPane because the ActionsPane is embedded in the task pane. However, you can programmatically change the width of the task pane by setting the Width property of the CommandBar that represents the task pane. You can change the height of the task pane if it is docked horizontally or is floating. Programmatically resizing the task pane is generally not recommended because the user should be able to select the task pane size that best suits his or her needs. However, if you must resize the width of the task pane, you could use the following code to achieve this task.

this.CommandBars["Task Pane"].Width = 200;

Repositioning the Actions Pane

You cannot directly reposition the ActionsPane because it is embedded in the task pane. However, you can programmatically move the task pane by setting the Position property of the CommandBar that represents the task pane. Programmatically repositioning the task pane is generally not recommended because the user should be able to choose the task pane position on the screen that best suits his or her needs. However, if you must move the task pane to a particular position, you could use the following code to achieve this task.

this.CommandBars["Task Pane"].Position =
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft;

NoteNote

End users can manually reposition the task pane at any time. There is no way to ensure that the task pane will remain docked at the position you indicate programmatically. You should check for orientation changes and ensure that the controls on the actions pane are stacked in the correct direction. For more information, see How to: Manage Control Layout on Actions Panes.

Setting the Top and Left properties of the ActionsPane does not change its position because the ActionsPane object is embedded in the task pane. If the task pane is not docked, you can set the Top and Left properties of the CommandBar that represents the task pane. The following code moves an undocked task pane to the upper-left corner of the document.

if (this.CommandBars["Task Pane"].Position == 
    Microsoft.Office.Core.MsoBarPosition.msoBarLeft)
{
    this.CommandBars["Task Pane"].Top = 0;
    this.CommandBars["Task Pane"].Left = 0;
}

See Also

Community Additions

ADD
Show:
© 2014 Microsoft