Walkthrough: Synchronizing a Custom Task Pane with a Ribbon Button
This walkthrough demonstrates how to create a custom task pane that users can hide or display by clicking a toggle button on the Ribbon. You should always create a user interface (UI) element, such as a button, that users can click to display or hide your custom task pane, because Microsoft Office applications do not provide a default way for users to show or hide custom task panes.
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.
Although this walkthrough uses Excel specifically, the concepts demonstrated by the walkthrough are applicable to any applications that are listed above.
This walkthrough illustrates the following tasks:
Designing the UI of the custom task pane.
Adding a toggle button to the Ribbon.
Synchronizing the toggle button with the custom task pane.
You need the following components to complete this walkthrough:
An edition of Visual Studio that includes the Microsoft Office developer tools. For more information, see Configuring a Computer to Develop Office Solutions.
Microsoft Excel or Microsoft Excel 2013.
In this step, you will create an VSTO Add-in project for Excel.
Create an Excel Add-in project with the name SynchronizeTaskPaneAndRibbon, using the Excel Add-in project template. For more information, see How to: Create Office Projects in Visual Studio.
Visual Studio opens the ThisAddIn.cs or ThisAddIn.vb code file and adds the SynchronizeTaskPaneAndRibbon project to Solution Explorer.
One of the Office application design guidelines is that users should always have control of the Office application UI. To enable users to control the custom task pane, you can add a Ribbon toggle button that shows and hides the task pane. To create a toggle button, add a Ribbon (Visual Designer) item to the project. The designer helps you add and position controls, set control properties, and handle control events. For more information, see Ribbon Designer.
On the Project menu, click Add New Item.
In the Add New Item dialog box, select Ribbon (Visual Designer).
Change the name of the new Ribbon to ManageTaskPaneRibbon, and click Add.
The ManageTaskPaneRibbon.cs or ManageTaskPaneRibbon.vb file opens in the Ribbon Designer and displays a default tab and group.
In the Ribbon Designer, click group1.
In the Properties window, set the Label property to Task Pane Manager.
From the Office Ribbon Controls tab of the Toolbox, drag a ToggleButton onto the Task Pane Manager group.
In the Properties window, set the Label property to Show Task Pane.
There is no visual designer for custom task panes, but you can design a user control with the layout you want. Later in this walkthrough, you will add the user control to the custom task pane.
On the Project menu, click Add User Control.
In the Add New Item dialog box, change the name of the user control to TaskPaneControl, and click Add.
The user control opens in the designer.
From the Common Controls tab of the Toolbox, drag a TextBox control to the user control.
To create the custom task pane when the VSTO Add-in starts, add the user control to the task pane in the Startup event handler of the VSTO Add-in. By default, the custom task pane will not be visible. Later in this walkthrough, you will add code that will display or hide the task pane when the user clicks the toggle button you added to the Ribbon.
In Solution Explorer, expand Excel.
Right-click ThisAddIn.cs or ThisAddIn.vb and click View Code.
Add the following code to the
ThisAddInclass. This code declares an instance of
TaskPaneControlas a member of
ThisAddIn_Startupevent handler with the following code. This code adds the
TaskPaneControlobject to the
CustomTaskPanesfield, but it does not display the custom task pane (by default, the Visible property of the CustomTaskPane class is false). The Visual C# code also attaches an event handler to the VisibleChanged event.
Add the following method to the
ThisAddInclass. This method handles the VisibleChanged event. When the user closes the task pane by clicking the Close button (X), this method updates the state of the toggle button on the Ribbon.
Add the following property to the
ThisAddInclass. This property exposes the private
myCustomTaskPane1object to other classes. Later in this walkthrough, you will add code to the
MyRibbonclass that uses this property.
The last step is to add code that displays or hides the custom task pane when the user clicks the toggle button on the Ribbon.
In the Ribbon Designer, double-click the Show Task Pane toggle button.
Visual Studio automatically generates an event handler named
toggleButton1_Click, which handles the Click event of the toggle button. Visual Studio also opens the MyRibbon.cs or MyRibbon.vb file in the Code Editor.
toggleButton1_Clickevent handler with the following code. When the user clicks the toggle button, this code displays or hides the custom task pane, depending on whether the toggle button is pressed or not pressed.
When you run the project, Excel opens without displaying the custom task pane. Click the toggle button on the Ribbon to test the code.
Press F5 to run your project.
Confirm that Excel opens, and the Add-Ins tab appears on the Ribbon.
Click the Add-Ins tab on the Ribbon.
In the Task Pane Manager group, click the Show Task Pane toggle button.
Verify that the task pane is alternately displayed and hidden when you click the toggle button.
When the task pane is visible, click the Close button (X) in the corner of the task pane.
Verify that the toggle button appears to be not pressed.
You can learn more about how to create custom task panes from these topics:
Create a custom task pane in an VSTO Add-in for a different application. For more information about the applications that support custom task panes, see Custom Task Panes.
Automate an application from a custom task pane. For more information, see Walkthrough: Automating an Application from a Custom Task Pane.
Create a custom task pane for every e-mail message that is opened in Outlook. For more information, see Walkthrough: Displaying Custom Task Panes with E-Mail Messages in Outlook.
Custom Task Panes
How to: Add a Custom Task Pane to an Application
Walkthrough: Automating an Application from a Custom Task Pane
Walkthrough: Displaying Custom Task Panes with E-Mail Messages in Outlook