Walkthrough: Synchronize a custom task pane with a Ribbon button

  • Articolo

Applies to: yesVisual Studio noVisual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

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.

Note

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.

Prerequisites

You need the following components to complete this walkthrough:

Create the Add-in project

In this step, you will create a VSTO Add-in project for Excel.

To create a new project

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

  1. On the Project menu, click Add New Item.

  2. In the Add New Item dialog box, select Ribbon (Visual Designer).

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

  4. In the Ribbon Designer, click group1.

  5. In the Properties window, set the Label property to Task Pane Manager.

  6. From the Office Ribbon Controls tab of the Toolbox, drag a ToggleButton onto the Task Pane Manager group.

  7. Click toggleButton1.

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

  1. On the Project menu, click Add User Control.

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

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

  1. In Solution Explorer, expand Excel.

  2. Right-click ThisAddIn.cs or ThisAddIn.vb and click View Code.

  3. Add the following code to the ThisAddIn class. This code declares an instance of TaskPaneControl as a member of ThisAddIn.

    private TaskPaneControl taskPaneControl1;
private Microsoft.Office.Tools.CustomTaskPane taskPaneValue;

    Private taskPaneControl1 As TaskPaneControl
Private WithEvents taskPaneValue As Microsoft.Office.Tools.CustomTaskPane

  4. Replace the ThisAddIn_Startup event handler with the following code. This code adds the TaskPaneControl object to the CustomTaskPanes field, 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.

    private void ThisAddIn_Startup(object sender, System.EventArgs e)
{
    taskPaneControl1 = new TaskPaneControl();
    taskPaneValue = this.CustomTaskPanes.Add(
        taskPaneControl1, "MyCustomTaskPane");
    taskPaneValue.VisibleChanged +=
        new EventHandler(taskPaneValue_VisibleChanged);
}

    Private Sub ThisAddIn_Startup(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles Me.Startup

    taskPaneControl1 = New TaskPaneControl()
    taskPaneValue = Me.CustomTaskPanes.Add( _
        taskPaneControl1, "MyCustomTaskPane")
End Sub

  5. Add the following method to the ThisAddIn class. 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.

    private void taskPaneValue_VisibleChanged(object sender, System.EventArgs e)
{
    Globals.Ribbons.ManageTaskPaneRibbon.toggleButton1.Checked = 
        taskPaneValue.Visible;
}

    Private Sub taskPaneValue_VisibleChanged(ByVal sender As Object, _
    ByVal e As System.EventArgs) Handles taskPaneValue.VisibleChanged

    Globals.Ribbons.ManageTaskPaneRibbon.ToggleButton1.Checked = taskPaneValue.Visible
End Sub

  6. Add the following property to the ThisAddIn class. This property exposes the private taskPaneValue object to other classes. Later in this walkthrough, you will add code to the MyRibbon class that uses this property.

    public Microsoft.Office.Tools.CustomTaskPane TaskPane
{
    get
    {
        return taskPaneValue;
    }
}

    Public ReadOnly Property TaskPane() As Microsoft.Office.Tools.CustomTaskPane
    Get
        Return taskPaneValue
    End Get
End 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

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

  2. Replace the toggleButton1_Click event 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.

    Private Sub ToggleButton1_Click(ByVal sender As System.Object, _
    ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) Handles ToggleButton1.Click

    Globals.ThisAddIn.TaskPane.Visible = _
        TryCast(sender, Microsoft.Office.Tools.Ribbon.RibbonToggleButton).Checked
End Sub

    private void toggleButton1_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisAddIn.TaskPane.Visible = ((RibbonToggleButton)sender).Checked;
}

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

  1. Press F5 to run your project.

    Confirm that Excel opens, and the Add-Ins tab appears on the ribbon.

  2. Click the Add-Ins tab on the ribbon.

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

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

Next steps

You can learn more about how to create custom task panes from these topics:

See also