Adding Custom Combo Boxes to the 2007 Office Fluent User Interface

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 combo boxes, to the 2007 Microsoft Office Fluent user interface (UI) requires only a few lines of XML and programming code.

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 optimized for efficiency and discoverability. The Office Fluent Ribbon is a part of the Office Fluent interface as are context (right-click) menus, the Quick Access Toolbar, and the Microsoft Office button. You can add a number of custom and built-in controls, such as buttons, check boxes, and combo boxes to the Office Fluent Ribbon. You add components to the Office Fluent 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 Framework and Microsoft Visual C#, as well as Microsoft Visual Basic for Applications (VBA), Microsoft Visual C++, and Microsoft Visual Basic 6.0.

Watch the Video Length: 11:30 | Size: 8.37 MB | Type: WMV file

Code It | Read It | Explore It

Code It

Whether you want to add you own custom combo boxes to the default Office Fluent Ribbon or reuse one of the many built-in combo boxes, you use a combination of XML and programming code.

Adding Controls with XML

XML provides a hierarchical, declarative model of the Office Fluent Ribbon. You add controls, such as combo boxes, to the Office Fluent Ribbon by using XML elements to specify the type of component. For example, you add a single combo box by using the comboBox element. You assign property values to the combo box by using attributes such as the label attribute.

<?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="ComboBox Demo" keytip="z" >
            <group id="group1" label="Demo Group">
               <comboBox id="comboBox1" 
                  enabled="true" 
                  getText="GetText" 
                  getLabel="GetLabel" 
                  image="camera.bmp" 
                  getShowLabel="GetShowLabel" 
                  getShowImage="GetShowImage" 
                  getScreentip="GetScreentip" 
                  supertip="This is a supertip for the combo box." 
                  keytip="A1" 
                  visible="true" 
                  getItemCount="GetItemCount" 
                  getItemLabel="GetItemLabel" 
                  getItemImage="GetItemImage" 
                  getItemScreentip="GetItemScreentip" 
                  getItemSupertip="GetItemSupertip" 
                  onChange="OnChange" />
               <comboBox id="comboBox2" 
                  label="Insert More Text." 
                  getText="GetText" 
                  imageMso="TableDrawTable" />
            </group>
         </tab>
      </tabs>
   </ribbon>
</customUI>

This sample adds a custom tab titled ComboBox 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 combo boxes named comboBox1 and comboBox2, respectively. The combo boxes have properties defined for them by using attributes such as visible, enabled, and label. 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 Office Fluent Ribbon in Microsoft Office Excel 2007:

Figure 1. A sample modified Ribbon in Office Excel 2007

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 sample, the id attribute does not have the Mso qualifier. This indicates to Microsoft Office that the combo box 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.

Examining the other attributes of the combo box, first, you see the enabled attribute. Setting this property to true causes the combo box to be available for use. Setting it to false grays out the control, indicating that the combo box is not active.

Then you see the getText attribute. The getText attribute points to a callback procedure that defines the text that is displayed in the combo box when it is initially displayed. Callback procedures are described in the Assigning Functionality to Ribbon Components section.

The getLabel attribute also points to a callback procedure that returns the label that is displayed for the combo box. Next, the image attribute for comboBox1 specifies a custom image for the combo box. Likewise, the imageMso attribute for comboBbox2 specifies a built-in image for the combo box. For a spreadsheet of built-in images, see 2007 Office Icon Library.

You can use the image and imageMso attributes in conjunction with the loadImage attribute of the customUI element. When you specify an image with the image attribute, the loadImage callback procedure is called to load the image. The image is then displayed on the Ribbon.

Public Function LoadImage(ByVal imageName As String) As Bitmap
    Dim assembly As Assembly = Assembly.GetExecutingAssembly()
    Dim stream As Stream = assembly.GetManifestResourceStream("CodeSnippetTester." & imageName)

    Return New Bitmap(stream)
End Function

public Bitmap LoadImage(string imageName)
{
    Assembly assembly = Assembly.GetExecutingAssembly();
    Stream stream = assembly.GetManifestResourceStream("your project name here" & imageName)
    return new Bitmap(stream);
}

In this procedure, a bitmap image is returned to Microsoft Office. When the procedure is called, the image is retrieved as an assembly resource and assigned to a Stream object. Finally the image is returned as a Bitmap object.

The getShowLabel attributeand the getShowImage attribute point to callback procedures that resolve to Boolean values. For example, setting the getShowLabel attribute to true causes the label for the combo box to appear when the control is displayed. If you want to set the value of the attribute explicitly, you use the showLabel attribute.

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 brief context-sensitive help about the item. Likewise, the supertip attribute (or the getSupertip attribute if you are pointing to a callback procedure) provides additional information about the object.

Another thing to notice about the getScreentip and the supertip attributes is that whenever you see an attribute prefixed by the word get, that attribute points to a callback procedure. Therefore, in the code, the getScreentip attribute points to the callback procedure named GetScreentip.

Note
You are not required to name callback procedures the same as the attribute with which they are used. You can just as easily use the following line of code: getScreentip="DoSomething". Also, you are not required to prefix attributes that point to callback procedures with the word get. For example, in the XML code, the onChange attribute points to a callback named OnChange.

The supertip attribute illustrates another aspect of control attributes. When you see the attribute without the get prefix, this typically indicates that you assign text to them explicitly. So in the case of the supertip attribute, the text is assigned directly instead of by a callback procedure. Again, there are exceptions such as the onAction attribute, where the attribute is not prefixed by the word get. To find more information about which attributes are assigned explicitly and which attributes point to callbacks, see the article Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3).

The keytip attribute assigns a KeyTip for the combo box. KeyTips are sometimes known as access keys or accelerators. KeyTips indicate what key to press to access program functionality when using the keyboard access systems. To use a KeyTip for a control on a custom tab, 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 example, below, the tab has a KeyTip equal to Z. The comboBox1 combo box has a KeyTip equal to A1. When the Office Fluent Ribbon is displayed, pressing the key combination ALT displays the Keytips for the tabs. Then pressing z brings the focus to the custom tab. And finally, pressing the key combination A+1 shifts the focus to the combo box.

Looking at the XML code, the visible attribute is set to a boolean value that determines whether the combo box is displayed on the Office Fluent Ribbon.

The next few attributes refer to the items in the combo box's drop-down list. For example, the getItemCount attribute returns the number of items in the drop-down list to Microsoft Office when the user clicks the combo box.

The getItemLabel and getItemImage attributes perform functions similar to the getLabel and getImage attributes, but for drop-down items. The getItemScreentip and getItemSupertip attributes specify screentip and supertips for the drop-down items.

Finally, as mentioned previously, the onChange attribute points to a callback procedure that executes when the user clicks an item in the combo box. 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 comboBox element has an onChange attribute. When the user clicks the combo box, the OnChange method, or callback procedure, is called. The code in the OnChange method gives the combo box its functionality. These procedures are called callbacks because when a user clicks an item in the drop-down list of the combo box, the action alerts Microsoft Office that the control needs its attention. Microsoft Office then calls back to the method defined by the onChange attribute and performs whatever action is contained in the method. The following paragraphs describe these callback procedures in detail.

The getText attribute points to the GetText callback procedure that specifies the text that is displayed in the combo box when the control is initially displayed.

Public Function GetText(ByVal control As IRibbonControl) As String
    Select Case control.Id
        Case "comboBox1" : strText = "Camera"
        Case "comboBox2" : strText = "Video"
    End Select
    Return strText
End Function

public string GetText(IRibbonControl control)
{
    Switch (control.Id)
    {
        case "comboBox1" : strText = "Camera"; break;
        case "comboBox2" : strText = "Video"; break;
        default : strText = "Camera"; break;
    }
    return strText
}

When Microsoft Office calls the GetText procedure, an IRibbonControl object representing the combo box is passed in. 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 default text in the combo box.

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 "combo box1" : strLabel = "Insert text."
        Case "combo box2" : strLabel = "Insert more text."
    End Select
    Return strLabel
End Function

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

Similar to the GetText callback procedure, when the GetLabel procedure is called by Microsoft Office, an IRibbonControl object representing the combo box is passed in. 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 combo box's label.

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 GetShowImage(ByVal control As IRibbonControl) As Boolean
    Return True
End Function

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

Public Function GetShowLabel(ByVal control As IRibbonControl) As Boolean
    Select Case (control.Id)
        Case "comboBox1" : Return True
        Case "comboBox2" : Return False
    End Select
End Function

public bool GetShowLabel(IRibbonControl control)
{
    bool boolShow = false;
    switch (control.Id)
    {
        case "comboBox1" : boolShow = true; break;
        case "comboBox2" : boolShow = false; break;
        default: boolShow = true; break;
    }
    return boolShow;
}

In the case of the GetShowLabel procedure, the 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 Microsoft Office.

The getScreentip attribute also points to a callback procedure. In this case, the procedure returns a string to Microsoft Office that is displayed when you move the mouse over the combo 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 getItemCount callback procedure returns an integer 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 GetItemCount(ByVal control As IRibbonControl) As Integer
    Return 3
End Function

public int GetShowImage(IRibbonControl control)
{
    return 3;
}

Next is the getItemImage attribute that points to the GetItemIamgee callback procedure.

Public Function GetItemImage(ByVal control As IRibbonControl, ByVal itemIndex As Integer) As Bitmap
    Dim imageName As String
    Select Case (itemIndex)
        Case 0 : imageName = "camera.bmp"
        Case 1 : imageName = "video.bmp"
        Case 2 : imageName = "mp3device.bmp"
    End Select

    Dim assembly As Assembly = Assembly.GetExecutingAssembly()
    Dim stream As Stream = assembly.GetManifestResourceStream("CodeSnippetTester." & imageName)

    Return New Bitmap(stream)
End Function

public Bitmap GetItemImage(IRibbonControl control, int itemIndex)
{
    string imageName;
    switch (itemIndex)
    {
        case 0 : imageName = "camera.bmp"; break;
        case 1 : imageName = "video.bmp"; break;
        case 2 : imageName = "mp3device.bmp"; break;
        default: imageName = "camera.bmp"; break;
    }

    Assembly assembly = Assembly.GetExecutingAssembly();
    Stream stream = assembly.GetManifestResourceStream("<your project name here>." & imageName)

    return new Bitmap(stream);
}

In this procedure, a bitmap image is returned to Microsoft Office. When the procedure is called the image is assigned to a variable. That image file is then retrieved as an assembly resource stream and assigned to a Stream object. Finally, the image is returned as a Bitmap object.

Next, the OnChange callback procedure is called when you click an item in the combo 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 OnChange(ByVal control As IRibbonControl, ByVal text As String)
    applicationObject.Range("A1").Value = _
      "You selected " & text
End Sub

public void OnChange(IRibbonControl control, string text)
{
    switch (control.Id)
    {
        case "combo box1":
            applicationObject.get_Range("A1:A1", missing).Value2 = "This combo box inserts text."; break;
        case "combo box2":
            applicationObject.get_Range("A1:A1", missing).Value2 = "This combo box 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. By using an add-in, you get application-level customization. This second option means that the customized Ribbon applies to the entire application regardless of which document is open.

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

To create a custom Office Fluent Ribbon with an Open XML Format 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 one method called GetCustomUI. You use this method to return the XML Ribbon customization code to Microsoft Office. Then, add programming procedures that give the custom Ribbon its functionality.

Adding Custom Combo Boxes to the Ribbon

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

To create the add-in solution:

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. At design time, it also makes it easier for you to install and uninstall the add-in.)

To interact with Excel 2007 and the Ribbon object model, you must add references to a type library.

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;
   

Next, you 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.

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

Next, you need to create an instance of Excel and add the Ribbon interface.

To access the host application 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 in this article based on the programming language. The GetCustomUI method tests the Id property of the control and inserts the text specific to that control into the worksheet at cell A1.

   Since this combobox 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.

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 RibbonDemoSetup, 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 ComboBox Demo tab appears. You also see the Group Demo group containing two combo boxes. Notice the custom image for the top combo box and the built-in image for the bottom combo box. In addition, notice the missing label for the bottom combo box. The label is missing because the getShowLabel attribute was set to false.

8. Click the Insert Text combo box.

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

   Figure 2. Click the Insert Text combo box to insert text into cell A1

   

9. Click the bottom combo box. The text in cell A1 changes.

10. Exit Excel.

11. 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.

• 2007 Office System Add-In: Icons Gallery

• Visual Studio Tools for Office Developer Portal

• Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3)

• Microsoft Office Developer Center: Office Fluent User Interface Developer Portal