Adding Custom Check Boxes to the 2007 Office Fluent User Interface

Article
05/05/2014

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 check boxes, 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

The 2007 Microsoft Office Fluent user interface (UI) replaces the current system of layered menus, toolbars, and task panes with a simpler system that is optimized for efficiency and discoverability. The Ribbon, context (right-click) menus, the Quick Access Toolbar, and the Microsoft Office checkbox are all parts of the Office Fluent interface. There are a number of custom and built-in controls, such as buttons, checkboxes, 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. You 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.

Adding Custom CheckBoxes to Ribbon video

Watch the Video

Length: 7:36 | Size: 4.93 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 checkboxes to the Ribbon or reuse one of the many built-in checkboxes.

Adding Controls with XML

XML provides a hierarchical, declarative model of the Ribbon. Add controls, such as check boxes, to the Ribbon by using XML elements to specify the type of component. For example, you can add a single check box by using the checkBox element. assign property values to the checkbox by using attributes such as the [label] attribute. Here is a sample:

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">
   <ribbon startFromScratch="false">
      <tabs>
         <tab id="tab1" label="CheckBox Demo" keytip="z" >
            <group id="group1" label="Demo Group">
               <checkBox id="checkbox1" 
                  "enabled="true" 
                  "getLabel="GetLabel" 
                  "keytip="A1" 
                  "getScreentip="GetScreentip" 
                  "supertip="This is a super tip for the checkBox." 
                  "visible="true" 
                  "getPressed="GetPressed" 
                  "onAction="OnAction" />
               <checkBox id="checkbox2" 
                  "getLabel="GetLabel" 
                  "onAction="OnAction" />
            </group>
         </tab>
      </tabs>
   </ribbon>
</customUI>

This sample adds a custom tab titled CheckBox Demo to the Office Fluent Ribbon by assigning text to the tab element's [label] attribute. This tab contains the Demo Group group, which contains two custom check boxes named checkBox1 and checkbox2, respectively. The check boxes have properties defined by attributes such as [visible], [enabled], and [keytip]. You can assign these properties 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 Office Fluent Ribbon in Microsoft Office Excel 2007.

Figure 1. A sample modified Ribbon in Office Excel 2007

Sample modified Ribbon

The [enabled] attribute's property is set to True, which causes the check box to be available to use. When it is set to False, the control is grayed out, indicating that the check box is not active. Next the [getLabel] attribute points to a callback procedure that defines the label for the check box. For more information about callback procedures, see Assigning Functionality to Office Fluent Ribbon Components.

The [keytip] attribute assigns a KeyTip for the check box. KeyTips are sometimes known as access keys or accelerators and are used as shortcut key combinations that activate controls. To use a KeyTip on a custom tab control, you first set a KeyTip for the tab or use the default KeyTip assigned by Microsoft Office. Then you assign a KeyTip for the control. For example, in the code, the tab has a KeyTip equal to z. The checkbox1 check box has a KeyTip equal to A1. When the Office Fluent 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 check box 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 item on the Office Fluent Ribbon. They 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.

Note
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 procedure 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]. For more information about which attributes are assigned explicitly and which attributes point to callback, see Customizing the 2007 Office Fluent Ribbon for Developers (Part 3 of 3).

Looking again at the XML code in the previous example, the [visible] attribute is set to a Boolean value that determines whether the check box is displayed on the Ribbon.

Next, the [getPressed] attribute specifies the default behavior for the check box. If the value of the attribute resolves to True when the check box is displayed, it shows as selected, with the box checked. If the value resolves to False, the check box is cleared.

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

Assigning Functionality to Office Fluent Ribbon Components

In the previous XML sample, some of the attributes point to callback procedures. For example, the checkbox element has an [OnAction] attribute. When the check box is clicked, the OnAction method, or callback procedure, is called. The code in the [OnAction] method gives the check box its functionality. These procedures are called callbacks because when the check box 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 "checkbox1" : strLabel = "Insert text."
        Case "checkbox2" : strLabel = "Insert more text."
    End Select
    Return strLabel
End Function

public stringn GetLabel(IRibbonControl control)
{
    private string strLabel = "";
    switch (control.Id)
    {
        case "checkbox1": strLabel = "Insert text."; break;
        case "checkbox2": strLabel = "Insert more text."; break;
        default: strLabel = "Insert text."; break;
    }
    return strLabel;
}

When the GetLabel procedure is called by Microsoft Office, an [IRibbonControl] object representing the check box 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 check box'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 check box.

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 GetPressed callback procedure returns a Boolean value to Microsoft Office that specifies the default condition of the check box. If the call resolves to True, the check box is displayed as checked when it is initially displayed. Returning False (the default value) specifies that the check box's initial display state is unchecked.

Public pressedState As Boolean = False 
Public Function GetPressed(ByVal control As IRibbonControl) As Boolean
    Return pressedState
End Function

public bool pressedState = false;
public bool GetPressed(IRibbonControl control)
{
    return pressedState;
}

Finally, the OnAction callback procedure is called when you click the check box. 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, ByVal pressed As Boolean)
    If pressed Then
        applicationObject.Range("A1").Value = _
           "You selected the check box."
    Else
        applicationObject.Range("A1").Value = _
           "You cleared the check box."
    End If
    pressedState = pressed
End Sub

public void OnAction(IRibbonControl control, bool pressed)
{
    if(pressed)
    {
        applicationObject.get_Range("A1:A1", missing).Value2 = "You selected the check box;
    }
    else 
    {
        applicationObject.get_Range("A1:A1", missing).Value2 = "You cleared the check box.";
    }
    pressedState = pressed;
}

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

Open the document as a ZIP file by changing the file name extension.
Add a folder containing the XML Ribbon customization code.
Modify the document's relationship file to point to the custom folder.
Rename the document's file extension.
Open the document in the Microsoft Office application.
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 Check Boxes to the Ribbon

In the following procedure, you combine this information to create a custom tab containing a custom group and two custom check boxes to add to the Ribbon in Office Excel 2007. This demonstrates how to use a check box on the Ribbon.

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

Start Visual Studio 2005.
On the File menu, point to New, and then click Project.
In the New Project dialog box, in the Project Types pane, expand Other Project Types, click Extensibility, and then select Shared Add-in.
In the Name box, type RibbonDemo and then click OK to create the project.
On the first page of the Shared Add-in Wizard, click Next.
On the Select a Programming Language page, select either Visual C# or Visual Basic, and then click Next.
On the Select an Application Host page, clear all of the selections except Microsoft Excel, and then click Next.
On the Enter a Name and Description page, optionally, type a name for the project and a description, and then click Next.
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 a reference to the Office Core type library.

To add a reference to the project

In Solution Explorer, expand the References folder.

If you do not see the References folder, on the Project menu, click Show All Files.
Delete the Microsoft.Office.Core reference.
Right-click the References folder and then click Add Reference.
Click the COM tab, select Microsoft Office 12.0 Object Library, and then click OK.

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

On the Project menu, click Add New Item.
In the Add New Item dialog box, select XML File. Name the new file Ribbon.xml, and then click Add.
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

In Solution Explorer, select Ribbon.xml.
In the Properties window, select the Build Action property, and then select Embedded Resource in the list of options.
On the Project menu, click RibbonDemo Properties.
Click the Resources tab.
From Solution Explorer, drag Ribbon.xml onto the Resources design surface.

This action creates a 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.
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

In Solution Explorer, right-click Connect.cs or Connect.vb, and then click View Code.
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;
```
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;
```
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
```
If coding in C#, at the end of the public class Connect : statement, add a comma and then type the following interface name.
```
IRibbonExtensibility
```
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.

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

Add the code in the section Assigning Functionality to Office Fluent 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.

Testing the Project

Now you are ready to run the project.

To test the project

On the File menu, click Save All.
Exit Excel 2007 if it is running.
On the Build menu, click Build Solution.
In Solution Explorer, right-click RibbonDemoSetup, and then click Build.
Right-click RibbonDemoInSetup, and then click Install.

The RibbonDemo Setup Wizard appears.
Click Next on each of the pages, and then click Close on the last screen.
Start Excel.

The Checkbox Demo tab appears. You also see the Group Demo group containing two check boxes.
Click the Insert Text check box.

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

Figure 2. Click the Insert Text check box to insert text in cell A1
Click the Insert Text check box a second time. The text in cell A1 changes.
Exit Excel.
In Visual Studio, in Solution Explorer, right-click RibbonDemoSetup, and then click Uninstall.

Explore It

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