Walkthrough: Creating a Custom Tab by Using the Ribbon Designer

Walkthrough: Creating a Custom Tab ...

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Microsoft Visual Studio 2010/.NET Framework 4.0

Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0)

Walkthrough: Creating a Custom Tab by Using the Ribbon Designer

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Document-level projects Application-level projects Microsoft Office version Excel 2007 Word 2007 Outlook 2007 PowerPoint 2007 For more information, see Features Available by Application and Project Type.

Applies to

The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office.

Project type

Document-level projects
Application-level projects

Microsoft Office version

Excel 2007
Word 2007
Outlook 2007
PowerPoint 2007

For more information, see Features Available by Application and Project Type.

This walkthrough demonstrates how to create a custom Ribbon tab by using the Ribbon Designer. You can use the Ribbon Designer to add and position controls on the custom tab.

This walkthrough illustrates the following tasks:

Creating actions panes.
Creating a custom tab.
Hiding and showing actions panes by using buttons on the custom tab.

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 Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

Visual Studio Tools for Office (an optional component of Visual Studio 2008 Professional and Visual Studio Team System).
Microsoft Office Excel 2007.

Visual Studio Tools for Office is installed by default with the listed versions of Visual Studio. To check whether it is installed, see Installing Visual Studio Tools for Office.

link to video For a video version of this topic, see Video How to: Creating a Custom Tab by Using the Ribbon Designer. For a related video demonstration, see How Do I: Use the Ribbon Designer to Customize the Ribbon in Excel?.

Creating 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 2007 workbook project with the name MyExcelRibbon. For more information, see How to: Create Visual Studio Tools for Office Projects.
Visual Studio opens the new workbook in the designer and adds the MyExcelRibbon project to Solution Explorer.

Creating Actions Panes

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

To create actions panes

On the Project menu, click Add New Item.
In the Add New Item dialog box, select ActionsPaneControl, and then click Add.
The ActionsPaneControl1.cs or ActionsPaneControl1.vb file opens in the designer.
From the Common Controls tab of the Toolbox, add a label to the designer surface.
In the Properties window, set the Text property of label1 to Actions Pane 1.
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.

Creating 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

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 MyRibbon, and click Add.
The MyRibbon.cs or MyRibbon.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 Label to Actions Pane Manager.
From the Office Ribbon Controls tab of the Toolbox, drag a button onto group1.
Click button1 to select it.
In the Properties window, set Label to Show Actions Pane 1.
Add a second button to group1, and set the Label property to Show Actions Pane 2.
From the Office Ribbon Controls tab of the Toolbox, drag a ToggleButton control onto group1.
Set the Label property to Hide Actions Pane.

Hiding and Showing 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 that hide and show the actions panes.

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

In Solution Explorer, right-click MyRibbon.cs or MyRibbon.vb, and then click View Code.

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

Visual Basic

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

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

In C#, you must add the following event handlers to the constructor. For information about creating event handlers, see How to: Create Event Handlers in Visual Studio Tools for Office.

this.button1.Click += new System.EventHandler
    <Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>
        (this.button1_Click);
this.button2.Click += new System.EventHandler
    <Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>
        (this.button2_Click);
this.toggleButton1.Click += new System.EventHandler
    <Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs>
        (this.toggleButton1_Click);
this.Load += new System.EventHandler
    <Microsoft.Office.Tools.Ribbon.RibbonUIEventArgs>
        (this.MyRibbon_Load);

Add the following code to the MyRibbon_Load event. This code adds the actions pane objects to the actions pane Microsoft.Office.Tools.ActionsPane.Controls collection and hides the objects from view.

Visual Basic

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

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

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.

Visual Basic

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()
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()

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

private void button1_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = true;
    actionsPane2.Hide();
    actionsPane1.Show();
}

private void button2_Click(object sender, RibbonControlEventArgs e)
{
    Globals.ThisWorkbook.Application.DisplayDocumentActionTaskPane = true;
    actionsPane1.Hide();
    actionsPane2.Show();

}

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

}

Testing the Custom Tab

When you run the project, Excel starts, The Add-Ins tab appears on the Ribbon. Click the buttons on Add-Ins to show and hide the actions panes.

To test the custom tab

Press F5 to run your project.
Click the Add-Ins tab.
In the Custom Actions Pane Manager group, click Show Actions Pane 1.
The actions pane appears and displays the label Actions Pane 1.
Click Show Actions Pane 2.
The actions pane appears and displays the label Actions Pane 2.
Click 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: Designing an Outlook Form Region.

To create an Excel workbook project

To create actions panes

To create a custom tab

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

To test the custom tab

Tasks

Concepts

Other Resources