Customizing Office 2007 and Office 2010 Ribbons and
ribbon controls in C#, C++, VB.NET

Add-in Express™
for Microsoft® Office and .net

Add-in Express Home >

Office ribbon and task pane tips

Add-in Express provides a visual designer for customizing Office 2007 and 2010 Ribbon tabs. On this page you can find some tips about dealing with Office 2007 and 2010 ribbons and ribbon controls.

Being ribboned

You can find IDs of built-in Ribbon controls on Microsoft web-sites:

Sharing Office 2010 and 2007 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 Ribbon 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 the 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 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 the add-ins that are to share an Office 2007 Ribbon control, for the control with the same Id (you can change the Id's to match), you set the Shared property to True. For the Ribbon 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 the 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 Ribbon container controls:

  • Ribbon Tab - ADXRibbonTab
  • Ribbon Box - ADXRibbonBox
  • Ribbon Group - ADXRibbonGroup
  • Ribbon Button Group - ADXRibbonButtonGroup

When referring to a shared Office 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. The resulting XML markup may look like this:

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

In the XML-code above, the add-in creates a shared tab, containing a private group, containing a button (private again).

Dynamic Ribbon controls

The Office 2010-2007 Ribbon is a static thing from birth; the only control providing any dynamism is Dynamic Menu (see the Dynamic property of the ADXRibbonMenu component). For other controls, you can only imitate that dynamism by changing the Visible property of a Ribbon control.

Cannot add a Ribbon control

The Ribbon tab designer performs the XML-schema validation automatically, so from time to time you will run into the situation when you cannot add a control to some level. It is a restriction of the Ribbon XML-schema.

Customizing Quick Access Toolbar

Microsoft require developers to use the StartFromScratch parameter (see the StartFromScratch property of the add-in module) when customizing the Quick Access Toolbar.

Built-in and custom command bars in Ribboned Office 2007-2010 applications

Do you know that all usual command bars that we used in earlier Office versions are still alive in Office 2007 - 2010 applications supporting the Ribbon UI? For instance, our free Built-in Controls Scanner reports that Outlook 2007 e-mail inspector still has the Standard toolbar with the Send button on it. This may be useful if the functionality of your add-in takes into account the enabled / disabled state of this or that toolbar button.

As to custom toolbars, you can use set the UseForRibbon property of the corresponding component to true (the default value is false). This will result in your command bar controls showing up on the Add-ins tab along with command bar controls from other add-ins.

Custom Task Panes (Office 2007, Office 2010)

To add a new task pane, you add a UserControl to your project and populate it with controls. Then you add an item to the TaskPanes collection of the add-in module and specify its properties:

TaskPanes collection editor

  • Caption - the caption of your task pane (required!)
  • Height, Width - the height and width of your task pane (applies to horizontal and vertical task panes, correspondingly)
  • DockPosition - you can dock your task pane to the left, top, right, or bottom edges of the host application window
  • ControlProgID - the UserControl just added

In Add-in Express, you work with the task pane component and task pane instances. The TaskPanes collection of the add-in module contains task pane components. When you set, say, the height or dock position of the component, these properties apply to every task pane instance that the host application shows. To modify a property of a task pane instance, you should get the instance itself. This can be done through the Item property of the component (in C#, this property is the indexer for the ADXTaskPane class). The property accepts the Outlook Explorer or Inspector window object that displays the task pane as a parameter. For instance, the method below finds the currently active instance of the task pane in Outlook 2007 and 2010 and refreshes it. For the task pane to be refreshed in a consistent manner, this method should be called in appropriate event handlers.


Private Sub RefreshTaskPane(ByVal ExplorerOrInspector As Object)
   If Me.HostVersion.Substring(0, 4) = "12.0" Then
      Dim TaskPaneInstance As _
         AddinExpress.MSO.ADXTaskPane.ADXCustomTaskPaneInstance = _
            AdxTaskPane1.Item(ExplorerOrInspector)
      If Not TaskPaneInstance Is Nothing _
         And TaskPaneInstance.Visible Then
         Dim uc As UserControl1 = TaskPaneInstance.Control
         If Not uc Is Nothing Then _
           uc.InfoString = GetSubject(ExplorerOrInspector)
      End If
   End If
End Sub

The InfoString property just gets or sets the text of the Label located on the UserControl1. The GetSubject method is shown below.


   Private Function GetSubject(ByVal ExplorerOrInspector As Object) _
      As String
      Dim mailItem As Outlook.MailItem = Nothing
      Dim selection As Outlook.Selection = Nothing

      If TypeOf ExplorerOrInspector Is Outlook.Explorer Then
         Try
            selection = CType(ExplorerOrInspector, _
               Outlook.Explorer).Selection
            mailItem = selection.Item(1)
         Catch
         Finally
            If Not selection Is Nothing Then _
               Marshal.ReleaseComObject(selection)
         End Try
      ElseIf TypeOf ExplorerOrInspector Is Outlook.Inspector Then
         Try
            mailItem = CType(ExplorerOrInspector, _
               Outlook.Inspector).CurrentItem
         Catch
         End Try
      End If

      If mailItem Is Nothing Then
         Return ""
      Else
         Dim subject As String = "The subject is: " + mailItem.Subject
         Marshal.ReleaseComObject(mailItem)
         Return subject
      End If
   End Function

The code of the GetSubject method emphasizes the following:

  • The ExplorerOrInspector parameter was originally obtained through parameters of Add-in Express event handlers. That is why we do not release it (see Releasing COM objects).
  • The selection and mailItem COM objects were created "manually" so they must be released.
  • All Outlook versions fire an exception when you try to obtain the Selection object for a top-level folder, such as Personal Folders.

Below is another sample that demonstrates how the same things can be done in Excel or Word.


Imports AddinExpress.MSO
...
   Private Sub RefreshTaskPane()
      If Version = "12.0" Then
         Dim Window As Object = Me.HostApplication.ActiveWindow
         If Not Window Is Nothing Then
            RefreshTaskPane(AdxTaskPane1.Item(Window))
            Marshal.ReleaseComObject(Window)
         End If
      End If
   End Sub

   Private Sub RefreshTaskPane(ByVal TaskPaneInstance As _
      ADXTaskPane.ADXCustomTaskPaneInstance)
      If Not TaskPaneInstance Is Nothing Then
         Dim uc As UserControl1 = TaskPaneInstance.Control
         If uc IsNot Nothing And TaskPaneInstance.Window IsNot Nothing Then
            uc.InfoString = GetInfoString(TaskPaneInstance.Window)
         End If
      End If
   End Sub

The InfoString property mentioned above just updates the text of the label located on the UserControl. Please pay attention to Releasing COM objects in this code.

Find more about Advanced task panes for MS Office Word, Excel, PowerPoint and How to create custom Excel task panes.

Note. If you didn't find the answer to your questions about MS Office 2007 and 2010 Ribbon on this page, please see the HOWTOs section:
See Also