Customizing the 2007 Office Fluent User Interface with Visual Studio 2005 Tools for Office Second Edition

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: The Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System Second Edition makes customizing the 2007 Microsoft Office Fluent Ribbon simple by creating the infrastructure for you.

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.

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

One way to customize the Office Fluent Ribbon in Visual Studio is to manually create the XML and code in an add-in. However, the Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System Second Edition simplifies this task by creating the infrastructure for you.

See It Image of video introduction screen

Watch the Video

Length: 10:59 | Size: 11.5 MB | Type: WMV

Code It | Read It | Explore It

Code It

Whether you want to manually add the code to create a custom Office Fluent Ribbon, or use the default infrastructure created in Visual Studio 2005 Tools for Office add-in as a starting point for your own add projects, you use a combination of XML and programming code.

Adding Controls with XML and Programming Code

When you create a Microsoft Office application add-in in Microsoft Visual Studio 2005, Visual Studio 2005 Tools for Office adds default code and XML to create a rudimentary custom Office Fluent Ribbon. This structure serves a couple of important purposes. First, it creates the infrastructure to associate the project with the Microsoft Office application; second, it provides the core XML and programming code to add the basic components to the Office Fluent Ribbon. For example, the add-in inserts an XML file into the project that adds a custom tab, a custom group, and toggle button control as seen in Figure 1.

Figure 1. A sample modified Ribbon in Office Excel 2007

A sample modified Ribbon in Office Excel 2007

The project does this with the following XML:

<?xml version="1.0" encoding="utf-8" ?>
<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>

This sample adds a built-in tab titled Add-Ins to the Office Fluent Ribbon. It does this by assigning the name of the tab assigned by Microsoft Office to the idMso attribute. Attributes that end with the Mso suffix must point to a built-in control, command, or image. To add your own custom controls or images, just use the attribute name without the Mso suffix and point to the name of the control or image. For example, the toggleButton control in the previous code is a custom component as denoted by the id attribute. Also notice that the toggleButton is using a built-in image as denoted by the imageMso attribute. Thus, it is perfectly acceptable to mix built-in and custom attributes within a single component.

NoteNote

You can find the name Microsoft Office assigns to a particular toolbar control or command by doing the following: click the Microsoft office button, click applicationOptions, and on the Customize tab, move the mouse pointer over the particular component. The name assigned to the component by Microsoft Office appears in parentheses.

Continuing with the XML sample, a custom group and toggleButton control is then inserted into the Office Fluent Ribbon. You can then use attributes to set various properties on the control. Some of these properties are assigned by explicitly setting the property to a string such as the size and label attributes. By contrast, attributes can also point to callback procedures by setting the attribute equal to the name of the procedure as seen with the onAction attribute. Callback procedures are described in the Assigning Functionality to Ribbon Components section.

The toggleButton element also includes the screentip 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.

Loading the Office Fluent Ribbon Customization XML

To customize the Office Fluent Ribbon, you need to load the customization XML markup when the Microsoft Office application starts. To do this, the add-in project implements the IRibbonExtensibility interface that contains a single method named GetCustomUI.

There are different ways to include the XML into the project. For example, you can add a file to the project containing the markup as an embedded resource and then load the file in the GetCustomUI method. You can also hard-code the markup into a string in the method. Typically, in an add-in created by Visual Studio 2005 Tools for Office, you add Office Fluent Ribbon support, which inserts a customization file to the project. In the steps in the Read It section, you add an XML file and use a string to load the XML into Microsoft Office.

Assigning Functionality to Ribbon Components

In the previous XML sample, the onAction attribute points to a callback procedure. You use callback procedures to give the control its functionality. These procedures are called callbacks because when a user performs some action such as clicking a button or selecting an item in a combo box, the action alerts Microsoft Office that the control needs its attention. Microsoft Office then calls back to the method defined by the attribute and performs whatever action is contained in the method.

Visual Studio 2005 Tools for Office adds the following callback procedure to the project when you create the Office Fluent Ribbon add-in. Clicking the togglebutton control triggers the procedure.

Public Sub OnToggleButton1(ByVal control As Office.IRibbonControl, ByVal isPressed As Boolean)
    If isPressed Then
        MessageBox.Show("Pressed")
    Else
        MessageBox.Show("Released")
    End If
End Sub
public void OnToggleButton1(Office.IRibbonControl control, bool isPressed)
{
    if (isPressed)
        MessageBox.Show("Pressed");
    else
        MessageBox.Show("Released");
}

When Microsoft Office calls the OnToggleButton1 procedure, an IRibbonControl object representing the toggleButton is passed in. In addition, for a toggleButton control, the isPressed Boolean parameter is passed in that represents the pressed state of the control. For example, if the state of the button is pressed, the value of this parameter is true. When the button state is pressed, the button's image also shows up as depressed. The procedure tests the isPressed value and depending on its value, displays the corresponding string.

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.

  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 Office Fluent Ribbon is equally simple. In the preceding sections, I described the XML and callback procedure that Visual Studio 2005 Tools for Office adds when you create an add-in. This code works to provide the framework for adding your own customizations. To illustrate this, in the following section, I replace the existing code with the XML and callback procedures to add a custom button and a dialogBoxLauncher control to the Office Fluent Ribbon.

Adding a Custom DialogBoxLauncher Control to the Ribbon

In the following section, you combine the information discussed previously to create a custom tab containing a custom group and a custom button and dialogBoxLauncher control to the default Office Fluent Ribbon in Office Excel 2007. The button inserts text into the worksheet. The dialogBoxLauncher displays a dialog box that you can customize for your own purposes.

To create the project, perform the following steps.

To create the add-in solution

  1. Start Visual Studio 2005.

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

  3. (Microsoft Visual Basic only) In the New Project dialog box, in the Project Types pane, expand Visual Basic, click Office, click 2007 Add-ins, and then select Excel Add-in.

  4. (Microsoft Visual C# only) In the New Project dialog box, in the Project Types pane, expand Other Languages, click C#, click Office, click 2007 Add-ins, and then select Excel Add-in.

  5. Leave the default name and then click OK to create the project.

  6. In the Solution Explorer, right-click the project name ExcelAddIn1, point to Add, and click New Item.

  7. In the Add New Item dialog box, click Ribbon Support, leave the default name, and click Add.

    This adds two files to the project named Ribbon1.vb (Ribbon.cs) and Ribbon1.xml. The Ribbon1.vb (Ribbon1.cs) file contains the code to extend the Office Fluent Ribbon. The Ribbon1.xml file contains the elements and attributes that define the Office Fluent Ribbon.

  8. Click the Ribbon1.vb (Ribbon1.cs) tab.

  9. Click the + symbol in the left part of the code window to expand the Ribbon Callbacks region. Do the same for the Helpers region.

    The Ribbon1.vb (Ribbon1.cs) file contains the Ribbon1 class that contains the procedures to load the customization XML and add functionality to the Office Fluent Ribbon.

  10. Click the Ribbon1.xml tab.

    The Ribbon1.xml contains the XML elements and attributes that add components to the Office Fluent Ribbon and set properties on those components, respectively.

  11. When you create an Office Fluent Ribbon add-in in Visual Studio 2005 Tools for Office, a tab, group, and custom toggle button are added to the project. This markup and programming code give you a starting point to use when modifying the Office Fluent Ribbon.

To demonstrate that the project works, run the project.

To run the default project

  1. Click the Ribbon1.vb (Ribbon1.cs) tab.

  2. (Visual basic only) Highlight and uncomment the code between the ' Partial Public Class ThisAddIn and ' End Class statements.

  3. (C# only) Highlight and uncomment the code between the //public partial class ThisAddIn and // } statements.

    This code connects the project to the Office Fluent Ribbon.

  4. Press the F5 key to run the project and start Excel. This adds a built-in tab to the right of the existing tabs, a custom group, and togglebutton to the Office Fluent Ribbon.

  5. Click the Add-Ins tab.

  6. In the My Group group, click My Button. A dialog box is displayed indicating the current state of the togglebutton.

    In the following sections, you replace the existing markup and code.

    NoteNote

    The code that you are adding is also available in the Visual Studio 2005 Office Fluent Ribbon code snippets, which is a free download that you can get from 2007 Office System Sample: Visual Studio Code Snippets for the Office Fluent UI.

To demonstrate using custom XML markup and code to customize the Office Fluent Ribbon, replace the existing components in the project.

To replace the existing markup and code

  1. If it is not already visible, click the Ribbon1.vb (Ribbon1.cs) tab.

  2. Replace the GetCustomUI function with the following code:

    Public Function GetCustomUI(ByVal RibbonID As String) As String _
           Implements Microsoft.Office.Core.IRibbonExtensibility.GetCustomUI
    
    Return "<customUI http://schemas.microsoft.com/office/2006/01/customui"">" & _
              "<ribbon startFromScratch=""false"">" & _
                 "<tabs>" & _
                    "<tab id=""tab1"" label=""DialogBoxLauncher Demo"" >" & _
                       "<group id=""group1"" label=""Demo Group"">" & _
                          "<button id=""button1"" " & _
                             "imageMso=""BevelTextGallery"" " & _
                             "label=""A Button"" " & _
                             "onAction=""OnAction"" " & _
                             "size=""large"" />" & _
                          "<dialogBoxLauncher>" & _
                             "<button id=""button2"" " & _
                                "screentip=""Launched by the DialogBoxLauncher control."" " & _
                                "onAction=""OnAction"" />" & _
                          "</dialogBoxLauncher>" & _
                       "</group>" & _
                    "</tab>" & _
                 "</tabs>" & _
              "</ribbon>" & _
           "</customUI>"
    End Function
    
    public string GetCustomUI(string RibbonID)
    {
       return @"<customUI http://schemas.microsoft.com/office/2006/01/customui"">
                   <ribbon startFromScratch=""false"">
                       <tabs>
                           <tab id=""tab1"" label=""DialogBoxLauncher Demo"" keytip=""x"" >
                               <group id=""group1"" label=""Demo Group"">
                                   <button id=""button1"" 
                                       imageMso=""BevelTextGallery"" 
                                       label=""A Button"" 
                                       onAction=""OnAction"" 
                                       size=""large"" />
                                   <dialogBoxLauncher>
                                       <button id=""button2"" 
                                           screentip=""Launched by the DialogBoxLauncher control."" 
                                           onAction=""OnAction"" />
                                    </dialogBoxLauncher>
                                </group>
                            </tab>
                       </tabs>
                   </ribbon>
               </customUI>";
    }
    

    The GetCustomUI function now returns the XML markup in a string to Microsoft Office. This markup creates a custom tab, group, button, and dialogBoxLauncher control to the Office Fluent Ribbon.

    NoteNote

    For more information about adding the dialogBoxLauncher control, see the Visual How To Video: Adding Custom DialogBoxLauncher Controls to the 2007 Office Fluent User Interface.

  3. Next, replace the code in the Ribbon Callbacks region with the following:

    Public Sub OnAction(ByVal control As Microsoft.Office.Core.IRibbonControl)
        Select Case control.id
            Case "button1"
                Globals.ThisAddin.Application.Range("A1").Value = "You selected A button."
            Case "button2"
                MessageBox.Show("You can substitute your own text here.", "dialogBoxLauncher")
        End Select
    End Sub
    
    object missing = Type.Missing;
    public void OnAction(Microsoft.Office.Core.IRibbonControl control)
    {
        switch (control.Id)
        {
            case "button1" :
                 Globals.ThisAddIn.Application.get_Range("A1:A1", missing).Value2 = "You selected A button."; break;
            case "button2" :
                 MessageBox.Show("You can substitute your own text here.", "dialogBoxLauncher"); break;
            default :
                 MessageBox.Show("There is a problem."); break;
        }
    }
    

    When Microsoft Office calls this procedure, it passes in an IRibbonControl representing the control that called it. The procedure then tests the Id property of the control and depending on its value either inserts text into the worksheet or displays a dialog box.

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. Press F5. Office Excel 2007 starts.

The DialogBoxLauncher Demo tab is displayed. Clicking the tab, you see the Demo Group group containing a button. Also, in the lower right corner of the group, you see an icon. This is the dialogBoxLauncher control.

  1. Click the A Button button. Excel inserts text into the worksheet at cell A1.

  2. Click the dialogBoxLauncher icon. A dialog box is displayed as displayed in Figure 2.

    Figure 2. After clicking the controls on the DialogBoxLauncher Demo tab

    Clicking the DialogBoxLauncher Demo control

To remove the add-in from Excel

  1. Click the Microsoft Office button, click Excel Options, and then click the Add-Ins tab.

  2. In the Manage drop-down list, click COM Add-ins, and then click the Go button.

  3. Select ExcelAddIn1, click the Remove button, and then click OK.

  4. Exit Excel.

Explore It

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