The sample add-in demonstrates how to customize the ribbons, menus, context menus, and Backstage view in Outlook 2010. Developed in Visual Studio 2008 Tools for Office, the add-in adds ribbon controls, a custom menu, context menu items, and Backstage view controls, and then displays a message box when the user clicks the control or menu item. The add-in provides a visual element for every entry point in the Outlook 2010 UI that you can customize by using Fluent UI extensibility.

The sample add-in has some additional features that illustrate how to manage certain problem areas in the Outlook 2010 UI. For example, suppose that you want to show a custom group in the ribbon for received e-mail items only. The sample add-in displays the custom ribbon tab only when the selected item in the Outlook explorer is a received mail item or when the received mail item is displayed in an inspector. Although that might seem to be a trivial task at first, it is actually a complex problem because Outlook can display multiple explorer or inspector windows, and your code must be able to respond appropriately. For example, in two open explorer windows, you might have to hide the custom tab in the window that has a meeting selected, but display the custom tab in the window that has a received mail item selected. Once you understand how the sample add-in works, you can use the wrapper classes from the sample to build your own solution that can coordinate the display of your command UI in multiple Outlook windows.

To download the sample code installation package

1. Download the OL2010ExtendingtheUserInterface_CS.zip file from Outlook 2010: Extending the User Interface in the MSDN Samples Gallery.

2. Extract the .zip file into the folder of your choice. In Windows Vista, the default path for Visual Studio 2008 Tools for Office projects is C:\Users\user\Documents\Visual Studio 2008\Projects.

To run the Outlook Ribbon extensibility sample

1. Close Outlook 2010.

2. In the folder where you extracted the RibbonXOutlook14AddinCS.zip file, open the RibbonXOutlook14AddinCS solution.

3. On the Build menu, click Build RibbonXOutlook14AddinCS.

4. Start Outlook 2010 to start the add-in in run mode, or press F5 to start the add-in in debug mode. If Outlook does not start in debug mode, complete the following procedure.

To start Outlook in debug mode

1. In Solution Explorer, select RibbonXOutlook14AddinCS.

2. On the Project menu, select RibbonXOutlook14AddinCS Properties, and then click the Debug tab.

3. Under Start Action, select the Start External Program option, and then click Browse.

4. In the [Drive:]\Program Files\Microsoft Office\Office14 folder, select Outlook.exe.

5. Press F5 to start the add-in in debug mode.

The Outlook14RibbonXAddinCS solution is built with Microsoft Visual Studio 2008 Service Pack 1. It uses manual authoring of XML markup files instead of the ribbon designer that is provided with Visual Studio Tools for Office. The most important architectural feature is the use of wrapper classes (OutlookExplorer.cs for explorers and OutlookInspector.cs for inspectors) to handle multiple Outlook windows. The wrapper classes are implemented by using a C# Generic List(T) class.

Note
If you are not writing managed code, you must write native C++ code that mimics the use of these wrapper classes.

First, the following class-level instance variables are declared in the standard ThisAddin class in Visual Studio 2008 with Visual Studio Tools for Office.

using System;
using System.Collections.Generic;
using System.Text;
using System.Windows.Forms;
using System.Diagnostics;
using Outlook = Microsoft.Office.Interop.Outlook;
using Office = Microsoft.Office.Core;namespace RibbonXOutlook14AddinCS
{public partial class ThisAddIn{#region Instance VariablesOutlook.Application m_Application;             Outlook.Explorers m_Explorers;Outlook.Inspectors m_Inspectors;public stdole.IPictureDisp m_pictdisp = null;// List of tracked explorer windows.         internal static List<OutlookExplorer> m_Windows;// List of traced inspector windows.internal static List<OutlookInspector> m_InspectorWindows;// Ribbon UI reference.internal static Office.IRibbonUI m_Ribbon;#endregion...}
}

Once the instance variables have been declared, they are used in the Startup method of the ThisAddin class that is provided to all Visual Studio 2008 with Visual Studio Tools for Office add-ins. In the Startup method, which typically occurs when Outlook starts, the code first hooks up an event handler to respond to the NewExplorer event on the Outlook Explorers collection object. After the NewExplorer event has been handled, the active explorer window is added by using the following code.

private void ThisAddIn_Startup(object sender, System.EventArgs e)
{// Initialize variables.m_Application = this.Application;m_Explorers = m_Application.Explorers;m_Inspectors = m_Application.Inspectors;m_Windows = new List<OutlookExplorer>();m_InspectorWindows = new List<OutlookInspector>();// Wire up event handlers to handle multiple Explorer windows.m_Explorers.NewExplorer += new Outlook.ExplorersEvents_NewExplorerEventHandler(m_Explorers_NewExplorer);// Wire up event handler to handle multiple Inspector windows.m_Inspectors.NewInspector += new Outlook.InspectorsEvents_NewInspectorEventHandler(m_Inspectors_NewInspector);// Add the ActiveExplorer to m_Windows.Outlook.Explorer expl = m_Application.ActiveExplorer()as Outlook.Explorer;OutlookExplorer window = new OutlookExplorer(expl);m_Windows.Add(window);// Hook up event handlers for window.window.Close += new EventHandler(WrappedWindow_Close);window.InvalidateControl += new EventHandler<OutlookExplorer.InvalidateEventArgs>(WrappedWindow_InvalidateControl);// Get IPictureDisp for CurrentUser on startup.try{Outlook.AddressEntry addrEntry = Globals.ThisAddIn.Application.Session.CurrentUser.AddressEntry;if (addrEntry.Type == "EX"){Outlook.ExchangeUser exchUser = addrEntry.GetExchangeUser() as Outlook.ExchangeUser;m_pictdisp = exchUser.GetPicture() as stdole.IPictureDisp;}}catch (Exception ex){// Write exception to debug window.Debug.WriteLine(ex.Message);}
}

Just after Outlook starts, Office calls GetCustomUI. GetCustomUI is the method of the IRibbonExtensibility interface that loads custom XML markup. In Outlook 2007, Office called GetCustomUI when the first instance of a given inspector type, such as a contact or appointment, was displayed. In Outlook 2010, Office calls GetCustomUI before the ThisAddin.Startup method to accommodate the loading of ribbon customizations for the Outlook explorer ribbon. Because Office calls GetCustomUI only once for the first Outlook explorer during startup and multiple times for the first instance of multiple inspector types, consider using a Switch statement to control loading of XML markup for different customized Ribbons. For each ribbon in Outlook, GetCustomUI is called and Office passes the ribbon ID string that identifies the ribbon that is being loaded in Outlook. For a complete listing of ribbon IDs, see the section Ribbon Identifiers.

In the sample code, there are three XML markup files:

• ContactCard.xml

• Explorer.xml

• ReadMail.xml

ContactCard.xml contains XML markup for context menus on the Contact Card. Explorer.xml contains XML markup for the explorer ribbon, context menus, and Backstage view. Readmail.xml contains XML markup for a read mail inspector.

To get a better idea of how this technique works, examine the following code from the GetCustomUI method in the OutlookRibbonXclass.

public string GetCustomUI(string ribbonID)
{string customUI = string.Empty;Debug.WriteLine(ribbonID);// Return the appropriate XML markup for ribbonID.switch (ribbonID){case "Microsoft.Outlook.Explorer":customUI = GetResourceText( "RibbonXOutlook14AddinCS.Explorer.xml");return customUI;case "Microsoft.Outlook.Mail.Read":customUI= GetResourceText("RibbonXOutlook14AddinCS.ReadMail.xml");return customUI;case "Microsoft.Mso.IMLayerUI":customUI = GetResourceText("RibbonXOutlook14AddinCS.ContactCard.xml");return customUI;default:return string.Empty;}
}

Take a look at the sample solution for a complete listing of ContactCard.xml, Explorer.xml, and ReadMail.xml. Once custom XML markup has been loaded for each add-in, it is time to write code in Fluent UI extensibility callbacks to hide and show the tab named MyTab, depending on whether the selected item in the explorer is a received mail item. To complete the scenario, you must hook up another set of events in the constructor of the OutlookExplorer class.

public OutlookExplorer(Outlook.Explorer explorer)
{m_Window = explorer;// Hook up Close event.((Outlook.ExplorerEvents_Event)explorer).Close +=new Outlook.ExplorerEvents_CloseEventHandler(OutlookExplorerWindow_Close);// Hook up SelectionChange event.m_Window.SelectionChange += new Outlook.ExplorerEvents_10_SelectionChangeEventHandler(m_Window_SelectionChange);
}

The SelectionChange event handler is very straightforward. The SelectionChange event occurs whenever the user changes the selection in an explorer window. When SelectionChange occurs, the RaiseInvalidateControl method is called and the control ID "MyTab" is passed to the method. RaiseInvalidateControl calls an event delegate named WrappedWindow_InvalidateControl in the ThisAddin class.

private void m_Window_SelectionChange()
{RaiseInvalidateControl("MyTab");
}
void WrappedWindow_InvalidateControl(object sender,OutlookExplorer.InvalidateEventArgs e)
{if (m_Ribbon != null){m_Ribbon.InvalidateControl(e.ControlID);}
}

The m_Ribbon variable represents an IRibbonUI object. When the InvalidateControl method of the IRibbonUI object is called, ribbon callbacks occur for the "MyTab" control. You could also call the Invalidate method of IRibbonUI, but that method causes callbacks for all of the controls that your add-in adds to the ribbon. In general, make your invalidation more granular than global, especially when your callbacks load image resources with a getImage callback. For the "MyTab" control, a getVisible callback has been defined in the RibbonXAddin class that controls the visibility of the tab. If the getVisible callback returns True, the tab is visible; otherwise, "MyTab" is hidden. The following code is the MyTab_GetVisible callback in its entirety.

// Only show MyTab when explorer selection is
// a received mail or when inspector is a read note.
public bool MyTab_GetVisible(Office.IRibbonControl control)
{if (control.Context is Outlook.Explorer){Outlook.Explorer explorer = control.Context as Outlook.Explorer;Outlook.Selection selection = explorer.Selection;if (selection.Count == 1){if (selection[1] is Outlook.MailItem){Outlook.MailItem oMail = selection[1] as Outlook.MailItem;if (oMail.Sent == true){return true;}else{return false;}}else{return false;}}else{return false;}}else if (control.Context is Outlook.Inspector){Outlook.Inspector oInsp = control.Context as Outlook.Inspector;if (oInsp.CurrentItem is Outlook.MailItem){Outlook.MailItem oMail = oInsp.CurrentItem as Outlook.MailItem;if (oMail.Sent == true){return true;}else{return false;}}else{return false;}}else{return true;}
}

This walkthrough detailed the most important strategies for extending the ribbon in Outlook 2010. In summary, your code should support the following:

• The use of multiple explorer or inspector windows in Outlook 2010. Wrap the windows in a separate class instance that can raise events appropriate to that specific window.

• The appropriate use of the InvalidateControl or Invalidate methods of the IRibbonUI interface to cause callbacks to occur.

• The evaluation of different item types (based on the message class, built-in properties, or custom properties of a specific item type) in both event handlers and ribbon callbacks.

Microsoft.Outlook.Explorer

Explorer object

When Outlook 2010 starts, it calls the GetCustomUI method of the IRibbonExtensibility interface and specifies the ribbon ID in the RibbonID parameter for the add-in. The add-in should implement the GetCustomUI method such that if RibbonID is Microsoft.Outlook.Explorer, GetCustomUI returns the XML markup for explorer and context menu customizations.

Outlook supports different ribbons in inspectors that display different item types. Depending on the message class of the item to be displayed in an inspector, the add-in should expect Outlook to pass the corresponding ribbon ID as the RibbonID parameter to the GetCustomUI method.

Inspector object

When Outlook 2010 displays the first inspector for a built-in message class, Outlook calls the GetCustomUI method of the IRibbonExtensibility interface and specifies the ribbon ID in the RibbonID parameter for the add-in. The add-in should implement the GetCustomUI method such that GetCustomUI returns the appropriate XML markup based on RibbonID.

Use the CurrentItem property of the Inspector object to return the item-level object such as MailItem, AppointmentItem, ContactItem, or TaskItem.

Microsoft.Outlook.Explorer

Folder object

When Outlook 2010 displays the following context menu, a folder is selected in the Folder List in the Navigation Pane.

Microsoft.Outlook.Explorer

Folder object

When Outlook 2010 displays the following context menu, the root search folder, Search Folders, is selected in the Folder List in the Navigation Pane.

Microsoft.Outlook.Explorer

Store object

When Outlook 2010 displays the following context menu, a store folder is selected in the Folder List in the Navigation Pane.

Microsoft.Outlook.Explorer

Selection object

When Outlook 2010 displays the following context menu, a mail item is selected in the current view.

Microsoft.Outlook.Explorer

Selection object

When Outlook 2010 displays the following context menu, multiple items are selected in the current view.

Microsoft.Outlook.Explorer

Selection object

When Outlook 2010 displays the following context menu, an appointment or a meeting request is selected in the current calendar view.

Microsoft.Outlook.Explorer

Selection object

When Outlook 2010 displays the following context menu, a task item is selected in the current task view.

Microsoft.Outlook.Explorer

Selection object

When Outlook 2010 displays the following context menu, a contact item is selected in the current view.

Microsoft.Outlook.Explorer

Selection object

When Outlook 2010 displays the following context menu, a journal item is selected in the current view.

Microsoft.Outlook.Explorer

Selection object

When Outlook 2010 displays the following context menu, a note item is selected in the current view.

Microsoft.Outlook.Explorer

OutlookBarShortcut object

When Outlook 2010 displays the following context menu, a shortcut is selected in the Shortcuts module.

Microsoft.Outlook.Explorer

AttachmentSelection object

When Outlook 2010 displays the following context menu, one or more attachments are selected in the Reading Pane in the explorer, or in an inspector.

Microsoft.Outlook.Explorer

View object

Outlook 2010 displays the following context menu when a user displays the context menu in a table view.

Microsoft.Outlook.Explorer

View object

Outlook 2010 displays the following context menu when a user displays the context menu in a calendar view.

Microsoft.Outlook.Explorer

View object

Outlook 2010 displays the following context menu when a user displays the context menu in a card view.

Microsoft.Outlook.Explorer

View object

Outlook 2010 displays the following context menu when a user displays the context menu in a timeline view.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following menu when a user points to Arrange By in the context menu for a field in a table view.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following context menu when a user right-clicks the time bar in a calendar view.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following context menu when a user right-clicks the free/busy bar in a calendar view.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following context menu when a user right-clicks a column header in a table view.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following context menu when a user right-clicks a category or, if no category has been specified, the user right-clicks under the Category column in a table view.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following context menu when a user displays the context menu for a quick flag.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following context menu when a user displays the context menu for a flagged mail item in the To-Do Bar.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following context menu when a user displays the context menu for a flagged mail item in the To-Do Bar.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following menu when a user selects New Items in the Home tab of the explorer ribbon for the Mail module. Although the New Items menu is not a context menu, the markup for a custom menu item should be placed inside the <contextMenus></contextMenus> tags. That way, you can add a command for an item that is based on a custom message class to the built-in New Itemsmenu.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following menu when a user clicks New Items in the Home tab of the explorer ribbon for the Calendar module. Although the New Items menu is not a context menu, the markup for a custom menu item should be placed inside the <contextMenus></contextMenus> tags. That way, you can add a command for an item that is based on a custom message class to the built-in New Itemsmenu.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following menu when a user clicks New Items in the Home tab of the explorer ribbon for the Contacts module. Although the New Items menu is not a context menu, the markup for a custom menu item should be placed inside the <contextMenus></contextMenus> tags. That way, you can add a command for an item that is based on a custom message class to the built-in New Itemsmenu.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following menu when a user clicks New Items in the Home tab of the explorer ribbon for the Tasks module. Although the New Items menu is not a context menu, the markup for a custom menu item should be placed inside the <contextMenus></contextMenus> tags. That way, you can add a command for an item that is based on a custom message class to the built-in New Itemsmenu.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following menu when a user clicks New Items in the Home tab of the explorer ribbon for the Journal module. Although the New Items menu is not a context menu, the markup for a custom menu item should be placed inside the <contextMenus></contextMenus> tags. That way, you can add a command for an item that is based on a custom message class to the built-in New Itemsmenu.

Microsoft.Outlook.Explorer

Explorer object

Outlook 2010 displays the following menu when a user clicks New Items in the Home tab of the explorer ribbon for the Notes module. Although the New Items menu is not a context menu, the markup for a custom menu item should be placed inside the <contextMenus></contextMenus> tags. That way, you can add a command for an item that is based on a custom message class to the built-in New Itemsmenu.

Microsoft.Mso.IMLayerUI

Office.IMsoContactCard object

Outlook 2010 displays the persona context menu when a user right-clicks a sender or a recipient of an Outlook item. To determine the identity of the sender or recipient, use the Address property of the IMsoContactCard object in the Office object model to obtain an AddressEntry object in the Outlook object model, which represents the recipient as shown in the following code example.

if (control.Context is Microsoft.Office.Core.IMsoContactCard)
{msg = "Context=IMsoContactCard" + "\n";Office.IMsoContactCard card = control.Context as Office.IMsoContactCard;Outlook.AddressEntry addr =Globals.ThisAddIn.Application.Session.GetAddressEntryFromID(card.Address);if (addr != null){msg = msg + addr.Name;}MessageBox.Show(msg);
}

Microsoft.Mso.IMLayerUI

Office.IMsoContactCard object

To interact with a contact by using a way other than e-mail, instant message, or phone, a user can specify an alternative form on the shortcut menu that is on a Contact Card. To display a Contact Card, a user can rest the pointer on, click, or right-click a sender or recipient of an Outlook item.

To determine the identity of the sender or recipient, use the Address property of the IMsoContactCard object in the Office object model to obtain an AddressEntry object in the Outlook object model, which represents the recipient as shown in the following code example.

if (control.Context is Microsoft.Office.Core.IMsoContactCard)
{msg = "Context=IMsoContactCard" + "\n";Office.IMsoContactCard card = control.Context as Office.IMsoContactCard;Outlook.AddressEntry addr =Globals.ThisAddIn.Application.Session.GetAddressEntryFromID(card.Address);if (addr != null){msg = msg + addr.Name;}MessageBox.Show(msg);
}

Microsoft.Outlook.Explorer or appropriate Inspector RibbonID

Explorer object or Inspector object

Contextual tabs appear when a user selects an object in the Outlook user interface with the intent to edit or modify that object. Customizing a contextual tab is similar to customizing a built-in ribbon tab, but the markup for customization uses <contextualTabs></contextualTabs> tags instead of <tabs></tabs>. Contextual tabs are used extensively in Outlook 2010. The following example shows how to customize the contextual tab for attachments named Attachment Tools.The Attachment Context Menu described previously adds a context menu item that can act on the selected attachment. To create an equivalent command in the Attachment Tools contextual tab, you need to supply XML markup as shown in the following XML markup example and then determine the selected attachment by using the AttachmentSelection object returned by IRibbonControl.Context as shown in the following C# code fragment:

    else if (control.Context is Outlook.Explorer){msg = "Context=Explorer" + "\n";Outlook.Explorer explorer = control.Context as Outlook.Explorer;if (explorer.AttachmentSelection.Count >= 1){Outlook.AttachmentSelection attachSel =explorer.AttachmentSelection;foreach (Outlook.Attachment attach in attachSel){msg = msg + attach.DisplayName + "\n";}}else{Outlook.Selection selection =explorer.Selection;if (selection.Count == 1){OutlookItem olItem =new OutlookItem(selection[1]);msg = msg + olItem.Subject+ "\n" + olItem.LastModificationTime;}else{msg = msg + "Multiple Selection Count="+ selection.Count;}}}}    

Microsoft.Outlook.Explorer

Explorer object or Inspector object

Backstage view helps users to find commonly used features and to discover new ways to work with their documents. To access Backstage view, click the File tab that appears to the left of the Home tab. In Outlook 2010, you can use Backstage view to expose application-level settings for an add-in. Consider customizing Backstage view to replace the property page extensions that were accessible when you clicked Tools and then Options in earlier versions of Outlook. Property page extensions continue to work in Outlook 2010, but users might not find them easily. To access add-in property page extensions, open Backstage view, click the Options command to display the Outlook Options dialog box, click the Add-ins tab, and then click the Add-in Options button.

Outlook 2010 can display Backstage view in either an explorer or inspector window. Use the IRibbonControl.Context property to determine whether Backstage view is hosted in an explorer or inspector window.

A tab in Backstage view is a functional unit. Backstage view contains default tabs. For example, Backstage view for the Outlook explorer contains the Info, Open, Print, and Help tabs. If you want to create a custom tab and show it in only an Outlook explorer or inspector window, use the GetVisible callback. The following C# code example causes the MyPlace tab to be visible only in the explorer window.

public bool MyPlace_GetVisible(IRibbonControl control)
{if (control.Context is Microsoft.Office.Interop.Outlook.Explorer)return true;elsereturn false;
}