Adding Custom Buttons to the 2007 Office Fluent User Interface

  • Article

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Summary: Adding controls, such as custom buttons, to the 2007 Microsoft Office Fluent user interface (UI) requires only a few lines of XML and programming code.

Office Visual How To

Applies to: 2007 Microsoft Office System, Microsoft Office Excel 2007, Microsoft Office PowerPoint 2007, Microsoft Office Word 2007

Frank Rice, Microsoft Corporation

April 2007

Overview

The 2007 Microsoft Office Fluent user interface (UI) replaces the current system of layered menus, toolbars, and task panes with a simpler system optimized for efficiency and discoverability. The Ribbon is a part of the Office Fluent interface as are context (right-click) menus, the Quick Access Toolbar, and the Microsoft Office button.

There are a number of custom and built-in controls, such as buttons, check boxes, and combo boxes that you can add to the Ribbon. You add components to the Ribbon with XML markup elements and set properties on those components by using attributes. Assign functionality to the components by using any programming language supported by Microsoft Visual Studio 2005, such as Microsoft Visual Basic.NET and Microsoft Visual C#, as well as Microsoft Visual Basic for Applications (VBA), Microsoft Visual C++, and Microsoft Visual Basic 6.0.

 See It Adding Custom Buttons to Ribbon video

Watch the Video

Length: 9:35 | Size: 7.05 MB | Type: WMV file

Code It | Read It | Explore It

Code It

You can use a combination of XML and programming code to add you own custom buttons to the Ribbon or reuse one of the many built-in buttons.

Adding Controls with XML

XML provides a hierarchical, declarative model of the Ribbon. Add controls, such as buttons, to the Ribbon by using XML elements to specify the type of component. For example, you can add a single button by using the button element. Assign property values to the button by using attributes such as the label attribute. Here is a sample:

<?xml version="1.0" encoding="utf-8" ?>
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" loadImage="LoadImage" >
    <ribbon startFromScratch="false">
        <tabs>
            <tab id="tab1" label="Button Demo" keytip="z" >
                <group id="group1" label="Demo Group">
                    <button id="button1"
                        "enabled="true"
                        "getLabel="GetLabel"
                        "keytip="A1"
                        "getScreentip="GetScreentip"
                        "supertip="This is a supertip for the button."
                        "getShowLabel="GetShowLabel"
                        "getShowImage="GetShowImage"
                        "getSize="GetSize"
                        "visible="true"
                        "image="camera.bmp"
                        "onAction="OnAction" />
                    <button id="button2"
                        "getLabel="GetLabel"
                        "getShowLabel="GetShowLabel"
                        "size="normal"
                        "keytip="A2"
                        "imageMso="TableDrawTable"
                        "onAction="OnAction" />
                </group>
            </tab>
        </tabs>
    </ribbon>
</customUI>

This sample adds a custom tab titled Button Demo to the Ribbon by assigning text to the tab element's label attribute. This tab contains the Demo Group group, which contains two custom buttons named button1 and button2, respectively. The buttons have properties defined by attributes such as [visible], [enabled], and size.

These properties are assigned explicitly by setting the attribute equal to a string, such as the [supertip] attribute, or indirectly by pointing to a programming code procedure. The following figure shows the result of applying this XML to the Ribbon in Microsoft Office Excel 2007:

Figure 1. A sample modified Ribbon in Office Excel 2007

Sample modified Ribbon

As in the sample code, you specify built-in components differently than custom components. Some attributes have the [Mso] suffix and some do not. For example, looking at the above sample, the [id] attribute does not have the [Mso] qualifier. This indicates to Office's software that the button is a custom control. In the [imageMso] attribute, the [Mso] suffix indicates it as a built-in image. Attributes with the [Mso] suffix refer to built-in controls, commands, and images. An example of this appears later in this article.

The other attributes of the buttons should be discussed. First, the enabled attribute's property has been set to True which causes the button to be available to use. When it is set to False the control is grayed out, indicating that the button is not active. Next the [getLabel] attribute points to a callback procedure that defines the label for the button. Callback procedures are described in the Assigning Functionality to Ribbon Components section.

The [keytip] attribute assigns a KeyTip for the button. KeyTips are sometimes known as access keys or accelerators and are used as shortcut key combinations that can be used to activate the control. To use a KeyTip on a custom tab control, you first set a KeyTip for the tab or use the default KeyTip assigned by Office. Then you assign a KeyTip for the control. For example, in the code, the tab has a KeyTip equal to z. The button1 button has a KeyTip equal to A1. When the Ribbon is displayed, press the key combination Alt + z to bring the focus to the custom tab. Then, press the key combination A+1 to activate the button and execute the procedure defined in the [onAction] attribute that inserts text into the worksheet.

Next you see the [getScreentip] attribute. Screentips are those small boxes that appear when you move the mouse pointer over an object on the Ribbon. They are used to provide information about the selected object. Similarly, the [supertip] attribute (or the [getSupertip] attribute if you are pointing to a callback procedure) provides additional information about the object.

When an attribute carries the prefix 'get' it indicates that the attribute points to a callback procedure. Thus in the code, the [getScreentip] attribute points to the callback procedure named GetScreentip.

NoteNote

Callback procedures do not have to be named the same as the attribute they are used with. You could just as easily have used the following line of code getScreentip="DoSomething". Also, attributes that point to callback procedures do not have to be prefixed by get. For example, in the XML code, the [onAction] attribute points to a callback named OnAction.

The [supertip] attribute illustrates another aspect of control attributes. An attribute without the [get] prefix indicates that you can assign text to it explicitly. In the case of the [supertip] attribute, the text is assigned directly instead of by a callback procedure. There are exceptions such as the [onAction] attribute, where the attribute is not prefixed by the word [get]. You can find more information about which attributes are assigned explicitly and which attributes point to callback in the article Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3).

The **[getShowLabel]**and the [getShowImage] attributes both point to callback procedures that resolve to Boolean values. For example, setting the [getShowLabel] attribute to True causes the label for the button to appear when the control is displayed. To set the value of the attribute explicitly, use the [showLabel] attribute.

The [getSize] attribute is used to specify the size of the button. If you are setting the size explicitly as seen in button2, the options are normal and large. For more information about setting the size by using the [getSize] attribute, see Assigning Functionality to Ribbon Components.

Looking again at the above XML code, the [visible] attribute is set to a Boolean value that determines whether the button is displayed on the Ribbon.

Next, the [image] attribute for button1 is used to specify a custom image for the button. Likewise, the [imageMso] attribute for button2 is used to specify a built-in image for the button. To find a spreadsheet of built-in images, see 2007 Office System Add-In: Icons Gallery.

Finally, as mentioned previously, the [onAction] attribute points to a callback procedure that is executed when you click the button. This procedure is discussed in the next section.

Assigning Functionality to Ribbon Components

In the previous XML sample, several of the attributes point to callback procedures. For example, the button element has an [OnAction] attribute. When the button is clicked, the OnAction method, or callback procedure, is called. The code in the [OnAction] method gives the button its functionality. These procedures are called callbacks because when the button is clicked the action alerts Microsoft Office that the control needs attention. Microsoft Office then calls back to the method defined by the OnAction attribute and performs whatever action is contained in the method. The following paragraphs describe these callback procedures in a little more detail.

The [getLabel] attribute calls the GetLabel callback procedure.

Public Function GetLabel(ByVal control As IRibbonControl) As String
    Dim strLabel As String = ""
    Select Case control.Id
        Case "button1" : strLabel = "Insert Text"
        Case "button2" : strLabel = "Insert More Text"
    End Select
    Return strLabel
End Function

public stringn GetLabel(IRibbonControl control)
{
    private string strLabel = "";
    switch (control.Id)
    {
        case "button1": strLabel = "Insert Text"; break;
        case "button2": strLabel = "Insert More Text"; break;
        default: strLabel = "Insert Text"; break;
    }
    return strLabel;
}

When the GetLabel procedure is called by Office, an IRibbonControl object representing the button is passed The procedure tests the Id property of the object and depending on its value, assigns text to a variable. That variable is then returned to Microsoft Office which displays its text as the button's label.

The [getScreentip] attribute also points to a callback procedure. In this case, the procedure returns a string that is displayed when you move the mouse over the button.

Public Function GetScreenTip(ByVal control As IRibbonControl) As String
    Return "Inserts text into the active worksheet."
End Function

public string GetScreenTip(IRibbonControl control)
{
    return "Inserts text into the active worksheet.";
}

The getShowLabel and getShowImage callback procedures return a Boolean value to Microsoft Office that specifies whether to display the respective object (a label or an image) when the custom tab is displayed.

Public Function GetShowLabel(ByVal control As IRibbonControl) As Boolean
    Dim bolShow As Boolean
    Select Case control.Id
        Case "button1" : bolShow = True
        Case "button2" : bolShow = False
    End Select
    Return bolShow
End Function

Public Function GetShowImage(ByVal control As IRibbonControl) As Boolean
    Return True
End Function

public bool GetShowLabel(IRibbonControl control)
{
    private bool bolShow;
    switch (control.Id)
    {
        case "button1": bolShow = true; break;
        case "button2": bolShow = false; break;
        default: bolShow = true; break;
    }
    return bolShow;
}

public bool GetShowImage(IRibbonControl control)
{
    return true;
}

The GetShowLabel procedure tests the Id property of the control and depending on its value, sets a Boolean variable to True or False. That variable is then returned to Office.

Next is the [getSize] attribute that points to the GetSize callback procedure.

Public Function GetSize(ByVal control As IRibbonControl) As RibbonControlSize
    ' Selecting one of the two RibbonControlSize enumeration values 
    ' sets the size of the button.
    Return RibbonControlSize.RibbonControlSizeRegular
    ' RibbonControlSize.RibbonControlSizeLarge
End Function

public RibbonControlSize GetSize(IRibbonControl control)
{
    // Selecting one of the two RibbonControlSize enumeration values 
    // sets the size of the button.
    return RibbonControlSize.RibbonControlSizeRegular;
    // RibbonControlSize.RibbonControlSizeLarge;
}

In this procedure, a value of the RibbonControlSize enumeration is returned to Office. The RibbonControlSizeRegular is used for the standard sized control and the RibbonControlSizeLarge value is used to represent a larger control.

Finally, the OnAction callback procedure is called when you click the button. In this case, the procedure tests the Id property of the calling control and inserts text specific to that control into the A1 cell in the worksheet.

Public Sub OnAction(ByVal control As IRibbonControl)
    Select Case control.Id
        Case "button1" : applicationObject.Range("A1").Value = _
            "This button inserts text."
        Case "button2" : applicationObject.Range("A1").Value = _
            "This button inserts more text."
    End Select
End Sub

public void OnAction(IRibbonControl control)
{
    switch (control.Id)
    {
        case "button1":
            applicationObject.get_Range("A1:A1", missing).Value2 = "This button inserts text."; break;
        case "button2":
            applicationObject.get_Range("A1:A1", missing).Value2 = "This button inserts more text."; break;
        default:
            applicationObject.get_Range("A1:A1", missing).Value2 = "There was a problem with your selection."; break;
    }
}

Read It

There are two ways to deploy a custom Ribbon:

  • Modify an Open XML Format file created by one of the Microsoft Office applications that support the Office Fluent UI.

  • Use an add-in.

You can select the technique depending on the scope you need for the customized Ribbon. For example, modifying an Open XML file results in document-level customization where the customized Ribbon is associated with a particular document rather than the entire application. On the other hand, by using an add-in, you get application-level customization which means that the customized Ribbon applies to the entire application regardless of which document is open.

Creating a customized Ribbon using an Open XML file is not complicated.

To create a customized Ribbon using an Open XML file

  1. Open the document as a ZIP file by changing the file name extension.

  2. Add a folder containing the XML Ribbon customization code.

  3. Modify the document's relationship file to point to the custom folder.

  4. Rename the document's file extension.

  5. Open the document in the Microsoft Office application.

  6. Add code to the document to give the custom Ribbon functionality.

Using an add-in to customize the Ribbon is equally simple.

After creating the add-in project, you implement the IRibbonExtensibility interface, which is included in the Microsoft.Office.Core namespace. This interface contains a method called GetCustomUI. Use this method to return the XML Ribbon customization code to Office. Then add programming procedures that give the custom Ribbon its functionality.

Adding Custom Buttons to the Ribbon

In the following procedure, you combine this information to create a custom tab containing a custom group and two custom buttons to the Ribbon in Office Excel 2007. These buttons insert text into the worksheet.

Creating the Add-In Solution

To create the project, there are nine steps.

To create the add-in solution adding custom buttons to the Ribbon

  1. Start Visual Studio 2005.

  2. On the File menu, point to New, and then click Project.

  3. In the New Project dialog box, in the Project Types pane, expand Other Project Types, click Extensibility, and then select Shared Add-in.

  4. In the Name box, type RibbonDemo and then click OK to create the project.

  5. On the first page of the Shared Add-in Wizard, click Next.

  6. On the Select a Programming Language page, select either Visual C# or Visual Basic, and then click Next.

  7. On the Select an Application Host page, clear all of the selections except Microsoft Excel, and then click Next.

  8. On the Enter a Name and Description page, optionally, type a name for the project and a description, and then click Next.

  9. On the Choose Add-in Options page, select I would like my Add-in to load when the host application loads, click Next, and then click Finish.

Visual Studio creates a solution that contains two projects—the add-in itself and a Setup project. The Setup project enables you to install the add-in on other users' computers, and it makes it easier for you, at design time, to install and uninstall the add-in.

Adding References to the Project

To interact with Excel 2007 and the Ribbon object model, add references to two type libraries.

To add references to the project

  1. In Solution Explorer, expand the References folder.

    If you do not see the References folder, on the Project menu, click Show All Files.

  2. Delete the Microsoft.Office.Core reference.

  3. Right-click the References folder and then click Add Reference.

  4. Click the COM tab, select Microsoft Office 12.0 Object Library, and then click OK.

  5. At the top of the open code file, add the following statements to the project.

    Imports Microsoft.Office.Core
Imports Excel = Microsoft.Office.Interop.Excel

    using Microsoft.Office.Core;
using Excel = Microsoft.Office.Interop.Excel;

Creating the Ribbon Customization XML File

Create the file that adds the components and sets the property for those components.

To create the ribbon customization XML file

  1. On the Project menu, click Add New Item.

  2. In the Add New Item dialog box, select XML File. Name the new file Ribbon.xml, and then click Add.

  3. In the new XML file, add the XML markup in the section titled Adding Controls with XML.

Adding the XML File as an Embedded Resource

For best results, use the XML file as a resource within the project's resource file.

To add the XML file as an embedded resource

  1. In Solution Explorer, select Ribbon.xml.

  2. In the Properties window, select the Build Action property, and then select Embedded Resource in the list of options.

  3. On the Project menu, click RibbonDemo Properties.

  4. Click the Resources tab.

  5. From Solution Explorer, drag Ribbon.xml onto the Resources design surface.

    This action creates a new file-based resource. From now on, the Ribbon.xml file is automatically stored as an application resource, and you can retrieve this content by using Visual Basic or Visual C# language features.

  6. Close the Resources window. When prompted, click Yes to save the resources.

Accessing the Host Application and Working with the Ribbon

You need to create an instance of Excel and add the Ribbon interface.

To access the host applications and work with the Ribbon

  1. In Solution Explorer, right-click Connect.cs or Connect.vb, and then click View Code.

  2. Find the existing declaration for the applicationObject variable, and modify it so that it refers to an Excel.Application object. That is, modify the declaration so that it looks like the following code.

    Private applicationObject As Excel.Application

    private Excel.Application applicationObject;

  3. Modify the existing first line of the OnConnection method, which creates an instance of the Excel.Application object.

    applicationObject = DirectCast(application, Excel.Application)

    applicationObject =(Excel.Application)application;

  4. In Visual Basic, modify the line of code, near the top of the class that starts with Implements, adding support for implementing the IRibbonExtensibility namespace. Visual Basic inserts the GetCustomUI procedure automatically.

    Implements Extensibility.IDTExtensibility2, IRibbonExtensibility

  5. If coding in C#, at the end of the public class Connect : statement, add a comma and then type the following interface name.

    IRibbonExtensibility

  6. Continuing in C#, right-click the interface you just added, click Implement Interface, and then click Implement Interface Explicitly. This adds a stub for the only IRibbonExtensibility interface member: GetCustomUI.

  7. Modify the GetCustomUI method so that it looks like the following code.

    Public Function GetCustomUI(ByVal RibbonID As String) As String _
   Implements Microsoft.Office.Core.IRibbonExtensibility.GetCustomUI
   Return My.Resources.Ribbon
End Function

    string IRibbonExtensibility.GetCustomUI(string RibbonID)
{
  Return Properties.Resources.Ribbon;

  8. Add the code in the section Assigning Functionality to Ribbon Components according to the programming language. This method tests the Id property of the control and inserts the text specific to that control into the worksheet at cell A1.

    Since this menu control uses a custom image, you will need to add your own image to the project by performing the following steps:

  9. In the Solution Explorer pane, right-click the project name, point to Add, and then click Existing Item.

  10. Navigate to and select the image and click the Add button.

  11. Select the image file and in the Properties pane, in the Build Action property, click Embedded Resource.

  12. Then right-click the project name again, and click Properties.

  13. Click the Resources tab and then from the Solution Explorer pane, drag and down the image file onto the Resources tab.

Testing the Project

Now you are ready to run the project.

To test the project

  1. On the File menu, click Save All.

  2. Exit Excel 2007 if it is running.

  3. On the Build menu, click Build Solution.

  4. In Solution Explorer, right-click RibbonDemonSetup, and then click Build.

  5. Right-click RibbonDemoInSetup, and then click Install.

    The RibbonDemo Setup Wizard appears.

  6. Click Next on each of the pages, and then click Close on the last screen.

  7. Start Excel.

    The Button Demo tab appears. You also see the Group Demo group containing two buttons. Notice the custom image for the top button and the built-in image for the bottom button. In addition, notice the missing label for the bottom button. The label is missing because the getShowLabel attribute was set to false.

  8. Click the Insert Text button.

    Excel inserts the text into the worksheet at cell A1 as displayed in Figure 2.

    Figure 2. Click the Insert Text button to insert text as cell A1

<<<<<<< HEAD Insert Test button

![Insert Test button](images\Bb410115.30fc06ad-8aba-4555-afcc-3c03d7f38ddc(en-us,office.12).gif "Insert Test button")

7f3a9c6c13e671f21bf63e8e33d124610e43b846

  1. Click the bottom button. The text in cell A1 changes.

  2. Exit Excel.

  3. In Visual Studio, in Solution Explorer, right-click RibbonDemonSetup, and then click Uninstall.

Explore It

There are a number of resources on customizing the Office Fluent user interface.