VSTO components to add Outlook 2007 Ribbon tabs,
context menu, commandbar controls in C#, VB. NET

Add-in Express™
for Microsoft® Office and VSTO

Add-in Express Home > Add-in Express for Office and VSTO > Online Guide > Add-in Express for VSTO components

Add-in Express for VSTO components

Add-in Express module

The add-in module represents an add-in in the targeted Office application and centralizes all programming logics in one place. Its designer allows adding other Add-in Express components and setting their properties at design-time. It provides all events of the host application. It also supplies the OnStartupComplete and OnBeginShutdown events, so you can handle add-in startup and shutdown. There are also events related to Office 2010 and 2007 task panes (OnTaskPaneBeforeCreate, OnTaskPaneBeforeShow, OnTaskPaneBeforeDestroy, etc), and the Ribbon UI (OnRibbonBeforeCreate, OnRibbonBeforeLoad, OnRibbonLoaded). For Outlook add-ins, you can specify pages for the Tools | Options and Folder Properties dialogs.

You can also add custom task panes in Outlook, Excel, Word, and PowerPoint, versions 2003, 2007 and 2010. See Advanced Custom Task Panes in Office 2003-2010.

Adding an Add-in Express component to the Add-in Express designer

To add any Add-in Express for VSTO component onto the add-in module, activate the Add-in Express Module designer window and use commands available either in the Properties Window or in the context menu. To activate the Add-in Express Module designer window, in the Solution Explorer window, right-click on the Add-in Express Module item and choose the View Designer popup menu item.

Office 2010 abd 2007 Ribbon components

Office 2007 introduced a new Ribbon user interface. Microsoft states that the interface makes it easier and quicker for users to get the results they want. The developers extend this interface by using the XML markup that the add-in should return to the host through an appropriate COM interface.

Add-in Express supports the Ribbon designer provided by VS 2008 and VS 2010 for Office 2007 - 2010 add-ins. If you have such a designer in your add-in project, then any of the Add-in Express Ribbon controls below will not be considered when generating the markup. The Add-in Express Ribbon controls are useful when creating the Ribbon interface for an add-in targeting Office 2003 and up; when such add-in is run in Office 2007 or 2010, Add-in Express generates the XML markup automatically.

Add-in Express provides some 50 Ribbon-related components that undertake the task of creating the markup. Also, there are 5 visual designers that allow creating the Ribbon 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 (Backstage View). To provide some sort of compatibility for you, ADXRibbonOfficeMenu will map 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 Office Ribbon UI designer.

Custom task panes for Outlook, Excel, PowerPoint

Advanced custom task panes in Office 2003 - 2010

Add-in Express provides the technology to show custom task panes in Outlook, Excel, Word and PowerPoint, versions 2003-2010. See custom Outlook, Excel, PowerPoint task panes for details.

Native Office custom task panes

Add-in Express supports native Office custom task panes by equipping the Add-in module with the TaskPanes property. Add a UserControl to your project, add an item to the TaskPanes collection, and set up the item by choosing the control in the ControlProgId property and filling in the Title property. Add your reaction to the TaskPaneXXX event series of the Add-in module and the DockPositionStateChange and VisibleStateChange events of the task pane.

Command bar components

Microsoft Office 2000 - 2003 supplied us with a common term for Office toolbars, menus, and context menus. This term is command bar. Microsoft Office 2000-2003 supplied us with a common term for Office toolbars, menus, and context menus. This term is "command bar". Add-in Express provides toolbar, menu, and context menu components that allow tuning up targeted command bars at design-time. There are also Outlook-specific versions of these components. Every such component provides a visual designer available in the Controls property of the component. The screenshot below shows the visual designer for the toolbar component that creates a custom toolbar with a button. Note that this screenshot was captured when creating a sample Microsoft Office add-in.

Note. You can still use command bar controls in Office 2007-2010 add-ins. To do this, set the UseForRibbon property of the command bar component to True. In this case, the controls will be added to the Add-ins tab of the host application's Ribbon UI.

Toolbar

To add a toolbar to the host application, use the Add CommandBar command. It adds an ADXCommandBar to the module. Its most important property is CommandBarName. If its value is equal to any built-in command bar of the host application, then you are connecting to a built-in command bar. Otherwise, you are creating a new command bar. To find out the built-in command bar names, use our free Built-in Controls Scanner utility.

To position your toolbar, use the Position property that allows docking your toolbar to the top, right, bottom, or left edges of the host application window. You can also leave your toolbar floating. For a fine positioning, you use the Left, Top, and RowIndex properties. To show a pre-2007 toolbar in the Add-ins tab in Office 2007 and 2010, set the UseForRibbon property of the corresponding command bar component to true. To speed up add-in loading when connecting to an existing command bar, set the Temporary property to False. To make the host application remove the command bar when the host application quits, set the Temporary property to true.

See how to add custom .NET controls to Office toolbar in five easy steps.

Main menu

By using the Add Main Menu command of the add-in module, you add an ADXMainMenu.

Like the toolbar component, it provides a visual designer for the Controls property. To add a custom top-level menu item, just add a popup control to the command bar. Then you can populate it with other controls. Note, however, that for all menu components, the controls can be buttons and pop-ups only. To add a custom button to a built-in top-level menu item, you specify the ID of the top-level menu item in the Id property of the button control. For instance, the ID of the File menu item in all Office applications is 30002. See more details about IDs of command bar controls in Using existing command bar controls.

In main applications of Office 2007, they replaced the command system with the Ribbon UI. Therefore, instead of adding custom items to the main menu, you need to add them to a custom or built-in Ribbon tab. Also, you can add custom items to the menu of the Office Button in Office 2007. In Office 2010, they abandoned the Office button in favor of the File Tab, also known as Backstage View. Add-in Express provides components allowing customizing both the File Tab and the Ribbon Office Menu, see Step 11. Customizing the Ribbon UI in Developing Office COM add-in. Note, if you customize the Office Button menu only, Add-in Express will map your controls to the Backstage View when the add-in is run in Office 2010. If, however, both Office Button menu and File tab are customized at the same time, Add-in Express ignores custom controls you add to the Office Button menu.

Context menu

In Office 2003-2007, context menus are in fact command bars and you can customize them in the same way as any other command bars. In Office 2010, you can customize a context menu using via the Ribbon XML. Accordingly, Add-in Express provides two components: a commandbar-based (ADXContextMenu) and Ribbon-based (ADXRibbonContextMenu).

Note.It is unambiguously stated by the PowerPoint development team that PowerPoint 2007 doesn't support customizing context menus with command bar controls. However, some context menus in PowerPoint 2007 are still customizable in this way.

The Add ADXContextMenu command of the add-in module adds an ADXContextMenu, which allows adding a custom command bar control to any context menu available in all Office 2003-2007 applications. To specify the context menu you want to connect to, just choose the name of the context menu in the CommandBarName combo.

Please note that the context menu names for this property were taken from Office 2007, the last Office version that introduced new commandbar-based context menus. That is, it is possible that the targeted context menu is not available in Office 2003. In Office 2010 and higher, you can customize both commandbar-based and Ribbon-based context menus. See Step 8. Customizing context menus and Step 9. Customizing context menus in Outlook in Office add-in sample and Outlook plug-in sample respectively.

Outlook toolbars and main menus

While the look-n-feel of all Office toolbars is the same, Outlook toolbars differ from toolbars of other Office applications. They are different for the two main Outlook window types - for Outlook Explorer and Outlook Inspector windows. Accordingly, Add-in Express provides you with Outlook-specific command bar components that work correctly in multiple Explorer and Inspector windows scenarios: ADXOlExplorerCommandBar and ADXOlInspectorCommandBar. In the same way, Add-in Express provides Outlook-specific versions of the Main Menu component: ADXOlExplorerMainMenu and ADXOlInspectorMainMenu.

All of the components above provide the FolderName, FolderNames, and ItemTypes properties that add context-sensitive features to the command bar. For instance, you can choose your toolbar to show up for e-mails only. To achieve this, just choose a correct checkbox in the ItemTypes property editor.

Connecting to existing command bars

In Office, all command bars are identified by their names. Keeping it in mind, you can add a custom or built-in control to any existing command bar. The only thing you need to know is the command bar name. Use our free Built-in Controls Scanner utility to get the names of all command bars and controls existing in any Office application. Then you can specify any of the command bar names in the CommandBarName property of the appropriate command bar component.

Command bar controls

Command bar components provide the Controls property. Clicking it in the Properties window in Visual Studio, invokes the appropriate visual designer. On the screenshot below, you see the visual designer of the ADXCommandBar component.

Using the designer, you can populate your command bars with controls and set up their properties at design-time. At run-time, you use the Controls collection of your command bar. Every control (built-in and custom) added to this collection will be added to the corresponding toolbar at your add-in startup.

Command bar control properties and events

The main property of any command bar control (they descend from ADXCommandBarControl) is the Id property. To add a built-in control to your toolbar, specify its ID in the corresponding property of the command bar control component. find out the Ids of every built-in control in the host application, use the free utility to find commandbar control IDs. To add a custom control to the toolbar, leave the Id unchanged.

To add a separator before any given control, set its BeginGroup property to true.

Set up a control's appearance using a large number of its properties, such as Enabled and Visible, Style and State, Caption and ToolTipText, DropDownLines and DropDownWidth, etc. You also control the size (Height, Width) and location (Before, AfterId, and BeforeId) properties. To provide your command bar buttons with a default list of icons, drop an ImageList component onto the add-in module and specify the ImageList in the Images property of the module. Do not forget to set the button's Style property to either adxMsoButtonIconAndCaption or adxMsoButtonIcon.

Use the OlExplorerItemTypes, OlInspectorItemTypes, and OlItemTypesAction properties to add context-sensitivity to controls on Outlook-specific command bars. The OlItemTypesAction property specifies an action that Add-in Express will perform with the control when the current item's type coincides with that specified by you.

To handle user actions, use the Click event for buttons and the Change event for edit, combo box, and drop down list controls. Use also the DisableStandardAction property available for built-in buttons added to your command bar. To intercept events of any built-in command bar control, see Built-in Control Connector.

Command bar control types

The Office Object Model contains the following control types available for toolbars: button, combo box, and pop-up. Using the correct property settings of the combo box component, you can extend the list with edits and dropdowns. Nevertheless, this list is extremely short. Add-in Express allows extending this list with any .NET control with Toolbar Controls for Microsoft Office.

Please note that due to the nature of command bars, menu and context menu items can only be buttons and pop-ups (item File in any main menu is a sample of a popup).

Using existing command bar controls

Add-in Express connects to built-in controls using the Id property. That is, if you specify the ID of a control not equal to 1 and this control exists on the specified command bar, Add-in Express connects to this control and ignores all other properties. If the control is not found, Add-in Express creates it. Using this approach, you can override the standard behavior of a built-in button on a given toolbar:

• Add a new toolbar component to the module
• Specify the toolbar name in the CommandBarName property
• Add an ADXCommandBarButton to the command bar
• Specify the ID of the built-in button in the ADXCommandBarButton.Id property
• Set DisableStandardAction to true
• And finally, handle the Click event of the button

Outlook property page

Outlook allows extending its Options dialog with custom pages. You see this dialog when you choose Tools | Options menu. In addition, Outlook allows adding such a page to the Folder Properties dialog. You see this dialog when you choose the Properties item in the folder context menu. You create such pages using the Outlook Property Page component.

In the Add New Item Dialog, choose the Outlook Options Page item to add a class to your project. This class is a descendant of the System.Windows.Forms.UserControl class. It allows creating Outlook property pages using its visual designer. Just set up the property page properties, place your controls onto the page, and add your code. To add this page to the Outlook Options dialog, select the name of your control class in the PageType combo of ADXAddinModule and enter some characters into the PageTitle property.

To add a page to the Folder Properties dialog for a given folder(s), you use the FolderPages collection of the Add-in Express Module. Run its property editor and add an item (of the ADXOlFolderPage type). You connect the item to a given property page through the PageType property. Note, the FolderName, FolderNames, and ItemTypes properties of the ADXOlFolderPage component work in the same way as those of Outlook-specific command-bars.

Specify reactions required by your business logics in the Apply and Dirty event handlers. Use the OnStatusChange method to raise the Dirty event, the parameters of which allow marking the page as Dirty.

Option pages and folder property pages

In the Add New Item dialog, choose the Outlook Options Page item to add a class to your project. This class is a descendant of the System.Windows.Forms.UserControl class. It allows creating Outlook Options Page controls using its visual designer. Just set up its properties, place your controls onto the page, and add your code. Add this page to the Outlook Options dialog (menu Tools / Options): select the name of your control class in the PageType combo of Add-in Express module and enter some characters into the PageTitle property.

Use the same technique with the FolderPages collection of the Add-in Express module to add the page to the Folder Properties dialog of a given folder. Specify reactions required by your business logics in the Apply and Dirty event handlers. Use the OnStatusChange method to raise the Dirty event, the parameters of which allow marking the page as Dirty.

Built-in Control Connector

Built-in controls of an Office application have predefined IDs. The Built-in Control Connector component allows overriding the standard action for any built-in control without adding it onto any command bar.

Add a built-in control connector onto the module. Set its Id property to the ID of your command bar control. To connect the component to all instances of the command bar control having this ID, leave its CommandBar property empty. To connect the component to the control on a given toolbar, specify the toolbar in the CommandBar property. To override the default action of the control, use the Action event. The component traces the context and when any change happens, it reconnects to the currently active instance of the command bar control with the given Id, taking this task away from you. To add a built-in control onto your command bar, see Command bar control properties and events.

Keyboard shortcuts

Every Office application provides built-in keyboard combinations that allow shortening the access path for commands, features, and options of the application. Add-in Express allows adding custom keyboard combinations and processing both custom and built-in ones. Add a Keyboard Shortcut component onto the add-in module, choose or specify the keyboard shortcut you need in the ShortcutText property, set the HandleShortCuts property of the module to true and process the Action event of the component.

More about creating custom application-level keyboard shortcuts.

Outlook Bar Shortcut Manager component

Outlook provides us with the Outlook Bar (Navigation Pane in Outlook 2003). The Outlook Bar displays Shortcut groups consisting of Shortcuts that you can target a Microsoft Outlook folder, a file-system folder, or a file-system path or URL. You use the Outlook Bar Shortcut Manager to customize the Outlook Bar with your shortcuts and groups.

This component is available for ADXAddinModule. Use the Groups collection of the component to create a new shortcut group. Use the Shortcuts collection of a short group to create a new shortcut. To connect to an existing shortcut or shortcut group, set the Caption properties of the corresponding ADXOlBarShortcut and / or ADXOlBarGroup components equal to the caption of the existing shortcut or shortcut group. Please note that there is no other way to identify the group or shortcut.

That is why your shortcuts and shortcut groups must be named uniquely for Add-in Express to remove only the specified ones (and not those having the same names) when the add-in is uninstalled. If you have several groups (or shortcuts) with the same name, you will have to remove them yourself. Depending on the type of its value, the Target property of the ADXOlBarShortcut component allows you to specify different shortcut types. If the type is Outlook.MAPIFolder, the shortcut represents a Microsoft Outlook folder. If the type is String, the shortcut represents a file-system path or a URL. No events are available for these components.

More about customizing Outlook bar and Navigation pane.

Events and Outlook Event classes

Outlook and Excel differ from other Office applications because they have event-raising objects not only at the topmost level of their object models. These exceptions are the Folders and Items classes as well as all item types in Outlook, and the Worksheet class in Excel. Naturally, you need to handle events from these sources. Add-in Express event classes provide you with version independent components that ease the pain of handling such events. The event classes also handle releasing of COM objects required for their functioning.

At design-time, you add an event class to the project (see Add New Item dialog) and use its event procedures to write the code for just one set of event handling rules for a given event source type, say, for the Items collection of the MAPIFolder class in Outlook 2003; in Outlook 2007, you can also use the Folder class. To implement another set of event handling rules for the same event source type, you add another event class to your project.

At run-time, you connect an event class instance to an event source using its ConnectTo method. To disconnect the event class from the event source you use the RemoveConnection method. To apply the same business rules to another event source of the same type (say, to items of another folder), you create a new instance of the same event class.

What follows below is the source code of a newly added event class that processes the events of the Items collection of the MAPIFolder class in Outlook (also the Folder class in Outlook 2007).

Imports System

'Add-in Express for VSTO
'Outlook Items Events Class
Public Class OutlookItemsEventsClass1
    Inherits AddinExpress.VSTO.ADXOutlookItemsEvents

    Public Sub New(ByVal ADXModule As AddinExpress.VSTO.ADXOutlookModule)
        MyBase.New(ADXModule)

    End Sub

    Public Overrides Sub ProcessItemAdd(ByVal Item As Object)
      MsgBox("The item with subject '" + Item.Subject + _
         "' has been added to the Inbox folder")
   End Sub

    Public Overrides Sub ProcessItemChange(ByVal Item As Object)
        'TODO: Add some code
    End Sub

    Public Overrides Sub ProcessItemRemove()
        'TODO: Add some code
    End Sub

End Class