Export (0) Print
Expand All

Ribbon Extensibility Overview

Note Required applications

The features in this topic are available only if you have the required applications installed.

For more information, see Features Available by Product Combination.

  • One of these development environments:

    VSTO 2005

    -or-

    Visual Studio Team System

    -or-

    Visual Studio 2005 Professional Edition

  • VSTO 2005 SE installed in the development environment

  • 2007 Microsoft Office system

The 2007 Microsoft Office system introduces a new user interface (UI) feature that is named the Ribbon. The Ribbon is a way to organize related commands (in the form of controls) so that they are easier to find. Controls are organized into groups along a horizontal strip at the top edge of an application window. Related groups are organized on tabs, such as the default tabs Page Layout and Insert, that help users performs tasks. Most of the features that were accessed by using the menus and toolbars in earlier versions of the Microsoft Office system can now be accessed by using the Ribbon.

You can create your own Ribbon tabs and groups to give users access to functionality that you provide in an application-level add-in. You can use Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System (VSTO 2005 SE) to customize the Ribbon in the following applications:

  • Microsoft Office Excel 2007

  • Microsoft Office Outlook 2007

  • Microsoft Office PowerPoint 2007

  • Microsoft Office Word 2007

For more information about how to use the Ribbon, see the technical article Developer Overview of the User Interface for the 2007 Microsoft Office System.

Architecture of a Custom Ribbon UI

You can customize the Ribbon UI by adding a Ribbon item to an add-in project. VSTO 2005 SE automatically adds the following files to your project:

  • A Ribbon XML file. This file defines the custom Ribbon UI. Use this file to add UI elements such as tabs, groups, and controls.

  • A Ribbon code file. This file contains the Ribbon class. This class has the name that you specified for the Ribbon item in the Add New Item dialog box. Microsoft Office applications use an instance of this class to load the custom Ribbon UI.

By default, these files add a toggle button to the Add-Ins tab in the Ribbon. The button displays a message box when the user clicks it. For information about the contents of the Ribbon project files, see Ribbon XML File Reference and Ribbon Class Reference.

After you add a Ribbon item to your project, you must modify your code to display the custom Ribbon UI. You can optionally modify the appearance and behavior of the default UI.

Displaying the Custom Ribbon UI

To display the custom Ribbon UI, find the RequestService method and uncomment it. VSTO 2005 SE generates this code in a partial extension of the ThisAddIn class in the Ribbon code file when you add a new Ribbon item to your add-in project. By default, this code is commented out in case you have already written a method that overrides RequestService.

You might have overridden the RequestService method if you have already implemented other functionality in your add-in, such as a custom Outlook form region. In that case, you can copy the necessary generated Ribbon code into your existing version of the method.

Your add-in must override the RequestService method so that Microsoft Office applications can discover and load an instance of the Ribbon class in your add-in project. After you uncomment the code, it should resemble the following example.

// TODO:
// This is an override of the RequestService method in ThisAddin class.
// To hook up your custom ribbon uncomment this code.
public partial class ThisAddIn
{
    MyRibbon ribbon;
    protected override object RequestService(Guid serviceGuid)
    {
        if (serviceGuid == typeof(Office.IRibbonExtensibility).GUID)
        {
            if (ribbon == null)
                ribbon = new MyRibbon();
            return ribbon;
        }

        return base.RequestService(serviceGuid);
    }
}

Defining the UI and Behavior of the Ribbon

Define the custom Ribbon UI by modifying the Ribbon XML file. By default, this file adds a toggle button to the Add-Ins tab. You can modify the default UI by adding elements and attributes to this XML file. For example, you can add controls to the Ribbon tab by using elements such as checkBox, comboBox, and splitButton. For information about the default elements and attributes in the Ribbon XML file, see Ribbon XML File Reference.

You can respond to user actions, such as clicking a button, 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. There are two steps 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.

NoteNote

Outlook 2007 requires an additional step. For more information, see Customizing Ribbons in Outlook 2007.

For a step-by-step procedure, see How to: Customize the Ribbon. For a walkthrough that demonstrates how to automate an application from the Ribbon, see Walkthrough: Automating an Application from Controls on the Ribbon.

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 2 of 2).

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 2 of 2). VSTO 2005 SE 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 happen 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 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.");
    }
}

Customizing Ribbons in Outlook 2007

When you customize the Ribbon in Outlook 2007, you must consider where your custom Ribbon UI will appear in the application. Outlook 2007 does not display the Ribbon in the main application window. Instead, Outlook 2007 displays the Ribbon in windows that open when users perform certain tasks, such as creating an e-mail message. These application windows are named Inspectors.

To select an Inspector to load your custom Ribbon UI, check the value of the ribbonID parameter in the Microsoft.Office.Core.IRibbonExtensibility.GetCustomUI method of the Ribbon class. This method is automatically generated by VSTO 2005 SE when you add a new Ribbon item to the add-in project. The ribbonID parameter is a string that identifies a specific type of Inspector. For a complete list of the possible values of the ribbonID parameter, see the technical article Customizing the Ribbon in Outlook 2007.

The following code example demonstrates how to display a custom Ribbon UI only in the Ribbon of the Microsoft.Outlook.Mail.Compose Inspector. This is the Inspector that opens when a user creates a new e-mail message.

public string GetCustomUI(string ribbonID)
{
    string ribbonXML = String.Empty;

    if (ribbonID == "Microsoft.Outlook.Mail.Compose")
    {
        ribbonXML = GetResourceText("Ribbon1.xml");
    }

    return ribbonXML;
}

Ribbon XML File Reference

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

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnLoad">
  <ribbon>
    <tabs>
      <tab idMso="TabAddIns">
        <group id="MyGroup" 
               label="My Group">
          <toggleButton id="toggleButton1" 
                        size="large"
                        label="My Button"
                        screentip="My Button Screentip" 
                        onAction="OnToggleButton1" 
                        imageMso="HappyFace" />
        </group>
      </tab>
    </tabs>
  </ribbon>
</customUI>

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

Element Description

customUI

Represents the custom Ribbon UI 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.

toggleButton

Represents a toggle button on the Ribbon tab.

These elements have attributes that specify the appearance and behavior of the custom Ribbon UI. 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 UI.

id

group, toggleButton

Identifies the group or toggle button.

label

group, toggleButton

Specifies the text that appears on the group or toggle button.

size

toggleButton

Specifies the size of the toggle button. The valid values are large and normal.

screentip

toggleButton

Specifies the text that appears when a user holds the pointer over the toggle button.

onAction

toggleButton

Identifies the method to call when the user clicks the button.

imageMso

toggleButton

Specifies a built-in icon to display on the toggle button.

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 2).

Ribbon Class Reference

VSTO 2005 SE 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 UI.

NoteNote
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 attempt to display dialog boxes or other windows in your GetCustomUI implementation. Otherwise, the custom Ribbon UI might not behave correctly. If you need 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 UI. You can use this field to dynamically update the custom Ribbon UI. For more information, see the technical article Customizing the Office (2007) Ribbon User Interface for Developers (Part 1 of 2).

OnToggleButton1

Called when users click the default toggleButton1 control in the custom Ribbon UI.

GetResourceText

Called by the GetCustomUI method to obtain the contents of the Ribbon XML file.

See Also

Community Additions

ADD
Show:
© 2014 Microsoft