Muokkaa

Jaa

Actions pane overview

  • Artikkeli

An actions pane is a customizable Document Actions task pane that is attached to a specific Microsoft Office Word document or Microsoft Office Excel workbook. The actions pane 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. You can use Windows Forms controls or WPF controls to design the actions pane user interface.

Applies to: The information in this topic applies to document-level projects for Excel and Word. For more information, see Features available by Office application and project type.

You can create an actions pane only in a document-level customization for Word or Excel. You cannot create an actions pane in a VSTO Add-in. For more information, see Features available by Office application and project type.

Note

The actions pane differs from custom task panes. Custom task panes are associated with the application, not a specific document. You can create custom task panes in VSTO Add-ins for some Microsoft Office applications. For more information, see Custom task panes.

Display the actions pane

The actions pane is represented by the ActionsPane class. When you create a document-level project, an instance of this class is available to your code by using the ActionsPane field of the ThisWorkbook (for Excel) or ThisDocument (for Word) class in your project. To display the actions pane, add a Windows Forms control to the Controls property of the ActionsPane field. The following code example adds a control named actions to the actions pane.

this.ActionsPane.Controls.Add(actions);

The actions pane becomes visible at run time as soon as you explicitly add a control to it. After the actions pane is displayed, you can dynamically add or remove controls in response to the user's actions. 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.

Add multiple controls to the actions pane

When you add multiple controls to the actions pane, you should group the controls in a user control and then add the user control to the Controls property. This process includes the following steps:

  1. Create the user interface (UI) of the actions pane by adding an Actions Pane Control or User Control item to your project. Both of these items include a custom Windows Forms UserControl class. The Actions Pane Control and User Control items are equivalent; the only difference is their name.

  2. Add Windows Forms controls to the UserControl by using the designer, or by writing code.

    Note

    You can also add WPF controls to the actions pane by adding a WPF UserControl to the Windows Forms UserControl. For more information, see Use WPF controls in Office solutions.

  3. Add an instance of the custom user control to the controls that are contained in the ActionsPane field of the ThisWorkbook (for Excel) or ThisDocument (for Word) class in your project.

    For examples that demonstrate this process in more detail, see How to: Add an actions pane to Word documents or Excel workbooks.

Hide the actions pane

Although the ActionsPane class 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 Visible property to false hides only the controls on the actions pane; it does not hide the task pane.

To hide the task pane in your solution, you have several options:

  • For Word, set the Visible property of the TaskPane object that represents the Document Actions task pane to false. The following code example is intended to be run from the ThisDocument class in your project.

    this.Application.TaskPanes[Word.WdTaskPanes.wdTaskPaneDocumentActions].Visible = false;

  • For Excel, set the DisplayDocumentActionTaskPane property of the Application object to false. The following code example is intended to be run from the ThisWorkbook class in your project.

    this.Application.DisplayDocumentActionTaskPane = false;

  • For Word or Excel, you can alternatively set the Visible property of the command bar that represents the task pane to false. The following code example is intended to be run from the ThisDocument or ThisWorkbook class in your project.

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

Clear the actions pane when the document is opened

When a user saves the document while the actions pane is visible, the actions pane is visible every time the document is opened, whether or not the actions pane contains any controls. If you want to control when it appears, call the Clear method of the ActionsPane field in the Startup event handler of ThisDocument or ThisWorkbook to ensure that the actions pane is not visible when the document is opened.

Determine when the actions pane is closed

There is no event that is raised when the actions pane is closed. Although the ActionsPane class has a VisibleChanged event, this event is not raised when the end user closes the actions pane. Instead, this event is raised when the controls on the actions pane are hidden by calling the Hide method or by setting the Visible property to false.

When the user closes the actions pane, the user can display it again by performing one of the following procedures in the user interface (UI) of the application.

To display the actions pane by using the UI of Word or Excel

  1. On the Ribbon, click the View tab.

  2. In the Show/Hide group, click the Document Actions toggle button.

Program 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. If you map XML schema elements to your document, you can show certain user controls in the actions pane whenever the insertion point is inside one of the XML elements. For more information, see 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: Program against events of a NamedRange control.

Bind data to controls on the actions pane

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 a master/detail relation between the controls on the actions pane and the controls on the worksheet. For more information, see Walkthrough: Bind data to controls on an Excel actions pane.

Validate 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, 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 StackStyle enumeration values.

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;

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

Resize 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 not recommended because the user should be able to select the task pane size that best suits their 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;

Reposition 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 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;

Note

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. However, you can 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 doesn't 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.msoBarFloating)
{
    this.CommandBars["Task Pane"].Top = 0;
    this.CommandBars["Task Pane"].Left = 0;
}

Related content