Add-in Express™
for Microsoft® Office and .netAdd-in Express Home > Add-in Express for Office and .NET > Online Guide > Add-in Express components > Office Ribbon components
Office Ribbon UI components
Office 2007 presented a new Ribbon user interface. Microsoft states that the interface makes it easier and quicker for users to achieve the wanted results.
You extend this interface by using the XML markup that the COM add-in returns to the host application through an appropriate interface when your add-in is loaded into
the host version supporting the Office Ribbon UI.
Add-in Express Toolbox provides some 50 components for customizing the Microsoft Office 2010 and 2007 Ribbon that undertake the task of creating the markup. Also, there are 5 visual designers
that allow creating the UI of your add-in: Ribbon Tab (ADXRibbonTab), Ribbon Office Menu (ADXRibbonOfficeMenu), Quick Access Toolbar
(ADXRibbonQuickAccessToolbar), Ribbon BackstageView (ADXBackStageView), and Ribbon Context Menu
(ADXRibbonContextMenu).
In Office 2010, Microsoft abandoned the Office Button (introduced in Office 2007) in favor of the File Tab (also known as Backstage View).
To provide some sort of compatibility for you, when the add-in is being loaded, ADXRibbonOfficeMenu maps your controls to the File tab
unless you use ADXBackStageView
components in your project; otherwise, all the controls you add to ADXRibbonOfficeMenu are ignored when Office 2010 loads your add-in.
Microsoft require developers to use the StartFromScratch parameter (see the StartFromScratch property of the add-in module) when
customizing the Quick Access Toolbar.
See also Developing Outlook COM add-in, Writing Microsoft Office COM add-in.
How Office Ribbon controls are created?
When your add-in is being loaded by the host application supporting the Ribbon UI, the very first event received by the add-in is
the OnRibbonBeforeCreate event of the add-in module (in a pre-Ribbon Office application, the very first event is OnAddinInitialize).
This is the only event in which you can add/remove/modify the Ribbon components onto/from/on the add-in module.
Then Add-in Express generates the XML markup reflecting the settings of the components and raises the OnRibbonBeforeLoad event.
In that event, you can modify the generated markup, say, by adding XML tags generating extra Ribbon controls.
Finally, the markup is passed to Office and the add-in module fires the OnRibbonLoaded event. In the event parameters, you get an object
of the AddinExpress.MSO.IRibbonUI type that allows invalidating a control; you call the corresponding methods when you need the
Ribbon to re-draw the control. Also, in Office 2010 only, you can call a method activating a tab.
Remember, the Ribbon designers perform the XML-schema validation automatically, so from time to time you may run into the situation
when you cannot add a control to some level. It is a restriction of the Ribbon XML-schema.
Still, we recommend turning on the Ribbon XML validation mechanism through the UI of the host application of your add-in; you need
to look for a checkbox named "Show add-in user interface errors".
Referring to built-in Ribbon controls
All built-in Ribbon controls are identified by their IDs. While the ID of a command bar control is an integer, the ID of a built-in Ribbon control is a string.
IDs of built-in Ribbon controls can be downloaded on the Microsoft web site, for Office 2007, see
here ;
for Office 2010, see this page.
The download installs Excel files; the Control Name column of each contains the IDs of almost all built-in Ribbon controls for the corresponding Ribbon.
Add-in Express components provide the IdMso property; if you leave it empty the component will create a custom control.
To refer to a built-in Ribbon control, you set the IdMso property of the component to the ID of the built-in control. For instance,
you can add a custom group to a built-in tab. To do this, you add a Ribbon tab component onto the add-in module and set its IdMso
to the ID of the required built-in tab. Then you add your custom group to the tab and populate it with controls. Note that the
Ribbon does not allow adding a custom control to a built-in group.
Intercepting built-in Ribbon controls
You use the Ribbon Command (ADXRibbonCommand) component to override the default action of a built-in Ribbon control. Note that the
Ribbon allows intercepting only buttons, toggle buttons and check boxes; see the ActionTarget property of the component. You specify the ID of a
built-in Ribbon control to be intercepted in the IdMso property of the component. To get such an ID, see
Referring to built-in Ribbon controls.
Another use of the component is demonstrated by the screenshot below; this is how you disable the Copy command in Word 2007-2010:
Positioning Ribbon controls
Every Ribbon component provides the InsertBeforeId, InsertBeforeIdMso and InsertAfterId, InsertAfterIdMso properties.
You use the InsertBeforeId and InsertAfterId properties to position the control among other controls created by your add-in,
just specify the Id of the corresponding components in any of these properties. The InsertBeforeIdMso and InsertAfterIdMso
properties allow positioning the control among built-in Ribbon controls (see also Referring to built-in
Ribbon controls).
Creating Ribbon controls at run-time
You cannot create Ribbon controls at run-time because Ribbon is a static thing from birth; but see How Ribbon controls are created?)
The only control providing any dynamism is Dynamic Menu if the ADXRibbonMenu.Dynamic property is set to True at design-time, the component will generate the OnCreate event allowing
creating menu items at run-time. For other control types, you can only imitate that dynamism by setting the Visible property of a Ribbon control.
Properties and events of Ribbon components
Add-in Express components implement two schemas of refreshing Ribbon controls.
The simple schema allows you to change a property of the Ribbon component and the component will supply it to the Ribbon UI whenever it
requests that property. This mechanism is an ideal when you need to display static or almost static things such as a button caption that
doesn't change or changes across all windows showing the button, say in Outlook inspectors or Word documents. This works because Add-in Express
supplies the same value for the property whenever the Ribbon UI invokes a corresponding callback function.
However, if you need to have a full control over the UI, say, when you need to show different captions of a Ribbon button in different
Inspector windows or Word documents, you can use the OnPropertyChanging event provided by all Ribbon components. That event occurs when the Ribbon
expects that you can supply a new value for a property of the control. The event allows you to learn the current context, i.e. the current
window showing your controls, such as Outlook.Inspector, Word.Document, etc. It also allows you to get the property being changed and its
current value. Finally, you can change that value as required.
Sharing Ribbon controls across multiple add-ins
First off, you assign the same string value to the AddinModule.Namespace property of every add-in that will share your controls.
This makes Add-in Express add two xmlns attributes to the customUI tag in the resulting XML markup:
- xmlns:default="%ProgId of your add-in, see the ProgID attribute of the AddinModule class%"
- xmlns:shared="%the value of the AddinModule.Namespace property%".
Originally, all Ribbon controls are located in the default namespace (id="%Ribbon control's id%" or idQ="default:%Ribbon control's id%")
and you have full control over them via the callbacks provided by Add-in Express. When you specify the Namespace property, Add-in Express
changes the markup to use idQ's instead of id's.
Then, in all add-ins that are to share a control, for the control with the same Id (you can change the Id's to match),
you set the Shared property to true. For a control whose Shared property is true, Add-in Express changes its idQ to use
the shared namespace (idQ="shared:%Ribbon control's id%") instead of the default one. Also, for such Ribbon controls, Add-in Express
cuts out all callbacks and replaces them with "static" versions of the attributes. Say, getVisible="getVisible_CallBack" will be replaced
with visible="%value%".
The shareable Ribbon controls are the following container controls:
- Ribbon Tab - ADXRibbonTab
- Ribbon Box - ADXRibbonBox
- Ribbon Group - ADXRibbonGroup
- Ribbon Button Group - ADXRibbonButtonGroup
When referring to a shared Ribbon control in the BeforeId and AfterId properties of another Ribbon control, you use the shared controls' idQ:
%namespace abbreviation% + ":" + %control id%. The abbreviations of these namespaces are "default" and "shared" string values. Say, when
creating a shared tab, containing a private group, containing a button (private again), the resulting XML markup looks as follows:
<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"
xmlns:default="MyOutlookAddin1.AddinModule"
xmlns:shared="MyNameSpace" [callbacks omitted]>
<ribbon>
<tabs>
<tab idQ=" shared:adxRibbonTab1" visible="true" label="My Tab">
<group idQ="default:adxRibbonGroup1" [callbacks omitted]>
<button idQ="default:adxRibbonButton1" [callbacks omitted]/>
</group>
</tab>
</tabs>
</ribbon>
</customUI>
Back to Add-in Express for Office and .NET homepage | 
