Ribbon Object Model Overview

The Visual Studio Tools for Office runtime exposes a strongly typed object model that you can use to get and set the properties of Ribbon controls at run time. For example, you can dynamically populate menu controls, or show and hide controls contextually. You can also add tabs, groups, and controls to a Ribbon, but only before the Ribbon is loaded by the Office application. For information, see Setting Properties That Become Read-Only.

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.

This Ribbon object model consists mainly of the Ribbon Class, Ribbon Events, and Ribbon Control Classes.

Ribbon Class

When you add a new Ribbon (Visual Designer) item to a project, Visual Studio adds a Ribbon class to your project. If your project targets the .NET Framework 4, the Ribbon class inherits from the RibbonBase class. If your project targets the .NET Framework 3.5, the Ribbon class inherits from the OfficeRibbon class.

This class appears as a partial class that is split between the Ribbon code file and the Ribbon Designer code file.

Ribbon Events

The Ribbon class contains the following three events:

Ribbon Controls

The Microsoft.Office.Tools.Ribbon namespace contains a type for each control that you see in the Office Ribbon Controls group of the Toolbox.

The following table shows the type for each Ribbon control. For a description of each control, see Ribbon Overview.

The Microsoft.Office.Tools.Ribbon namespace uses the "Ribbon" prefix for these types to avoid a name collision with the names of control classes in the System.Windows.Forms namespace.

When you add a control to the Ribbon Designer, the Ribbon Designer declares the class for that control as a field in the Ribbon Designer code file.

Common Tasks Using the Properties of Ribbon Controls

Each Ribbon control contains properties that you can use to perform various tasks, such as assigning a label to a control, or hiding and showing controls.

In some cases, properties become read-only after the Ribbon loads or after a control is added to a dynamic menu. For more information, see Setting Properties that Become Read-Only.

The following table describes some of the tasks that you can perform by using Ribbon control properties.

Setting Properties That Become Read-Only

Some properties can only be set before the Ribbon loads. There are three places to set these properties:

• In the Visual Studio Properties window.

• In the constructor of the Ribbon class.

• In the CreateRibbonExtensibilityObject method of the ThisAddin, ThisWorkbook, or ThisDocument class of your project.

Dynamic menus provide some exceptions. You can create new controls, set their properties, and then add them to a dynamic menu at run time, even after the Ribbon that contains the menu is loaded.

Properties of controls that you add to a dynamic menu can be set at any time.

For more information, see Properties that Become Read-Only.

Setting Properties in the Constructor of the Ribbon

You can set the properties of a Ribbon control in the constructor of the Ribbon class. This code must appear after the call to the InitializeComponent method. The following example adds a new button to a group if the current time is 17:00 Pacific Time (UTC-8) or later.

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

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New(Globals.Factory.GetRibbonFactory())

    'This call is required by the Component Designer.
    InitializeComponent()
    Dim MyButton As Microsoft.Office.Tools.Ribbon.RibbonButton = _
        Me.Factory.CreateRibbonButton()
    MyButton.Label = "New Button"
    If System.DateTime.Now.Hour > 16 Then
        Group1.Items.Add(MyButton)
    End If

End Sub

public Ribbon1()
    : base(Globals.Factory.GetRibbonFactory())
{
    InitializeComponent();
    if (System.DateTime.Now.Hour > 16)
    {
        Microsoft.Office.Tools.Ribbon.RibbonButton button =
            this.Factory.CreateRibbonButton();
        button.Label = "New Button";
        group1.Items.Add(button);
    }
}

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

<System.Diagnostics.DebuggerNonUserCode()> _
Public Sub New()
    MyBase.New()

    'This call is required by the Component Designer.
    InitializeComponent()
    If DateTime.Now.Hour > 16 Then
        Group1.Items.Add(New RibbonButton())
        CType(Group1.Items.Last(), RibbonButton).Label = "New Button"
    End If
End Sub

public Ribbon1()
{
    InitializeComponent();
    if (DateTime.Now.Hour > 16)
    {
        group1.Items.Add(new RibbonButton());
        ((RibbonButton)group1.Items.Last()).Label = "New Button";
    }

}

In Visual C# projects that you upgraded from Visual Studio 2008, the constructor appears in the Ribbon code file.

In Visual Basic projects, or in Visual C# projects that you created in Visual Studio 2010, the constructor appears in the Ribbon Designer code file. This file is named YourRibbonItem.Designer.cs or YourRibbonItem.Designer.vb. To see this file in Visual Basic projects, you must first click the Show All Files button in Solution Explorer.

Setting Properties in the CreateRibbonExtensibilityObject Method

You can set the properties of a Ribbon control when you override the CreateRibbonExtensibilityObject method in the ThisAddin, ThisWorkbook, or ThisDocument class of your project. For more information about the CreateRibbonExtensibilityObject method, see Ribbon Overview.

The following example sets Ribbon properties in the CreateRibbonExtensibilityObject method of the ThisWorkbook class of an Excel workbook project.

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

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return Globals.Factory.GetRibbonFactory.CreateRibbonManager _
            (New Microsoft.Office.Tools.Ribbon.IRibbonExtension() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = false;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager( 
            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[]
             { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType =
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return Globals.Factory.GetRibbonFactory().CreateRibbonManager(
                            new Microsoft.Office.Tools.Ribbon.IRibbonExtension[] { tempRibbon });
    }
}

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

Protected Overrides Function CreateRibbonExtensibilityObject() _
    As Microsoft.Office.Core.IRibbonExtensibility
    Dim myCondition As Boolean = True
    If myCondition = True Then
        Dim tempRibbon As New Ribbon1()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabHome"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    Else
        Dim tempRibbon As New Ribbon2()
        tempRibbon.Tab1.ControlId.ControlIdType = _
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office
        tempRibbon.Tab1.ControlId.OfficeId = "TabInsert"
        Return New Microsoft.Office.Tools.Ribbon.RibbonManager _
            (New Microsoft.Office.Tools.Ribbon.OfficeRibbon() {tempRibbon})
    End If
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility
    CreateRibbonExtensibilityObject()
{
    bool myCondition = true;
    if (myCondition == true)
    {
        Ribbon1 tempRibbon = new Ribbon1();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabHome";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
    else
    {
        Ribbon2 tempRibbon = new Ribbon2();
        tempRibbon.tab1.ControlId.ControlIdType = 
            Microsoft.Office.Tools.Ribbon.RibbonControlIdType.Office;
        tempRibbon.tab1.ControlId.OfficeId = "TabInsert";
        return new Microsoft.Office.Tools.Ribbon.RibbonManager(
            new Microsoft.Office.Tools.Ribbon.OfficeRibbon[] 
                { tempRibbon });
    }
}

Properties That Become Read-Only

The following table shows properties that can only be set before the Ribbon loads.

Setting Properties for Ribbons that Appear in Outlook Inspectors

A new instance of the Ribbon is created each time a user opens an Inspector in which the Ribbon appears. However, you can set the properties listed in the table above only before the first instance of the Ribbon is created. After the first instance is created, these properties become read-only because the first instance defines the XML file that Outlook uses to load the Ribbon.

If you have conditional logic that sets any of these properties to a different value when other instances of the Ribbon are created, this code will have no effect.

Ribbon Control Events

Each control class contains one or more events. The following table describes these events.

The event handlers for these events have the following two parameters.

See Also

Tasks

How to: Get Started Customizing the Ribbon

Walkthrough: Creating a Custom Tab by Using the Ribbon Designer

Walkthrough: Updating the Controls on a Ribbon at Run Time

How to: Customize a Built-in Tab

How to: Customize the Microsoft Office Menu

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

How to: Show Add-in User Interface Errors

Reference

Microsoft.Office.Tools.Ribbon

Concepts

Accessing the Ribbon at Run Time

Ribbon Designer

Customizing a Ribbon for Outlook

Other Resources

Ribbon Overview