Ribbon XML

Article
11/16/2012

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.

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.

The Ribbon (XML) item enables you to customize a Ribbon by using XML. 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. For a comparison of what you can do with each item, see Ribbon Overview.

Adding a Ribbon (XML) Item to a Project

You can add a Ribbon (XML) item to any Visual Studio Tools for Office project from the Add New Item dialog box. Visual Studio Tools for Office automatically adds the following files to your project:

A Ribbon XML file. This file defines the Ribbon user interface (UI). Use this file to add UI elements such as tabs, groups, and controls. For details, see Ribbon XML File Reference later in this topic.
A Ribbon code file. This file contains the Ribbon class. This class has the name that you specified for the Ribbon (XML) item in the Add New Item dialog box. Microsoft Office applications use an instance of this class to load the custom Ribbon. For details, see Ribbon Class Reference later in this topic.

By default, these files add a custom group to the Add-Ins tab in the Ribbon.

Displaying the Custom Ribbon in a Microsoft Office Application

After you add a Ribbon (XML) item to your project, you must add code to the ThisAddin, ThisWorkbook, or ThisDocument class that overrides the CreateRibbonExtensibilityObject method and returns the Ribbon XML class to the Office application.

The following code example overrides the CreateRibbonExtensibilityObject method and returns a Ribbon XML class named MyRibbon.

Protected Overrides Function CreateRibbonExtensibilityObject() As  _
Microsoft.Office.Core.IRibbonExtensibility
    Return New MyRibbon()
End Function

protected override Microsoft.Office.Core.IRibbonExtensibility CreateRibbonExtensibilityObject()
{
    return new MyRibbon();
}

Defining the Behavior of the Custom Ribbon

You can respond to user actions, such as clicking a button on the Ribbon, by creating callback methods. Callback methods resemble events in Windows Forms controls, but they are identified by an attribute in the XML of the UI element. You write methods in the Ribbon class, and a control calls the method that has the same name as the attribute value. For example, you can create a callback method that is called when a user clicks a button on the Ribbon. Two steps are required to create a callback method:

Assign an attribute to a control in the Ribbon XML file that identifies a callback method in your code.
Define the callback method in the Ribbon class.

Note

Outlook 2007 requires an additional step. For more information, see Customizing a Ribbon for Outlook.

For a walkthrough that demonstrates how to automate an application from the Ribbon, see Walkthrough: Creating a Custom Tab by Using Ribbon XML.

Assigning Callback Methods to Controls

To assign a callback method to a control in the Ribbon XML file, add an attribute that specifies the type of the callback method and the name of the method. For example, the following element defines a toggle button that has an onAction callback method named OnToggleButton1.

<toggleButton id="toggleButton1" onAction="OnToggleButton1" />

onAction is called when the user performs the main task associated with a particular control. For example, the onAction callback method of a toggle button is called when the user clicks the button.

The method that you specify in the attribute can have any name. However, it must match the name of the method that you define in the Ribbon code file.

There are many different types of callback methods that you can assign to Ribbon controls. For a complete list of the callback methods available for each control, see the technical article Customizing the Office (2007) Ribbon User Interface for Developers (Part 3 of 3).

Defining Callback Methods

Define your callback methods in the Ribbon class in the Ribbon code file. A callback method has several requirements:

It must be declared as public.
Its name must match the name of a callback method that you assigned to a control in the Ribbon XML file.
Its signature must match the signature of a type of callback method that is available for the associated Ribbon control.

For a complete list of the callback method signatures for Ribbon controls, see the technical article Customizing the Office (2007) Ribbon User Interface for Developers (Part 3 of 3). Visual Studio Tools for Office does not provide IntelliSense support for callback methods that you create in the Ribbon code file. If you create a callback method that does not match a valid signature, the code will compile, but nothing will occur when the user clicks the control.

All callback methods have an Microsoft.Office.Core.IRibbonControl parameter that represents the control that called the method. You can use this parameter to reuse the same callback method for multiple controls. The following code example demonstrates an onAction callback method that performs different tasks depending on which control the user clicks.

Public Sub OnActionCallback(ByVal control As Office.IRibbonControl, _
    ByVal isPressed As Boolean)

    If (control.Id = "checkBox1") Then
        MessageBox.Show("You clicked " + control.Id)
    Else
        MessageBox.Show("You clicked a different control.")
    End If 

End Sub

public void OnActionCallback(Office.IRibbonControl control, bool isPressed)
{
    if (control.Id == "checkBox1")
    {
        MessageBox.Show("You clicked " + control.Id);
    }
    else
    {
        MessageBox.Show("You clicked a different control.");
    }
}

Ribbon XML File Reference

You can define your custom Ribbon by adding elements and attributes to the Ribbon XML file. By default, the Ribbon XML file contains the following XML.

<?xml version="1.0" encoding="UTF-8"?>
<customUI xmlns="https://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup"
               label="My Group">
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

The following table describes the default elements in the Ribbon XML file.

Element	Description
customUI	Represents the custom Ribbon in the add-in project.
ribbon	Represents the Ribbon.
tabs	Represents a set of Ribbon tabs.
tab	Represents a single Ribbon tab.
group	Represents a group of controls on the Ribbon tab.

These elements have attributes that specify the appearance and behavior of the custom Ribbon. The following table describes the default attributes in the Ribbon XML file.

Attribute	Parent element	Description
onLoad	customUI	Identifies a method that is called when the application loads the Ribbon.
idMso	tab	Identifies a built-in tab to display in the Ribbon.
id	group	Identifies the group.
label	group	Specifies the text that appears on the group.

The default elements and attributes in the Ribbon XML file are a small subset of the elements and attributes that are available. For a complete list of the available elements and attributes, see the technical article Customizing the Office (2007) Ribbon User Interface for Developers (Part 2 of 3).

Ribbon Class Reference

Visual Studio Tools for Office generates the Ribbon class in the Ribbon code file. Add the callback methods for controls on the Ribbon to this class. This class implements the Microsoft.Office.Core.IRibbonExtensibility interface.

The following table describes the default methods in this class.

Method	Description
GetCustomUI	Returns the contents of the Ribbon XML file. Microsoft Office applications call this method to obtain an XML string that defines the user interface of your custom Ribbon. Note GetCustomUI should be implemented only to return the contents of the Ribbon XML file; it should not be used to initialize your add-in. In particular, you should not try to display dialog boxes or other windows in your GetCustomUI implementation. Otherwise, the custom Ribbon might not behave correctly. If you have to run code that initializes your add-in, add the code to the ThisAddIn_Startup event handler.
OnLoad	Assigns the Microsoft.Office.Core.IRibbonControl parameter to the ribbon field. Microsoft Office applications call this method when they load the custom Ribbon. You can use this field to dynamically update the custom Ribbon. For more information, see the technical article Customizing the Office (2007) Ribbon User Interface for Developers (Part 1 of 3).
GetResourceText	Called by the GetCustomUI method to obtain the contents of the Ribbon XML file.

Ribbon XML

Adding a Ribbon (XML) Item to a Project

Displaying the Custom Ribbon in a Microsoft Office Application

Defining the Behavior of the Custom Ribbon

Assigning Callback Methods to Controls

Defining Callback Methods

Ribbon XML File Reference

Ribbon Class Reference

See Also

Tasks

Concepts

Additional resources