Customizing the Ribbon in Outlook 2007 Using Visual Studio 2005 Tools for the Office System SE

Summary:   Create a custom Ribbon in Microsoft Office Outlook 2007 by using Microsoft Visual Studio 2005 Tools Second Edition for the 2007 Microsoft Office System.

Office Visual How To

Applies to:   2007 Microsoft Office System, Microsoft Office Outlook 2007, Microsoft Visual Studio 2005 Tools Second Edition for the 2007 Microsoft Office System

Steve Hansen, Office Zealot

September 2007

Overview

The Microsoft Office Fluent user interface (UI) in the 2007 Microsoft Office system replaces the current menu system of command bars and command controls. The Ribbon is a component of the Office Fluent UI. The Microsoft Office Outlook 2007 UI is different from other 2007 Office system applications because it uses both the Ribbon and command bars: Inspector windows use the Ribbon, and Explorer windows use a UI based on the command bar.

The purpose of this Office Visual How-to article is to show how to use Visual Studio 2005 Tools for Office SE to create a custom Ribbon in Outlook 2007.

See It Customizing the Ribbon in Outlook 2007

Watch the Video

Length: 09:06 | Size: 12.8 MB | Type: WMV file

Code It | Read It | Explore It

Code It

After you add Ribbon customization support to an Outlook add-in project, you can perform several tasks. The following code examples demonstrate how to implement some common tasks.

Adding Ribbon Support to an Outlook Add-in

To add Ribbon support to an existing Outlook add-in, start Visual Studio 2005 Tools for Office SE, select Project, and then click Add New Item. Click Ribbon Support, name the item, for example, ribbon.cs, and then click Add.

Visual Studio 2005 Tools for Office SE adds a class that implements IRibbonExtensibility and any callback procedures specified in the Ribbon XML that defines the custom Ribbon. You can think of callback procedures as event handlers for a Ribbon.

In the class file that implements IRibbonExtensibility, uncomment the partial class, ThisAddIn. This class is initially commented out in case the RequestService method has already been implemented elsewhere in the project.

Targeting Specific Inspector Windows

The code that Visual Studio 2005 Tools for Office SE adds to an Outlook add-in project adds an Add-Ins tab to the Ribbon in each type of Inspector window, for example, Mail, Contacts, and Tasks. To customize the Ribbon for a specific type of Inspector window, such as Mails, inspect the ribbonID parameter passed to the GetCustomUI method to determine which type of Inspector window is requesting the custom UI. For a complete listing of Outlook ribbonID parameters, see Outlook Ribbon IDs.

public string GetCustomUI(string ribbonID)
{
   String ui = null;
   // Examine the ribbonID to see if the current item
   // is a Mail inspector.
   if (ribbonID == "Microsoft.Outlook.Mail.Read" ||
       ribbonID == "Microsoft.Outlook.Mail.Compose")
   {
      // Retrieve the customized Ribbon XML.
      ui = GetResourceText("OutlookRibbonExample.OutlookRibbon.xml");
   }
   Return ui;
}
Public Function GetCustomUI(ByVal ribbonID as String) As String _
   Implements Office.IRibbonExtensibility.GetCustomUI
   Dim ui As String = ""

   ' Examine the ribbonID to see if the current item
   ' is a Mail inspector.
   If ribbonID = "Microsoft.Outlook.Mail.Read" Or _
      ribbonID = "Microsoft.Outlook.Mail.Compose" Then
   
      ' Retrieve the customized Ribbon XML.
      ui = GetResourceText("OutlookRibbonExampleVB.OutlookRibbon.xml")
   
   End If

   Return ui
End Function

Retrieving Images from Project Resource Files

More than 2,000 built-in images of various sizes are available to use as images for custom Ribbons. To use custom icons, set the getImage attribute in custom Ribbon XML to specify a callback that retrieves an image to use. For example, the following XML fragment specifies two Ribbon controls. The first control uses the getImage attribute while the second control specifies a built-in image by using the imageMso attribute. To download icons for browsing the available built-in images, see 2007 Office System Add-In: Icons Gallery.

Notice the use of the onAction attribute for each button. Like getImage, the values associated with onAction are actually the names of callback procedures that are implemented in the class file implementing IRibbonExtensibility.

<button id="buttonHistory" 
   size="large"
   label="Sales History"
   screentip="Show customer sales history"
   onAction="OnShowHistory" 
   getImage="GetCustomImage" />
<button id="buttonContact" 
   size="large"
   label="Contact Info"
   screentip="Show customer contact information"
   onAction="OnShowContactInfo" 
   imageMso="AutoDial" />  

Using getImage, it is possible to embed icons as resources in an assembly. To retrieve the correct icon from the resource file, examine the control ID of the IRibbonControl object, as shown in the following example.

NoteNote

The example refers to a Convert method on an ImageConverter object. The ImageConverter object is explained later in this visual how-to article. Also, this example assumes that an image named opportunity has been added to your resources file.

public stdole.IPictureDisp 
GetCustomImage(Office.IRibbonControl control)
{
   stdole.IPictureDisp pictureDisp = null;
   switch (control.Id)
   {
      case "buttonHistory":
         // The following line assumes that there is an
         // image named "opportunity" in your resources file.
         pictureDisp = ImageConverter.Convert(
              Properties.Resources.opportunity.ToBitmap());
      break;
      // Other cases as needed.
   }
   return pictureDisp;
}
Public Function GetCustomImage( _
ByVal control As Office.IRibbonControl) As stdole.IPictureDisp
   
   Dim pictureDisp As stdole.IPictureDisp = Nothing

   Select Case control.Id
       Case Is = "buttonHistoryVB"
           ' The following line assumes that there is an 
           ' image named "opportunity" in your resources file.
           pictureDisp = ImageConverter.Convert( _
               My.Resources.opportunity.ToBitmap())    
       ' Other cases as needed.
   End Select

   Return pictureDisp
End Function

Finally, you must provide a way to convert the managed bitmap object to a COM IPictureDisp object as expected by the Ribbon. You can do this by creating an internal class inside your Ribbon class that handles the conversion.

internal class ImageConverter : System.Windows.Forms.AxHost
{
   private ImageConverter(): base(null)
   {
   }

   public static stdole.IPictureDisp 
   Convert(System.Drawing.Image image)
   {
      Return(stdole.IPictureDisp)
           AxHost.GetIPictureDispFromPicture(image);
   }
}
Friend Class ImageConverter
   Inherits System.Windows.Forms.AxHost
   
   Sub New()
      MyBase.New(Nothing)
   End Sub
   
   Public Shared Function _
   Convert(ByVal image As System.Drawing.Image) _
   As stdole.IPictureDisp
      Return AxHost.GetIPictureDispFromPicture(image)
   End Function
End Class

Read It

While the main Outlook 2007 application window (Explorer window) uses command bars, Outlook item windows (Inspector windows) use the Ribbon, a component of the Office Fluent UI. You can customize the Ribbon by using an Outlook add-in that implements the IRibbonExtensibility interface. Visual Studio 2005 Tools for Office SE allows you to rapidly add Ribbon customization to an Outlook add-in project.

Ribbon Customization Overview

Performing Ribbon customization by using an add-in generally involves three logical parts. The primary component, an XML file that conforms to the schema definition for Ribbon extensibility (customUI.xsd), defines a custom Ribbon. The next component is code within your add-in that implements the IRibbonExtensibility interface; IRibbonExtensibility specifies only one method, GetCustomUI, which Outlook calls to retrieve a string representing the custom Ribbon XML. The final component is code that implements callback procedures you specify within the custom Ribbon XML that implements the behavior you want. To succeed with ribbon customization, it is helpful to understand the interactions among Outlook, custom Ribbon XML, code that implements IRibbonExtensibility, and code that implements callback procedures.

Because the Outlook main application window uses command bars, Outlook does not make a call to the GetCustomUI method until the user opens an Inspector window. For example, selecting a mail item and viewing it in the Reading pane does not trigger a call to the GetCustomUI method.

When an Inspector window is opened, Outlook might call GetCustomUI depending on whether it has already loaded the appropriate Ribbon. Outlook uses 19 ribbon IDs that correlate to various message classes. When an Inspector window is opened, Outlook determines the ribbon ID that correlates to the item that is being opened. If that type of item is not yet open in the current session, Outlook calls GetCustomUI and passes the ribbon ID associated with the item being opened. After GetCustomUI is called with a given ribbon ID, GetCustomUI is not called again for that ribbon ID.

Because the GetCustomUI method is called only once per ribbon ID, you cannot use it to implement conditional ribbon logic based on conditions specific to a given item, such as visibility. This is where you use callbacks. Within your custom XML, you can use attributes, such as getVisible, to specify methods to call at appropriate times. For example, the method specified in the getVisible attribute is called whenever Outlook determines that the associated Ribbon control is no longer valid and must be redrawn. You can call one of two methods to force Outlook to invalidate Ribbon controls: Invalidate or InvalidateControl. For more information, see Customizing the Ribbon in Outlook 2007.

Ribbon Customization with Visual Studio 2005 Tools for Office SE

Visual Studio 2005 Tools for Office SE provides functionality that allows you to create a custom Ribbon quickly. Adding Ribbon support to an Outlook add-in consists of these steps:

  1. Add a new item to the project.

  2. Select the Ribbon support item.

  3. Uncomment the partial class ThisAddIn within the Ribbon class that Visual Studio 2005 Tools for Office SE adds to the project.

  4. Modify the Ribbon XML as needed.

  5. Add any callback procedures as needed.

When you add Ribbon support in this way, Visual Studio 2005 Tools for Office SE adds two files to your project: a custom Ribbon XML file and a Ribbon class that implements the IRibbonExtensibility interface and basic Ribbon callbacks associated with the Ribbon XML.

NoteNote

The Ribbon class also contains an extension (partial class) to ThisAddIn that is initially commented out by default, to address the case in which you have already overridden the RequestService method elsewhere in your project. If that is the case, add the Ribbon-specific code from this section to your existing implementation.

For more information about how to target specific types of Inspector windows and how to use custom images, see Code It.

Explore It