Customizing the 2007 Office Fluent Ribbon for Developers (Part 2 of 3)
Summary: This article is the companion to the part one and part three articles of the same name. This article contains detailed reference material about the controls and method signatures of the Ribbon user interface. (11 printed pages)
Frank Rice, Microsoft Corporation
Ken Getz, MCW Technologies, LLC
Published: May 2006
Updated: November 2006
Applies to: 2007 Microsoft Office Suites, Microsoft Office Access 2007, Microsoft Office Excel 2007, Microsoft Office PowerPoint 2007, Microsoft Office Outlook 2007, Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office System
Contents
Overview
Descriptions, Attributes, and Child Information for the Ribbon Controls
Conclusion
Additional Resources
Overview
The Microsoft Office Fluent user interface (UI) feature replaces the current system of layered menus, toolbars, and task panes in Microsoft Office applications with a simpler system of interfaces optimized for efficiency and discoverability. UI extensibility introduces an innovative model that you can use to enhance the user experience. You use extensible markup language (XML) and one of several conventional programming languages to manipulate the components that make up the Fluent UI. The following sections define and describe the components, methods, and attributes that you use to customize the Fluent UI. With this information, you can create a rich, intuitive experience that maximizes efficiency and productivity for your customers.
Descriptions, Attributes, and Child Information for the Ribbon Controls
The following XML reference contains details about the Ribbon control markup. There are two main sections: details about the XML that is specific to the Ribbon, and details about the XML for basic controls.
Ribbon XML
The following XML reference is specific to the Ribbon.
customUI
The root tag of all Ribbon customizations.
Attributes
Common: None
Table 1. Attributes and methods of Fluent UI containers
Attribute or method |
Type or action |
Description |
|---|---|---|
xmlns |
String |
Must be set to http://schemas.microsoft.com/office/2006/01/customui |
onLoad |
callback |
Passes a Ribbon parameter to the callback procedure as the Ribbon loads. This enables the associated code to store a reference to the Ribbon for later use. See the section "Dynamically Updating the Fluent UI" in the article Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3). |
loadImage |
callback |
Enables you to create a single procedure that loads all of the images required by the Ribbon. See the section "Loading Images" in the article Customizing the 2007 Office Fluent Ribbon for Developers (Part 1 of 3). |
Children
commands, ribbon
commands
Contains globally repurposed commands.
Attributes
None
Children
command
command
Represents a command that you are repurposing.
Attributes
Common: enabled, getEnabled, idMso (required), onAction
Children
None
ribbon
Represents the Fluent UI.
Attributes
Table 2. Attribute of the Fluent UI
Attribute |
Values |
Description |
|---|---|---|
startFromScratch |
True, False, 1, 0 |
If set to True, the Ribbon hides built-in main tabs and displays a minimal File menu. |
Children
contextualTabs, officeMenu, qat, tabs
contextualTabs
The tabs that are displayed when certain object types are selected, such as the Picture tools.
Attributes
None
Children
tabSet
tabSet
Represents a collection of tab controls.
Attributes
Common: getVisible, idMso (required), visible
Children
tab
qat
The Quick Access Toolbar. Can be authored only in start from scratch mode.
Attributes
None
Children
documentControls, sharedControls
sharedControls
Controls that are shared across documents (use documentControls, not sharedControls, in general).
Attributes
None
Children
button, control, separator
documentControls
Controls that are specific to a document.
Attributes
None
Children
button, control, separator
officeMenu
Controls that are contained in the Microsoft Office menu.
Attributes
None
Children
button, checkbox, control, dynamicMenu, gallery, menu, menuSeparator, splitButton, toggleButton
tabs
Contains tab controls.
Attributes
None
Children
tab
tab
Represents a tab on the Ribbon.
Attributes
Common: getKeytip, getLabel, getVisible, id, idMso, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, tag, visible
Children
group
group
Represents a group within a tab on the Ribbon.
Attributes
Common: getImage, getImageMso, getKeytip, getLabel, getScreentip, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, screentip, supertip, visible
Children
box, button, buttonGroup, checkBox, comboBox, control, dialogBoxLauncher, dropDown, editBox, gallery, labelControl, menu, separator, splitButton, toggleButton
Basic Controls
The following XML reference describes basic controls.
box
Arranges controls within a group.
Attributes
Common: getVisible, id, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, visible
Table 3. Attribute of box
Attribute |
Values |
Description |
|---|---|---|
boxStyle |
Horizontal, Vertical |
Determines the visual flow of the controls inside the box. |
Children
box, button, buttonGroup, checkBox, comboBox, control, dropdown, dynamicMenu, editBox, gallery, labelControl, menu, splitButton, toggleButton
button
Represents a button control.
Attributes
Common: description, enabled, getDescription, getEnabled, getImage, getImageMso, getKeytip, getLabel, getScreentip, getShowImage, getShowLabel, getSize, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, onAction, screentip, showImage, showLabel, size, supertip, tag, visible
Children
None
buttonGroup
Represents a grouping of buttons.
Attributes
Common: getVisible, id, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, visible
Children
button, control, dynamicMenu, gallery, menu, splitButton, toggleButton
checkBox
Represents a check box control.
Attributes
Common: description, enabled, getDescription, getEnabled, getKeytip, getLabel, getScreentip, getSupertip, getVisible, id, idMso, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, onAction, screentip, supertip, tag, visible
Table 4. Attribute of checkBox
Attribute |
Type or Action |
Description |
|---|---|---|
getPressed |
callback |
Enables you to specify whether the checkBox control is pressed. |
Children
None
comboBox
Represents a combo box control.
Attributes
Common: enabled, getEnabled, getImage, getImageMso, getKeytip, getLabel, getScreentip, getShowImage, getShowLabel, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, label, screentip, showImage, showLabel, supertip, tag, visible
Shared with editBox: getText, maxLength, onChange, sizeString
Table 5. Attributes and methods of comboBox
Method |
Attribute or method |
Description |
|---|---|---|
getItemCount |
callback |
Gets the number of items in this comboBox. |
getItemID |
callback |
Gets the ID of this item. |
getItemImage |
callback |
Gets the image of this item. |
getItemLabel |
callback |
Gets the label of this item. |
getItemScreentip |
callback |
Gets the ScreenTip of this item. |
getItemSupertip |
callback |
Gets the Enhanced ScreenTip of this item. |
showItemImage |
True, False, 1, 0 |
Specifies whether to display the item image. |
Children
item
dialogBoxLauncher
Contains the dialog box launcher for a group. A group can contain only a single dialogBoxLauncher control. This control must contain a button control, and must appear as the final element within the containing group element.
Attributes
None
Children
button (required)
dropDown
Represents a drop-down list box.
Attributes
Common: enabled, getEnabled, getImage, getImageMso, getKeytip, getLabel, getScreentip, getShowImage, getShowLabel, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, onAction, screentip, showImage, showLabel, supertip, tag, visible
Shared with comboBox: getItemCount, getItemID, getItemImage, getItemLabel, getItemScreentip, getItemSupertip, showItemImage
Shared with editBox: sizeString
Table 6. Attributes and methods of dropDown
Method |
Action |
Description |
|---|---|---|
getSelectedItemID |
callback |
Asks for the item that should be selected by ID. Specify either this attribute or the getSelectedItemIndex attribute, but not both. |
getSelectedItemIndex |
callback |
Asks for the item that should be selected by index. Specify either this attribute or the getSelectedItemId attribute, but not both. |
showItemLabel |
True, False, 1, 0 |
Indicates whether items should display labels. |
Children
item
dynamicMenu
Represents a menu that is created at run time.
Attributes
Common: description, enabled, getDescription, getEnabled, getImage, getImageMso, getKeytip, getLabel, getScreentip, getShowImage, getShowLabel, getSize, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, screentip, showImage, showLabel, supertip, tag, visible
Table 7. Method of dynamicMenu
Method |
Action |
Description |
|---|---|---|
getContent |
callback |
Gets an XML string that contains the contents of this dynamic menu. |
The getContent method must return XML similar to the following to populate the menu.
<menu xmlns="http://schemas.microsoft.com/office/2006/01/customui">
<button id="dynaButton" label="Button"
onAction="OnAction" imageMso="FoxPro"/>
<toggleButton id="dynaToggleButton" label="Toggle Button"
onAction="OnToggleAction" image="logo.bmp"/>
<menuSeparator id="div2"/>
<dynamicMenu id="subMenu" label="Sub Menu" getContent="GetSubContent" />
</menu>
Children
Same as a menu, but is populated by using the getContent callback.
editBox
Represents an edit box control.
Attributes
Common: enabled, getEnabled, getImage, getImageMso, getKeytip, getLabel, getScreentip, getShowImage, getShowLabel, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, screentip, showImage, showLabel, supertip, tag, visible
Table 8. Attributes and methods of editBox
Attribute or method |
Type or action |
Description |
|---|---|---|
getText |
callback |
Gets the text to display in the edit box. |
maxLength |
Integer |
The maximum size of the string, in characters, that the user may type in the edit box. |
onChange |
callback |
Called when the value in the edit box is changed and committed by the user. |
sizeString |
String |
A string, such as "wwwwwwwwww", that determines the size of the edit box. |
Children
None
gallery
Represents a gallery control.
Attributes
Common: description, enabled, getDescription, getEnabled, getImage, getImageMso, getKeytip, getLabel, getScreentip, getShowImage, getShowLabel, getSize, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, onAction, screentip, showImage, showLabel, size, supertip, tag, visible
Shared with comboBox: getItemCount, getItemID, getItemImage, getItemLabel, getItemScreentip, getItemSupertip, showItemImage, showItemLabel
Shared with dropDown: getSelectedItemID, getSelectedItemIndex
Shared with editBox: sizeString
Table 9. Attributes and methods of gallery
Attribute or method |
Type or action |
Description |
|---|---|---|
columns |
Integer |
The number of columns to display in this gallery. |
getItemHeight |
callback |
Asks for the height of items, in pixels. |
getItemWidth |
callback |
Asks for the width of items, in pixels. |
itemHeight |
Integer |
The height of items, in pixels. |
itemWidth |
Integer |
The width of items, in pixels. |
rows |
Integer |
The number of rows to display in this gallery. |
Children
item, button. Buttons must be listed after the items, and all buttons appear at the bottom of the gallery.
item
A static gallery, dropDown, or comboBox item. If you specify static items, you cannot also specify dynamic items.
Attributes
Common: id, image, imageMso, label, screentip, supertip
Children
None
labelControl
Represents a label control.
Attributes
Common: enabled, getEnabled, getLabel, getScreentip, getShowLabel, getSupertip, getVisible, id, idMso, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, label, screentip, showLabel, supertip, tag, visible
Children
None
menu
Represents a menu control.
Attributes
Common: description, enabled, getDescription, getEnabled, getImage, getImageMso, getKeytip, getLabel, getScreentip, getShowImage, getShowLabel, getSize, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, screentip, showImage, showLabel, size, supertip, tag, visible
Table 10. Attribute of menu
Attribute |
Values |
Description |
|---|---|---|
itemSize |
Normal, Large |
The size of items inside the menu. Large menu items show their Description property. |
Children
button, checkBox, control, dynamicMenu, gallery, menu, menuSeparator, splitButton, toggleButton
menuSeparator
Represents a separator line (which can optionally include a text label) between menu items.
Attributes
Common: id, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ
Table 11. Attribute and method of menuSeparator
Attribute |
Type or action |
Description |
|---|---|---|
title |
String |
The text for this separator. |
getTitle |
callback |
Callback for this separator's text. |
Children
None
separator
Represents a separator line between controls.
Attributes
Common: getVisible, id, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, visible
Children
None
splitButton
Represents a split button control.
Attributes
Common: enabled, getEnabled, getKeytip, getShowLabel, getSize, getSupertip, getVisible, id, idMso, idQ, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, showLabel (determines whether the button or toggle button control displays its label), size, supertip, tag, visible
Children
button or toggleButton (required, only one permitted, and must appear before the menu): The main button for the split button control.
menu (required, and only one permitted): The menu of a split button control.
toggleButton
Represents a toggle button control.
Attributes
Common: description, enabled, getDescription, getEnabled, getImage, getImageMso, getKeytip, getLabel, getPressed, getScreentip, getShowImage, getShowLabel, getSize, getSupertip, getVisible, id, idMso, idQ, image, imageMso, insertAfterMso, insertAfterQ, insertBeforeMso, insertBeforeQ, keytip, label, onAction, screentip, showImage, showLabel, size, supertip, tag, visible
Table 12. Attribute of toggleButton
Attribute |
Type or action |
Description |
|---|---|---|
getPressed |
callback |
Enables you to specify whether the toggle button control is pressed. |
Children
None
Conclusion
The articles that make up this set provide you with the information you need to produce professional-looking solutions tailored to the needs of your customers. The customization samples presented in the first article can be used as a jumping-off point for creating a UI that places the controls and options that are most important to your customers within easy reach. The reference information described in this article gives you detailed control over the look and feel of the Fluent UI. The third part of this series of articles contains a list of frequently asked questions. By applying the information presented here to your own applications, you can create innovative, attractive solutions that set you apart from your competition.
Additional Resources
To learn more about the products and technologies mentioned or used in this article, see these resources: