Adding Custom DialogBoxLauncher Controls 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 dialogBoxLaunchers, 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
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.
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:
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.
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
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:
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.
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
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
Next, you must create the file that adds the components and sets the property for those components.
To create the Ribbon customization XML file
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
You need to create an instance of Excel and add the Ribbon interface.
To access the host application and work with the Ribbon
Now you are ready to run the project.
To test the project
Length: 5:29 | Size: 3.34 MB | Type: WMV
There are a number of resources on customizing the Office Fluent user interface.