Udostępnij za pośrednictwem


Ribbon Object Model Overview

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.

Visual Studio Tools for Office 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.

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 Tools for Office adds a class to your project that 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 OfficeRibbon class contains the following three events:

The Load event is raised when the Office application loads the Ribbon customization. The Load event handler is automatically added to the Ribbon code file. Use this event handler to run custom code when the Ribbon loads.

The LoadImage event enables you to cache images in the Ribbon customization when the Ribbon loads. You can get a slight performance gain if you write code to cache the Ribbon images in this event handler. For more information, see LoadImage.

The Close event is raised when the Ribbon instance closes.

Ribbon Control Classes

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

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

Control name

Class name

Box

RibbonBox

Button

RibbonButton

ButtonGroup

RibbonButtonGroup

CheckBox

RibbonCheckBox

ComboBox

RibbonComboBox

DropDown

RibbonDropDown

EditBox

RibbonEditBox

Gallery

RibbonGallery

Group

RibbonGroup

Label

RibbonLabel

Menu

RibbonMenu

Separator

RibbonSeparator

SplitButton

RibbonSplitButton

Tab

RibbonTab

ToggleButton

RibbonToggleButton

The Microsoft.Office.Tools.Ribbon namespace uses the "Ribbon" prefix for these classes 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 Control Classes

Each Ribbon control class 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.

For this task:

Do this:

Hide or show a control.

Use the Visible property.

Enable or disable a control.

Use the Enabled property.

Set the size of a control.

Use the ControlSize property.

Get the image that appears on a control.

Use the Image property.

Change the label of a control.

Use the Label property.

Add user-defined data to a control.

Use the Tag property.

Get the items in a RibbonBox, RibbonDropDown, RibbonGallery, or

RibbonSplitButton control.

Use the Items property.

Add items to a RibbonComboBox, RibbonDropDown, or RibbonGallery control.

Use the Items property.

Add controls to a RibbonMenu.

Use the Items property.

To add controls to the RibbonMenu after the Ribbon is loaded into the Office application, you must set the Dynamic property to true before the Ribbon is loaded into the Office application. For information, see Setting Properties That Become Read-Only.

Get the selected item of a RibbonComboBox,

RibbonDropDown, or RibbonGallery.

Use the SelectedItem property. For a RibbonComboBox, use the Text property.

Get the groups on a RibbonTab.

Use the Groups property.

Specify the number of rows and columns that appear in a RibbonGallery.

Use the RowCount and ColumnCount 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 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.

Starting in Visual Studio 2008 Service Pack 1 (SP1), properties of controls that you add to a dynamic menu can be set at any time. However, if you have not installed SP1, some of the properties become read-only after the control has been added to the menu.

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.

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

}

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 2007 workbook project.

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.

Note

If you install SP1, you can set the properties of controls on dynamic menus at any time. This table does not apply in that case.

Property

Ribbon control class

BoxStyle

RibbonBox

ButtonType

RibbonSplitButton

ColumnCount

RibbonGallery

ControlId

RibbonTab

DialogLauncher

RibbonGroup

Dynamic

RibbonMenu

Global

OfficeRibbon

Groups

RibbonTab

ImageName

RibbonButton

RibbonComboBox

RibbonDialogLauncher

RibbonDropDown

RibbonEditBox

RibbonGallery

RibbonMenu

RibbonSplitButton

RibbonToggleButton

ItemSize

RibbonMenu

RibbonSplitButton

MaxLength

RibbonComboBox

RibbonEditBox

Name

RibbonComponent

Position

RibbonButton

RibbonCheckBox

RibbonGallery

RibbonGroup

RibbonMenu

RibbonSeparator

RibbonSplitButton

RibbonTab

RibbonToggleButton

RibbonType

OfficeRibbon

RowCount

RibbonGallery

ShowItemImage

RibbonComboBox

RibbonDropDown

RibbonGallery

ShowItemLabel

RibbonDropDown

RibbonGallery

ShowItemSelection

RibbonGallery

SizeString

RibbonComboBox

RibbonDropDown

RibbonEditBox

StartFromScratch

OfficeRibbon

Tabs

OfficeRibbon

Title

RibbonSeparator

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.

Note

Ensure that the Name property is set for each control that you add to an Outlook Ribbon. If you add a control to an Outlook Ribbon at run time, you must set this property in your code. If you add a control to an Outlook Ribbon at design time, the Name property is set automatically.

Ribbon Control Events

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

Event

Description

Click

Occurs when a control is clicked.

TextChanged

Occurs when the text of an edit box or combo box is changed.

ItemsLoading

Occurs when the Items collection of the control is requested by Office. Office caches the Items collection until your code changes the properties of the control, or you call the Microsoft.Office.Core.IRibbonUI.InvalidateControl method.

ButtonClick

Occurs when a button in a RibbonGallery or RibbonDropDown is clicked.

SelectionChanged

Occurs when the selection in a RibbonDropDown or RibbonGallery changes.

DialogLauncherClick

Occurs when the dialog launcher icon in the lower-right corner of a group is clicked.

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

Parameter

Description

sender

An Object that represents the control that raised the event.

e

A RibbonControlEventArgs that contains an Microsoft.Office.Core.IRibbonControl. Use this control to access any property that is not available in the Visual Studio Tools for Office Ribbon object model.

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

Concepts

Accessing the Ribbon at Run Time

Ribbon Overview

Ribbon Designer

Customizing a Ribbon for Outlook

Reference

Microsoft.Office.Tools.Ribbon

Change History

Date

History

Reason

July 2008

Revised information about setting properties of controls on dynamic menus after you install SP1.

SP1 feature change.