Walkthrough: Create a custom tab by using the Ribbon Designer

Applies to: Visual Studio Visual Studio for Mac

By using the Ribbon Designer, you can create a custom tab and then add and position controls on it.

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

This walkthrough illustrates the following tasks:

• Create actions panes.

• Create a custom tab.

• Hide and show actions panes by using buttons on the custom tab.

Prerequisites

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

Create an Excel workbook project

The steps for using the Ribbon Designer are almost identical for all Office applications. This example uses an Excel workbook.

To create an Excel workbook project

• Create an Excel workbook project with the name MyExcelRibbon. For more information, see How to: Create Office Projects in Visual Studio.

  Visual Studio opens the new workbook in the designer and adds the MyExcelRibbon project to Solution Explorer.

Create actions panes

Add two custom actions panes to the project. You will later add buttons that show and hide these actions panes to the custom tab.

To create actions panes

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

2. In the Add New Item dialog box, select ActionsPaneControl, and then choose Add.

   The ActionsPaneControl1.cs or ActionsPaneControl1.vb file opens in the designer.

3. From the Common Controls tab of the Toolbox, add a label to the designer surface.

4. In the Properties window, set the Text property of label1 to Actions Pane 1.

5. Repeat steps 1 through 5 to create a second actions pane and label. Set the Text property of the second label to Actions Pane 2.

Create a custom tab

One of the Office application design guidelines is that users should always have control of the Office application UI. To add this capability for the actions panes, you can add buttons that show and hide each actions pane from a custom tab on the ribbon. To create a custom tab, add a Ribbon (Visual Designer) item to the project. The designer helps you add and position controls, set control properties, and handle control events.

To create a custom tab

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

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

3. Change the name of the new ribbon to MyRibbon, and choose Add.

   The MyRibbon.cs or MyRibbon.vb file opens in the Ribbon Designer and displays a default tab and group.

4. In the Ribbon Designer, choose the default tab.

5. In the Properties window, expand the ControlId property, and then set the ControlIdType property to Custom.

6. Set the Label property to My Custom Tab.

7. In the Ribbon Designer, choose group1.

8. In the Properties window, set Label to Actions Pane Manager.

9. From the Office Ribbon Controls tab of the Toolbox, drag a button onto group1.

10. Select button1.

11. In the Properties window, set Label to Show Actions Pane 1.

12. Add a second button to group1, and set the Label property to Show Actions Pane 2.

13. From the Office Ribbon Controls tab of the Toolbox, drag a ToggleButton control onto group1.

14. Set the Label property to Hide Actions Pane.

Hide and show actions panes by using buttons on the custom tab

The last step is to add code that responds to the user. Add event handlers for the Click events of the two buttons and the Click event of the toggle button. Add code to these event handlers to enable hiding and showing the actions panes.

To hide and show actions panes by using buttons in the custom tab

1. In Solution Explorer, open the shortcut menu for MyRibbon.cs or MyRibbon.vb, and then choose View Code.

2. Add the following code to the top of the MyRibbon class. This code creates two actions pane objects.

   ActionsPaneControl1 actionsPane1 = new ActionsPaneControl1();
   ActionsPaneControl2 actionsPane2 = new ActionsPaneControl2();
   

   Dim actionsPane1 As New ActionsPaneControl1()
   Dim actionsPane2 As New ActionsPaneControl2()
   

3. Replace the MyRibbon_Load method with the following code. This code adds the actions pane objects to the Controls collection and hides the objects from view. The Visual C# code also attaches delegates to several ribbon control events.

   private void MyRibbon_Load(object sender, RibbonUIEventArgs e)
   {
       Globals.ThisWorkbook.ActionsPane.Controls.Add(actionsPane1);
       Globals.ThisWorkbook.ActionsPane.Controls.Add(actionsPane2);
       actionsPane1.Hide();
       actionsPane2.Hide();
       Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = false;
   
       this.button1.Click += new Microsoft.Office.Tools.Ribbon.RibbonControlEventHandler(
           this.button1_Click);
       this.button2.Click += new Microsoft.Office.Tools.Ribbon.RibbonControlEventHandler(
           this.button2_Click);
       this.toggleButton1.Click += new Microsoft.Office.Tools.Ribbon.RibbonControlEventHandler(
           this.toggleButton1_Click);
   
   
   }
   

   Private Sub MyRibbon_Load(ByVal sender As System.Object, ByVal e As Microsoft.Office.Tools.Ribbon.RibbonUIEventArgs) Handles MyBase.Load
       Globals.ThisWorkbook.ActionsPane.Controls.Add(actionsPane1)
       Globals.ThisWorkbook.ActionsPane.Controls.Add(actionsPane2)
       actionsPane1.Hide()
       actionsPane2.Hide()
       Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = False
   End Sub
   

4. Add the following three event handler methods to the MyRibbon class. These methods handle the Click events of the two buttons and the Click event of the toggle button. The event handlers for button1 and button2 show alternate actions panes. The event handler for toggleButton1 shows and hides the active actions pane.

   private void button1_Click(object sender, RibbonControlEventArgs e)
   {
       Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = true;
       actionsPane2.Hide();
       actionsPane1.Show();
       toggleButton1.Checked = false;
   }
   
   private void button2_Click(object sender, RibbonControlEventArgs e)
   {
       Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = true;
       actionsPane1.Hide();
       actionsPane2.Show();
       toggleButton1.Checked = false;
   
   }
   
   private void toggleButton1_Click(object sender, RibbonControlEventArgs e)
   {
       if (toggleButton1.Checked == true)
       {
           Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = false;
       }
       else
       {
           Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = true;
       }
   
   }
   

   Private Sub Button1_Click(ByVal sender As System.Object, _
       ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
           Handles Button1.Click
       Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = True
       actionsPane2.Hide()
       actionsPane1.Show()
       ToggleButton1.Checked = False
   End Sub
   
   Private Sub Button2_Click(ByVal sender As System.Object, _
       ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
           Handles Button2.Click
   
       Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = True
       actionsPane1.Hide()
       actionsPane2.Show()
       ToggleButton1.Checked = False
   
   End Sub
   
   
   Private Sub ToggleButton1_Click(ByVal sender As System.Object, _
       ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) _
           Handles ToggleButton1.Click
   
       If ToggleButton1.Checked Then
           Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = False
       Else
           Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = True
       End If
   
   End Sub
   

Test the custom Tab

When you run the project, Excel starts, and the My Custom Tab tab appears on the ribbon. Choose the buttons on My Custom Tab to show and hide the actions panes.

To test the custom tab

1. Press F5 to run your project.

2. Choose the My Custom Tab tab.

3. In the Custom Actions Pane Manager group, choose Show Actions Pane 1.

   The actions pane appears and displays the label Actions Pane 1.

4. Choose Show Actions Pane 2.

   The actions pane appears and displays the label Actions Pane 2.

5. Choose Hide Actions Pane.

   The actions panes are no longer visible.

Next steps

You can learn more about how to customize the Office UI from these topics:

• Add context-based UI to any document-level customization. For more information, see Actions pane overview.

• Extend a standard or custom Microsoft Office Outlook form. For more information, see Walkthrough: Design an Outlook form region.

See also

• Access the ribbon at run time
• Ribbon overview
• Ribbon Designer
• Customize a ribbon for Outlook
• How to: Get started customizing the ribbon
• How to: Change the position of a tab on the ribbon
• How to: Customize a built-in tab
• How to: Add controls to the backstage view
• Ribbon object model overview