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

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

Add-in Express for VSTO components

Add-in Express module

The Add-in Express module is the core component of Add-in Express for VSTO. It centralizes all programming logics in one place. Its designer allows adding other Add-in Express components and sets their properties at design-time. It also provides all events of the host application. Note, some Outlook-specific events as well as the Outlook Option page (Folder Property pages) should be added via the Add New Item dialog.

For Word 2003 and Excel 2003 VSTO projects, the Add-in Express module provides the collection of Action Panes. For Outlook add-ins, it provides the collection of Folder Property pages, as well as the title and the form to be displayed in the Outlook Options dialog (menu Tools / Options). For Outlook add-ins, you specify the Options page and Folder Property pages (see Outlook property page).  For Office 2007 add-ins (Outlook, Excel, Word, PowerPoint, Visio, and InfoPath) the Add-in Express module provides the collection of Task Panes.

Below there is the list of Add-in Express for VSTO components that can be placed onto the Add-in Express module:

• Office 2007 Ribbon components
• CommandBar
• ExplorerCommandBar - Outlook-specific
• InspectorCommandBar - Outlook-specific
• Built-in Control Connector
• Keyboard Shortcut
• Outlook Bar Shortcut - Outlook-specific
• Outlook Forms Manager

Use the OnStartupComplete and OnBeginShutdown events to handle the add-in startup and shutdown.

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

To add any Add-in Express for VSTO component onto an Add-in Express 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 2007 Ribbon components

Office 2007 presented us 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 COM add-in should return to the host through the appropriate interface. Add-in Express provides some 20 Ribbon-related components to give you the full power of the Office 2007 Ribbon UI customization features. You start with ADXRibbonTab, ADXRibbonOfficeMenu, and ADXRibbonQuickAccessToolbar that get the task of creating the markup upon them. You add controls to a tab or menu using the convenient tree-view-like editor that allows you to see all the items of the tab or menu at a glance. Please, note Microsoft require developers to use the StartFromScratch parameter (see the StartFromScratch property of AddinModule) when customizing Quick Access Toolbar.

ADXRibbonTab and ADXRibbonOfficeMenu support all types of Ribbon controls including regular and button groups; regular, edit, combo and check boxes; buttons and split buttons; labels and dropdown lists; galleries and menus; separators and dialog launchers. Also, note, you can use pre-Office2007 command bars in the Outlook 2007 add-ins. In this case, your toolbars will be added to the Add-ins ribbon tab. See also Office Ribbon UI designer.

Office 2007 custom task panes

To allow further customization of its applications, Office 2007 provides custom task panes. Add-in Express supports task panes for Excel and Outlook by equipping the COM 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 COM Add-in module and the DockPositionStateChange and VisibleStateChange events of the task pane. More about custom Outlook, Excel task panes.

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. While look-n-feel of all Office command bars is the same, Outlook command bars are different from command bars of other Office applications. They are different for the two main Outlook window types – for Outlook Explorer and Outlook Inspector windows. Additionally, different Outlook Inspector window types show different command bars. Accordingly, Add-in Express provides you with ADXCommandBar, ADXOlExplorerCommandBar, ad ADXOlInspectorCommandBar components.

To add a command bar to your project, use one of the following Add-in Express module commands:

• Add CommandBar
• Add ExplorerCommandBar - Outlook-specific
• Add InspectorCommandBar - Outlook-specific

The main property of any CommandBar component is CommandBarName. If its value is not equal to the name of any built-in command bar of the host application, then you are creating a new toolbar. 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. To find out the built-in command bar names, use the free utility for finding Built-in Controls Scanner .

To position your command bar, use the Position, Left, Top, and RowIndex properties. 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. Outlook-specific toolbars provide the FolderName, FolderNames, and ItemTypes properties that add context-sensitive features to the toolbar. See how to add custom .NET controls to Office toolbar in five easy steps.

Command Bars in Office 2007

You can use pre-Office2007 command bars in the Office 2007 add-ins. In this case, your toolbars will be added to the Add-ins ribbon tab.

Command bar controls

The Office Object Model (OOM) includes the following command bar controls CommandBarButton, CommandBarComboBox, and CommandBarPopup. Using the correct property settings of the CommandBarComboBox 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 control of your choice using the Add-in Express Extensions for Microsoft Office Toolbars, which is a plug-in for Add-in Express.

Below there is a list of controls available in the ADXCommandBarControl Collection Editor dialog (it opens when you edit the Controls collection of a command bar):

• ADXCommandBarButton
• ADXCommandBarComboBox
• ADXCommandBarEdit
• ADXCommandBarPopup
• ADXCommandBarDropDownList
• ADXCommandBarControl (you use this item to add built-in controls to your command bars)
• ADXCommandBarAdvancedControl (you use this item with the Toolbar Controls for Microsoft Office)

Please, note that due to the nature of command bars (remember a 'command bar' stands for toolbar, menu, and context menu), [context] menu items can be buttons, combo boxes, and pop-ups. Populate your command bar using the Controls collection both at run-time and at design-time. Every control (built-in and custom) added to this collection will be added to the corresponding toolbar at your project startup.

The main property of any command bar control is the Id property. To add a built-in control to your toolbar, specify its Id in the Id property of the command bar control. To 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 property unchanged.

Set up a control's appearance using a great number of its properties, such as Enabled and Visible, Style and State, Caption and ToolTipText, DropDownLines and DropDownWidth, etc. You also control the size (Top, Left, 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 to the Add-in Express Module and specify the ImageList in the Images property of the Add-in Express module. Don’t forget to set the button's Style property to either adxMsoButtonIconAndCaption or adxMsoButtonIcon. Use the DisableStandardAction property available for command bar buttons.

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 on the control when the current item's type coincides with that specified by you. Use the Click event for Button and the Change event for Edit, ComboBox and DropDownList controls.

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

This component allows overriding the standard action for any built-in control without the necessity to add it onto any toolbar. Add a BuiltinControlConnector onto the Add-in Express module. Set its Id property to the command bar control ID from your host application. To connect the component to the command bar control, 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 the context changes it reconnects to the currently active instance of the commandbar control with the given Id taking away this task from you.

Keyboard shortcuts

Add the component to the Add-in Express module, choose the keyboard shortcut you need in the ShortcutText property, set the HandleShortCuts property of the Add-in Express module to true and process the Action event of the KeyboardShortcut 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 to 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, there are no other ways to identify the group or shortcut.

That is why your shortcuts and shortcut groups must be named uniquely for Add-in Express to remove them (and not those with the same names) when the add-in is uninstalled. That is why you have to do this 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 MAPIFolder, the shortcut represents a Microsoft Outlook folder. If the type is a String, the shortcut represents a file-system path or a URL. No events, thanks to Microsoft. More about customizing Outlook bar and Navigation pane.

Outlook Forms Manager component

Customizing Outlook has a long-dated history. To customize Outlook forms you can use the built-in tools purposed for designing and publishing the form. You can use HTML and VBScript to customize folder views, and Outlook Today is an example of this approach. Now you can embed custom .NET forms into the Outlook Explorer and Inspector windows and replace folder views with custom .NET forms. The Outlook Forms Manager component is available for ADXAddinModule only. It is the core component of the Add-in Express Extensions for Microsoft Outlook that is part of Add-in Express VSTO packages.

Action panes / task panes

Add a UserControl to your project, add an item to the ActionPanes (TaskPanes in VSTO 2005 SE) collection of the Add-in Express module and select the UserControl in the TypeName property of the item.

Events and Outlook Event classes

To respond to the application-level, Outlook Explorer, and Outlook Inspector -level events, you use the events of the Add-in Express module. But if you need to respond to the events of the Item (say, BeforeDelete or Send events), Items (ItemAdd, ItemChange, ItemRemove), or Folders (FolderAdd, FolderChange, FolderRemove) objects, you need to add an appropriate event class to your project via the Add New Item dialog. In the event class you specify the event processing logics. Then, in the Add-in Express module events you create an instance of the Event class and call its ConnectTo method passing out the source of events.

Back to Add-in Express for VSTO homepage