Adding Custom DialogBoxLauncher Controls 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 dialogBoxLaunchers, 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 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 checkbox.

There are a number of custom and built-in controls, such as buttons, dialogBoxLaunchers, and combo boxes, that you can add 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, 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.

To add your own custom dialogBoxLaunchers to the Ribbon, 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 dialogBoxLaunchers, to the Office Fluent Ribbon by using XML elements to specify the type of component. For example, you add a single dialogBoxLauncher by using the dialogBoxLauncher element. You assign property values to the dialogBoxLauncher by using attributes such as the label attribute.

<customUI xmlns="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>

This sample adds a custom tab titled DialogBoxLauncher 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 custom button named button1 and a dialogBoxLauncher. The dialogBoxLauncher contains a button named button2.

Note

The dialogBoxLauncher control must contain a button, and must appear as the final element within the containing group element.

The dialogBoxLauncher is a container for the button. The button has properties defined for it by using attributes such as screentip and onAction. These properties are assigned explicitly by setting the attribute equal to a string, such as the screentip attribute, or indirectly by pointing to a programming code procedure such as the onAction attribute. 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

Examining the attributes of the dialogBoxLauncher's button, first you see the screentip attribute. ScreenTips are those small boxes that appear when you move the mouse pointer over an object on the Office Fluent Ribbon. They provide brief context-sensitive help about the item.

Finally the onAction attribute points to a callback procedure that executes when you click the button. This procedure is discussed in the next 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: onAction="DoSomething".

Assigning Functionality to Ribbon Components

In the previous XML sample, the onAction attribute points to a callback procedure. When the user clicks the dialogBoxLauncher button, 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 user clicks the button, 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.

Public Sub OnAction(ByVal control As IRibbonControl)
    Select Case control.id
        Case "button1"
            applicationObject.Range("A1").Value = "You 
            selected A button."
        Case "button2"
            MessageBox.Show("You can substitute your own 
            text here.", "dialogBoxLauncher")
    End Select
End Sub

public string OnAction(IRibbonControl control)
{
    switch (control.Id)
    {
        case "button1": 
            applicationObject.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: applicationObject.get_Range("A1:A1", 
        missing).Value2 = "There was a problem."; break;
    }
}

When you click the button in the dialogBoxLauncher, Microsoft Office is alerted. Microsoft Office then calls back to the add-in, triggering the OnAction callback procedure and passing the control object representing the button. The Id property of the control object is tested. Depending on its value, Microsoft Office executes one or the other switch statements. Specifically, if the value of the property is equal to button2, then the custom dialog box is displayed.

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.

Open the document as a ZIP file by changing the filename 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 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 DialogBoxLaunchers to the Ribbon

In the following procedure, you combine this information to create a custom tab containing a custom group, a custom dialogBoxLauncher and a button to the default Office Fluent Ribbon in Office Excel 2007. This demonstrates how to use a dialogBoxLauncher control on the Ribbon.

To create the add-in solution

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. 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, next you need to add references to the Microsoft.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;

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

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

To add the XML file as an embedded resources

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.

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

To access the host application 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 the Ribbon Components" based on the programming language.

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 DialogBoxLauncher Demo tab appears. You also see the Group Demo group containing a button and a dialogBoxLauncher in the lower right of the group.
Click the dialogBoxLauncher icon.

The dialog box is displayed as displayed in Figure 2.

Figure 2. Click the Insert Text dialogBoxLauncher to insert text in cell A1
Close the dialog box and then exit Excel.
In Visual Studio, in Solution Explorer, right-click RibbonDemoSetup, and then click Uninstall.

Watch the Video

Length: 5:29 | Size: 3.34 MB | Type: WMV

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
MSDN article: Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3)
The Ribbon page on the Microsoft Office Developer Center contains dozens of articles, blogs, downloads, and videos.