Components to customize Office 2007 Ribbon bar, command bars,
context menus, controls, task panes in VB.NET, C#, C++.

Add-in Express Home > Add-in Express.NET > Online Guide > Components

Add-in Express .NET components

How to add an Add-in Express component to the Add-in Express designer

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

Office 2007 Ribbon components

Office 2007 presented 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 about 20 Ribbon-related components to give you the full power of the Ribbon UI customization features. You start with ADXRibbonTab, ADXRibbonOfficeMenu and ADXRibbonQuickAccessToolbar that get the task of creating the markup upon themselves. You add controls to a ribbon tab or menu using the convenient tree-view-like editor that allows you to see all the items of the ribbon menu or tab at a glance. Please, note Microsoft require developers to use the StartFromScratch parameter (see the StartFromScratch property of  AddinModule) 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.

All of them are available in the visual designer which you access by clicking the Controls property in the Properties window: Please note that Microsoft require developers to use the StartFromScratch parameter (see the StartFromScratch property of the add-in module) when customizing the Quick Access Toolbar. Note also that to use pre-Office2007 command bars in the Office 2007 add-ins, you must explicitly set to true the UseForRibbon property of the appropriate command bar components. In this case, your toolbars are added to the Add-ins ribbon tab. To re-purpose a Ribbon control, you use the Ribbon Command component. For instance, the following settings make the Copy command in Word 2007 disabled:

Also, note, to use pre-Office2007 command bars in the Office 2007 add-ins, you must explicitly set to True the UseForRibbon property of the appropriate command bar components. In this case, your toolbars are added to the Add-ins ribbon tab. See also Office 2007 Ribbon tab designer and code samples in C# and VB.NET to create a ribbon tab with a custom ribbon button.

Command bar: toolbar, menu, and context menu

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 which allow tuning up targeted command bars at design-time. Every such component provides a visual designer available in the Controls property of the component.

For instance, the screenshot above shows a visual designer for the toolbar component that creates a custom Office toolbar with two buttons. One of the buttons is has the Visible property set to false.

Please note! To create Outlook toolbars, menus, and context menus, you need to use Outlook-specific versions of command bar components provided by Add-in Express.

Toolbar

To add a toolbar to your add-in, use the "Add CommandBar" command available in the context menu of the add-in module. It adds an ADXCommandBar to the module. Its most important property 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 command bar. 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 names of built-in command bars , use our free Built-in Controls Scanner utility.

To position your toolbar, use the Position property which allows docking your toolbar to the top, right, bottom, or left sides 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.

Main menu

By using the Add Main Menu command of the add-in module, you add an ADXMainMenu, which is intended for customizing main menu in an Office application that you specify in the SupportedApp property.

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 about IDs of command bar controls in Connecting to 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 Office 2007, 2003 and 2002 (XP) applications, but is not available in Office 2000 applications. The component allows connecting to a single context menu of a single host application. Like for the Main Menu component, you must specify the SupportedApp property. 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 combo were taken from Office 2007. That is, it is possible that the context menu you are targeting to is not available in Office 2000 - 2003.

Outlook toolbar and main menu

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: just choose a correct checkbox in the ItemTypes property editor.

Office 2007 custom task panes

To allow further customization of its applications, Office 2007 provides custom task panes. Add-in Express supports task panes 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 add-in module and the DockPositionStateChange and VisibleStateChange events of the task pane item. Use the OfficeColorSchemeChanged event and the OfficeColorScheme property for your task pane colors to conform to the current Office 2007 color scheme.

Find more about special features provided by Add-in Express for customizing Excel GUI and a sample project of creating a custom Excel task panes.

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 picture below, you can see the visual designer to populate a toolbar with custom controls.

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. To find out the Id of every built-in control in any Office application, use our free Built-in Controls Scanner utility. 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 (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 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 button 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.

Command bar control types

The Office Object Model includes 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 .NET allows extending this list with any control of your choice using the 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).

Connecting to existing command bar controls

Placeholders in the main menu components (see Main Menu) demonstrate that 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 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 
• Now you should handle the Click event

The Office Object Model (OOM) contains 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 .NET allows extending this list with any control of your choice using the Toolbar Controls for Microsoft Office, which is a plug-in for Add-in Express.

What follows below 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).

See also a sample project showing how to customize Outlook toolbar with .NET controls.

Built-in Control Connector

Built-in controls of an Office application have predefined IDs. You find the IDs using the free Built-in Controls Scanner utility. The Built-in Control Connector component allows overriding the standard action for any built-in control without the necessity to add it onto any command bar.

Add a built-in control connector onto the 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 command bar control with the given Id, taking away this task from you.

Keyboard Shortcut component

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 the component onto ADXAddinModule, 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.

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 for creating 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.

Outlook Forms Manager component

The Outlook Forms Manager component is available for ADXAddinModule only. It is the core component of the Advanced Outlook 2007 - 2000 Form Regions technology.

Excel Task Panes Manager component

This is the core component of the technology described in Advanced Custom Task Panes in Excel 2000-2007.

Outlook Property Page component

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.

Smart Tag component

The Kind property of the ADXSmartTag component allows you to choose one of two text recognition strategies: either using a list of words in the RecognizedWords string collection or implementing a custom recognition process based on the Recognize event of the component. Use the ActionNeeded event to change the Actions collection according to the current context. The component raises the PropertyPage event when the user clicks the Property button in the Smart Tags tab (Tools / AutoCorrect Options menu) for your smart tag. See also how to create Office 2007 smart tag step-by-step.

RTD Topic component

Use the String## properties to identify the topic of your RTD server. To handle RTD Server startup situations nicely, specify the default value for the topic and, using the UseStoredValue property, specify, if the RTD function in Excel returns the default value (UseStoredValue = false) or doesn't change the displayed value (UseStoredValue = true). The RTD Topic component provides you with the Connect, Disconnect, and RefreshData events. The last one occurs (for enabled topics only) whenever Excel calls the RTD function. See also how to build a sample Excel Real-Time Data project.

Application-level events

ADXAddinModule provides events for all Office applications through the Add Events command that shows the following dialog:

 
Select the application you need and click OK. This adds and/or removes appropriate Add-in Express event components to the module. Use the event handlers of an Add-in Express event component to respond to the host application's events. You may need to process other events provided by Outlook and Excel. If this is the case, see Event Classes below.

Add-in Express 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 Worksheet in Excel, and Folders, Items and all Item sorts in Outlook. Naturally, you need to handle events from these sources. Add-in Express Event classes provide you with components that ease the pain of handling such events. Add-in Express Event classes are host-version independent. The Add-in Express event classes also handle releasing of COM objects required for their functioning.

At design-time, you add an Add-in Express event class to the project and use its event procedures to write the code for just one set of event handling rules for a given event source type (say, Items collection of an Outlook folder). To implement another set of event handling rules for the same event source type, you add another Add-in Express event class to your project.

At run-time, you connect an Add-in Express event class instance to an event source using its ConnectTo method. To disconnect the Add-in Express 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 follow below is the source of a newly added Event Class that processes the events of the Items collection of the MAPIFolder class in Outlook.

Imports System
 
'Add-in Express Outlook Items Events Class
Public Class OutlookItemsEventsClass1
   Inherits AddinExpress.MSO.ADXOutlookItemsEvents

   Public Sub New(ByVal ADXModule As AddinExpress.MSO.ADXAddinModule)
      MyBase.New(ADXModule)
   End Sub

   Public Overrides Sub ProcessItemAdd(ByVal Item As Object)
      'TODO: Add some code
   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

MSForms control

This command is available for ADXExcelSheetModule and ADXWordDocumentModule. When run, it displays the following dialog:

 
Select the control you need to connect to and click OK. Add-in Express adds an appropriate MS Forms Control Connector to the module. Use the Control Name property of the connector to specify the underlying control on the Excel worksheet or Word document. Respond to the events provided by the control connector.

Note! All Add-in Express .NET components support C#, C++, VB.NET and Chrome.

Back to Add-in Express.NET homepage