Share via


Ribbon Overview

The 2007 Microsoft Office system introduced a user interface (UI) element that is named the Ribbon. The Ribbon is a way to organize related commands so that they are easier to find. Commands appear as controls on the Ribbon. Controls are organized into groups along a horizontal strip at the top edge of an application window. Related groups are organized on tabs.

Most of the features that were accessed by using menus and toolbars in earlier versions of the Microsoft Office system can now be accessed by using the Ribbon. For more information, see the technical article Developer Overview of the User Interface for the 2007 Microsoft Office System.

Applies to: The information in this topic applies to document-level projects and application-level projects for the following applications: Excel 2007 and Excel 2010; InfoPath 2010; Outlook 2007 and Outlook 2010; PowerPoint 2007 and PowerPoint 2010; Project 2010; Visio 2010; Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.

Customizing the Microsoft Office Ribbon

To customize the Ribbon, add one of the following Ribbon items to your Office project:

  • Ribbon (Visual Designer)

  • Ribbon (XML)

For example, to customize the Excel Ribbon, add a Ribbon item to an Excel add-in project.

Ribbon (Visual Designer) Item

The Ribbon (Visual Designer) item provides advanced tools that make it easier for you to design and develop a custom Ribbon. Use the Ribbon (Visual Designer) item to customize the Ribbon in the following ways:

  • Add custom or built-in tabs to a Ribbon.

  • Add custom groups to a custom or built-in tab.

    Note

    A built-in tab or group is one that already exists on the Ribbon of a Microsoft Office application. For example, the Data tab is a built-in tab in Excel. The Connections group is a built-in group on the Data tab.

  • Add custom controls to a custom group.

  • Add custom controls to the Microsoft Office menu.

For more information about how to customize a Ribbon by using the Ribbon (Visual Designer) item, see Ribbon Designer.

Ribbon (XML) Item

Use the Ribbon (XML) item if you want to customize the Ribbon in a way that is not supported by the Ribbon (Visual Designer) item. Use the Ribbon (XML) item to customize the Ribbon in the following ways:

  • Add built-in groups to a custom tab or built-in tab.

  • Add built-in controls to a custom group.

  • Add custom code to override the event handlers of built-in controls.

  • Customize the Quick Access Toolbar.

  • Share a Ribbon customization between add-ins by using a qualified ID.

For more information about how to customize the Ribbon by using the Ribbon (XML) item, see Ribbon XML.

Exporting a Ribbon from the Ribbon Designer to Ribbon XML

If you create a Ribbon by using the Ribbon Designer, and then decide that you want to customize the Ribbon in ways that the Ribbon (Visual Designer) item does not support, you can export the Ribbon to XML.

Visual Studio automatically creates a Ribbon (XML) item and populates the Ribbon XML file with elements and attributes for each control on the Ribbon.

Not all of the properties that are in the Properties window of the Ribbon designer are transferred to the Ribbon XML file. For example, Visual Studio does not export the value of the Image or Text property. That is because you must create a callback method in the Ribbon code file of the exported project to assign an image or set the text of a control. Visual Studio does not automatically generate callback methods as part of the export process.

In addition, any unchanged default property values do not appear in the resulting Ribbon XML file.

For more information about how to export the Ribbon to XML, see How to: Export a Ribbon from the Ribbon Designer to Ribbon XML.

Updating the Code

A new Ribbon code file is added to Solution Explorer. This file contains the Ribbon XML class. You must create callback methods in the Ribbon Callbacks region of this class to handle user actions, such as clicking a button. Move your code from the event handlers to these callback methods and modify the code to work with the Ribbon extensibility (RibbonX) programming model. For more information, see Ribbon XML.

You must also add code to the ThisAddIn, ThisWorkbook, or ThisDocument class that overrides the CreateRibbonExtensibilityObject method and returns the Ribbon XML class to the Office application.

For more information, see Ribbon XML.

Adding Multiple Ribbon Items to a Project

You can add more than one Ribbon item to a single project. This is useful if you want to perform either of the following two tasks:

  • Create Ribbons for Outlook Inspectors. For more information, see Customizing a Ribbon for Outlook.

    Note

    An Inspector is a window that opens when users perform certain tasks, such as creating an e-mail message.

  • Select which Ribbon to display at run time.

Selecting Which Ribbons to Display at Run Time

Because a project can contain more than one Ribbon, you can select which Ribbon to display at run time.

To select a Ribbon to display at run time, override the CreateRibbonExtensibilityObject method in the ThisAddin, ThisWorkbook, or ThisDocument class of your project and return the Ribbon that you want to display. The following example checks the value of a field named myCondition and returns the appropriate Ribbon.

Note

The syntax used in this example returns a Ribbon that was created by using the Ribbon (Visual Designer) item. The syntax for returning a Ribbon that is created by using a Ribbon (XML) item is slightly different. For more information about returning a Ribbon (XML) item, see Ribbon XML.

For projects that target the .NET Framework 4, add the following code:

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
    Microsoft.Office.Core.IRibbonExtensibility
    If myCondition = True Then
        Return Globals.Factory.GetRibbonFactory().CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() _
                 {New Ribbon1()})
    Else
        Return Globals.Factory.GetRibbonFactory().CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() _
                 {New Ribbon2()})
    End If
End Function
    protected override Microsoft.Office.Core.IRibbonExtensibility
CreateRibbonExtensibilityObject()
    {
        if (myCondition == true)
        {
            return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { new Ribbon1() });
        }
        else
        {
            return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { new Ribbon2() });
        }
    }

For projects that target the .NET Framework 3.5, add the following code:

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
    Microsoft.Office.Core.IRibbonExtensibility
    If myCondition = True Then
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() _
                 {New Ribbon1()})
    Else
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() _
                {New Ribbon2()})
    End If
End Function
    protected override Microsoft.Office.Core.IRibbonExtensibility
CreateRibbonExtensibilityObject()
    {
        if (myCondition == true)
        {
            return new Microsoft.Office.Tools.Ribbon.RibbonManager(
                new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                    { new Ribbon1() });
        }
        else
        {
            return new Microsoft.Office.Tools.Ribbon.RibbonManager(
                new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                    { new Ribbon2() });
        }
    }

Title

Description

How to: Get Started Customizing the Ribbon

Shows you how to customize the Ribbon of a Microsoft Office application, add a Ribbon (Visual Designer) or Ribbon (XML) item to an Office project.

Ribbon Designer

Describes how you can use the Ribbon Designer to add custom tabs, groups, and controls to the Ribbon of a Microsoft Office application.

Walkthrough: Creating a Custom Tab by Using the Ribbon Designer

Shows you 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.

Ribbon Object Model Overview

Provides an overview of the strongly typed object model that you can use to get and set the properties of Ribbon controls at run time.

Walkthrough: Updating the Controls on a Ribbon at Run Time

Demonstrates how to use the Ribbon object model to update the controls on a Ribbon after the Ribbon is loaded into the Office application.

Customizing a Ribbon for Outlook

Provides guidance for customizing the Ribbon in Microsoft Office Outlook.

Customizing a Ribbon for InfoPath

Provides guidance for customizing the Ribbon in Microsoft Office InfoPath.

Accessing the Ribbon at Run Time

Shows how to show, hide, and modify the Ribbon, and enable users to run the code from controls in a custom task pane, actions pane, or Outlook form region.

How to: Change the Position of a Tab on the Ribbon

Shows how to change the order of tabs on a Ribbon.

How to: Customize a Built-in Tab

Shows how to add groups and controls to a built-in tab.

How to: Customize the Microsoft Office Menu

Shows how to add controls to the menu that opens when you click the File tab (for Office 2010) or the Microsoft Office Button (for Office 2007).

How to: Add a Dialog Box Launcher to a Ribbon Group

Shows to add a dialog box launcher to any group on a Ribbon.

How to: Export a Ribbon from the Ribbon Designer to Ribbon XML

Shows how to customize the Ribbon in advanced ways by exporting the Ribbon from the designer to Ribbon XML.

Ribbon XML

Explains how you can customize a Ribbon by using Ribbon XML.

Walkthrough: Creating a Custom Tab by Using the Ribbon Designer

Demonstrates how to create a custom Ribbon tab by using the Ribbon (XML) item.