Walkthrough: Synchronize a custom task pane with a Ribbon button
Applies to: Visual Studio Visual Studio for Mac Visual Studio Code
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.
Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Personalize the Visual Studio IDE.
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 Configure a computer to develop Office solutions.
Microsoft Excel or Microsoft Excel 2013 .
Create the Add-in project
In this step, you will create a VSTO Add-in project for Excel.
To create a new project
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.
Add a toggle button to the ribbon
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.
To add a toggle button to the ribbon
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.
Design the user interface of the custom 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.
To design the user interface of 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.
Create the custom task pane
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.
To create the custom task pane
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
taskPaneValueobject to other classes. Later in this walkthrough, you will add code to the
MyRibbonclass that uses this property.
Hide and show the custom task pane by using the toggle button
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.
To display and hide the custom task pane by using the toggle button
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.
Test the Add-in
When you run the project, Excel opens without displaying the custom task pane. Click the toggle button on the ribbon to test the code.
To test your VSTO Add-in
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 a 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: Automate 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: Display custom task panes with email messages in Outlook.