VSTO components to add Outlook 2007 Ribbon tabs,
context menu, commandbar controls in C#, VB. NET
Add-in Express™ |
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 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 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 for Office 2007 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; when such add-in is run in Office 2007, Add-in Express generates the XML markup automatically.
Add-in Express provides some 20 Ribbon-related components that undertake the task of creating the markup. You start with ADXRibbonTab, ADXRibbonOfficeMenu, and ADXRibbonQuickAccessToolbar components. You add controls to a tab or menu using a visual designer that allows you to see all the items of a tab or menu at a glance. Microsoft requires developers to use the StartFromScratch parameter (see the StartFromScratch property of the add-in module) when customizing the 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.
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. 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.
Please note that you can still use command bars in Office 2007 add-ins. In this case, their 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, 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.
Context menu
The Add Context Menu command of the add-in module adds an ADXContextMenu, which allows you to add a custom command bar control to any context menu available in all Office applications except for Outlook 2000. To specify the context menu you want to connect to, just choose its name in the CommandBarName combo. The context menu names for this combo were taken from Office 2007. That is, it is possible that the targeted context menu is not available in Office 2003.
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.
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. More about custom task panes.
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