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

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" loadImage="LoadImage" >
   <ribbon startFromScratch="false">
      <tabs>
         <tab id="tab1" label="Gallery Demo" keytip="x" >
            <group id="group1" label="Demo Group">
               <gallery id="gallery1" 
                  columns="2" 
                  rows="2" 
                  getEnabled="GetEnabled" 
                  getScreentip="GetScreenTip" 
                  supertip="This is the super tip." 
                  getKeytip="GetKeyTip" 
                  getShowImage="GetShowImage" 
                  getShowLabel="GetShowLabel"
                  getLabel="GetLabel" 
                  getSize="GetSize" 
                  image="internetconnection.bmp" 
                  getItemCount="GetItemCount" 
                  getItemHeight="GetItemHeight" 
                  getItemWidth="GetItemWidth" 
                  getItemImage="GetItemImage" 
                  getItemLabel="GetItemLabel" 
                  getItemScreentip="GetItemScreenTip" 
                  getItemSupertip="GetItemSuperTip"  
                  onAction="galleryOnAction" >
                     <item id="item1" />
                     <item id="item2" />
                     <item id="item3" />
                     <item id="item4" />
                     <button id="button1" getLabel="GetLabel" 
                        onAction="buttonOnAction" 
                        imageMso="HappyFace" />
               </gallery>
            </group>
         </tab>
      </tabs>
   </ribbon>
</customUI>

This sample adds a custom tab titled Gallery 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 a gallery control named gallery1. In addition to the items contained in the gallery, the code defines a button named button1. The gallery and button have properties defined for them by using attributes such as columns, rows, and supertip. 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 such as the getEnabled attribute. The following figure shows the result of applying this XML to the Office Fluent Ribbon in Microsoft Office Excel 2007:

When you see an attribute prefixed by the word get, this tells you that the attribute points to a callback procedure. However, an attribute does not have to be prefixed by get to reference a callback procedure. One example is the onAction attribute that will be discussed later.

You can differentiate built-in components from custom components based on the Mso suffix. Looking at the sample, you see that some attributes have the Mso suffix, such as the imageMso attribute for the button, and some attributes do not. Attributes that do not have the Mso qualifier, such as the id attribute of the gallery element, are custom controls. Attributes with the Mso suffix refer to built-in controls, commands, and images.

Looking at the other attributes of the gallery control, the columns and rows attributes specify the number of columns and rows, respectively, for the list of items in the gallery control's drop-down list.

Next, you see the getEnabled attribute. This attribute points to a callback procedure that returns True to indicate that the gallery is available for use. Setting the attribute to False grays out the control, indicating that the gallery is not active. Callback procedures are described in the Assigning Functionality to Ribbon Components section.

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: getEnabled="DoSomething".

Next, you see the getScreentip attribute. ScreenTips are the 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.

The supertip attribute illustrates another aspect of control attributes. When an attribute lacks the get prefix, this typically indicates that you assign text to the attribute explicitly. So 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. 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 getKeytip attribute points to a callback procedure that assigns a KeyTip for the gallery control. KeyTips are also called access keys or keyboard shortcuts. KeyTips indicate which key combination to press to access program functionality from the keyboard. 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 (You can see the KeyTip for the tabs by pressing the ALT key). Then you assign a KeyTip for the control. For example, in the XML code sample, the tab1 tab has a KeyTip equal to x. The gallery1 gallery control resolves to a KeyTip equal to GL. When the Office Fluent Ribbon is displayed, pressing the key combination ALT displays the access keys for the tabs. Then pressing x brings the focus to the custom tab. And finally, pressing the key combination G+L shifts the focus to the gallery.

The getShowLabel attribute and 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 gallery to appear when the control is displayed. If you want to set the value of the attribute explicitly, you use the showLabel attribute.

The getLabel attribute also points to a callback procedure that returns the label that is displayed for the gallery. Next, the image attribute for gallery1 specifies a custom image for the control. Likewise, the imageMso attribute for button1 specifies a built-in image for the button. For a spreadsheet of built-in images, see 2007 Office System Add-In: Icons Gallery.

You can use the image and imageMso attributes 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.

Returning to the XML sample, all of the attributes that contain the word Item relate to the items that are displayed when you click the arrow on the gallery control; these attributes are self-explanatory. For example, the getItemCount attribute specifies the number of items that are displayed in the drop-down list when you click the gallery control. The getItemHeight and getItemWidth attributes specify the height and width dimensions of the items in the drop-down list. And the getItemScreentip and getItemSupertip attributes specify screen tips and super tips for the drop-down items.

The onAction attribute points to a callback procedure that is triggered when you click an item in the gallery. This procedure is discussed in the next section.

And finally, the button element adds a button to the gallery. You can tell that the button uses an image that is built into Microsoft Office because of the use of the imageMso attribute.

In the previous XML sample, several of the attributes point to callback procedures. For example, the gallery element has an onAction attribute. When the user clicks an item in the drop-down, the OnAction method, or callback procedure, is called. The code in the OnAction method gives the gallery its functionality. These procedures are called callbacks because when a user clicks an item in the drop-down list, the action alerts Microsoft Office that the control needs its 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 some of these callback procedures.

To get an idea how a basic callback works, look at the GetLabel function.

Public Function GetLabel(ByVal control As IRibbonControl) As String
    Select Case control.Id
       Case "gallery1" : strText = "Select a Device:"
       Case "button1" : strText "Button in Gallery"
    End Select
    Return strText
End Function

public string GetLabel(IRibbonControl control)
{
    private string strText = "";
    switch (control.Id)
    {
       case "gallery1" : strText = "Select a Device"; break;
       case "button1" : strText = "Button in Gallery"; break;
       default : strText = "Select a Device"; break;
    }
    return strText;
}

When Microsoft Office calls the GetLabel procedure, an IRibbonControl object representing the gallery is passed in. The procedure tests the Id property of the object and, depending on its value, returns the text label of the control. Microsoft Office then displays that text label with the control.

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
    Return True
End Function

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

The getItemImage attribute points to the GetItemImage 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 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.

The GetSize procedure is called from the getSize attribute and determines the size of the control.

Public Function GetSize(ByVal control As IRibbonControl) As RibbonControlSize
    Select Case control.Id
        Case "gallery1" : Return RibbonControlSize.RibbonControlSizeLarge
        Case "button1" : Return RibbonControlSize.RibbonControlSizeRegular
    End Select
End Function

public RibbonControlSize GetSize(IRibbonControl control)
{
    RibbonControlSize ctrlSize;
    switch (control.Id)
    {
        case "gallery1" : ctrlSize = RibbonControlSize.RibbonControlSizeLarge; break;
        case "button1" : ctrlSize = RibbonControlSize.RibbonControlSizeRegular; break;
        default: ctrlSize = RibbonControlSize.RibbonControlSizeRegular; break;
    }
    return ctrlSize;
}

The procedure tests the Id property of the calling control and depending on its value, sets its size from one of the choices from the RibbonControlSize enumeration.

Next, the galleryOnAction callback procedure is called when you click an item in the gallery. When triggered, Microsoft Office passes in the control object, the id of the item that you clicked, and the index number of the item. The procedure tests the selectedIndex property of the gallery and inserts text specific to that control into the A1 cell in the worksheet.

Public Sub galleryOnAction(ByVal control As IRibbonControl, ByVal selectedId As String, _
    ByVal selectedIndex As Integer)
    Select Case selectedIndex
        Case 0
            applicationObject.Range("A1").Value = "You clicked a camera."
        Case 1
            applicationObject.Range("A1").Value = "You clicked a video player."
        Case 2
            applicationObject.Range("A1").Value = "You clicked an mp3 device."
        Case 3
            applicationObject.Range("A1").Value = "You clicked a cell phone."
    End Select
End Sub

public void galleryOnAction(IRibbonControl control, string selectedId, int selectedIndex)
{
    switch (selectedIndex)
    {
        case 0:
            applicationObject.get_Range("A1:A1", missing).Value2 = "You clicked a camera."; break;
        case 1:
            applicationObject.get_Range("A1:A1", missing).Value2 = "You clicked a video player."; break;
        case 2:
            applicationObject.get_Range("A1:A1", missing).Value2 = "You clicked an mp3 device."; break;
        case 3:
            applicationObject.get_Range("A1:A1", missing).Value2 = "You clicked a cell phone."; break;
        default:
            applicationObject.get_Range("A1:A1", missing).Value2 = "There was a problem with your selection."; break;
    }
}

When you click the button, Microsoft Office calls the buttonOnAction procedure, which then displays a dialog box.

Public Sub buttonOnAction(ByVal control As IRibbonControl)
    MessageBox.Show("Hello world.")
End Sub

public void buttonOnAction(IRibbonControl control)
{
    MessageBox.Show("Hello world.");
}

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.

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

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.

   Visual Basic

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

   C#

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

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.

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.

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.

   Visual Basic

   Private applicationObject As Excel.Application

   C#

   private Excel.Application applicationObject;

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

   Visual Basic

   applicationObject = DirectCast(application, Excel.Application)

   C#

   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.

   Visual Basic

   Implements Extensibility.IDTExtensibility2, IRibbonExtensibility

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

   C#

   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.

   Visual Basic

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

   C#

   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 you are using. The GetCustomUI method tests the Id property of the control and inserts the text specific to that control into the worksheet at cell A1.

   Because the gallery 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 drop the image file onto the Resources tab.

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 Gallery Demo tab appears. You also see the Group Demo group containing the gallery. Notice the custom image for the gallery control.

8. Click the down arrow in the control. Notice the four items and the button with the built-in image.

9. Click the Video Player item.

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

   Figure 2. Click an item in the gallery to insert text into cell A1
   
   

10. Click the gallery again and then click the button. The dialog box is displayed as shown in Figure 3.

    Figure 3. Clicking the button displays a dialog box
    
    

11. Exit Excel.

12. In Visual Studio, in Solution Explorer, right-click RibbonDemoSetup, and then click Uninstall.