Customize Office commandbar / toolbar:
add button, context menu items in VB.NET, C#, C++
|
Add-in Express™ Add-in Express Home > Add-in Express for Office and .NET > Online Guide > Add-in Express components > CommandBar components This page describes components for creating the UI of your add-in in Office 2000 - 2003 and in non-Ribboned applications of Office 2007: Outlook 2007 (Explorer windows only), Publisher 2007, Visio 2007, Project 2007 and InfoPath 2007. In all other applications, the command bar UI has been superseded by the new Ribbon user interface. Nevertheless, all command bars and controls are still available in those Office applications and you may want to use this fact in your code. Also, custom command bar controls created by your add-in will be shown on the Add-ins tab in the Ribbon UI but the best way is to support both CommandBar and Ribbon user interfaces in your add-in, To do this, you need to add both command bar and ribbon components onto the add-in module. The command bar UI of your add-in includes custom and built-in command bars as well as custom and built-in command bar controls. Command bar is a common term for traditional toolbars, menus, and context menus.
Office CommandBar UI componentsAdd-in Express provides toolbar, main menu, and context menu components that allow tuning up targeted command bars at design time. There are also Outlook-specific versions of toolbar and main menu components. Every such component provides an in-place visual designer. For instance, the screenshot below shows a visual designer for the toolbar component that creates a custom toolbar with a button.
Note.To create toolbars and menus in Outlook, you need to use Outlook-specific versions of command bar components. See Outlook toolbars and main menu. Using visual designers, you populate your command bars with controls and set up their properties at design-time. At run-time, you use the Controls collection provided by every command bar component. Every control (built-in and custom) added to this collection will be added to the corresponding toolbar at your add-in startup. See also How command bars and their controls are created and removed? Office toolbar componentsTo add a toolbar to the host application, use the Add ADXCommandBar command available in the Add-in Express Toolbox. It places a new ADXCommandBar component onto the module. The most important property of the 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 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 built-in command bar names, use our free Built-in Controls Scanner utility.
To position a toolbar, use the Position property that allows docking the 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-2010, set the UseForRibbon property of the corresponding command bar component to true. Pay attention to the SupportedApps property. You use it to specify if the command bar will appear in some or all host applications supported by the add-in. Using several command bar components with different values in their SupportedApps properties is useful when creating toolbars for Outlook and Word, see below. Unregister your add-in before you change the value of the SupportedApps property. 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. However, this is the general rule only. If your add-in supports Outlook or Word, see How command bars and their controls are created and removed. You need to unregister the add-in before changing the value of this property. Main menuBy using the Add Main Menu command of the Add-in Express Toolbox, you add an ADXMainMenu, which is intended for customizing the main menu (menu bar) of an Office application, which you specify in the SupportedApp property of the component.
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, controls can be buttons and popups 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 popup control. For instance, the ID of the File menu item (which is a popup control, in fact) in all Office applications is 30002. Find more details about IDs of command bar controls in Connecting to existing command bar controls. In main applications of Office 2007, they replaced the command bar 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 of Microsoft Office COM add-in in the Office COM Add-in sample. 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 or above. 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. Office context menuIn Office 2000-2007, context menus are command bars and they can be customized in the same way as any other command bar. In Office 2010 and 2013, you can customize context menus via the Ribbon XML. Accordingly, Add-in Express provides two components: a commandbar-based (ADXContextMenu) and Ribbon-based (ADXRibbonContextMenu).
The PowerPoint development team explicitly states 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 Express Toolbox creates an ADXContextMenu, which allows adding a custom command bar control to any context menu available in all Office 2000-2007 applications except for Outlook 2000. The component allows connecting to a single context menu of a single host application; to customize several context menus, add an appropriate number of context menu components. Like for the ADXMainMenu 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 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 a pre-2007 Office version.
In Office 2010 and 2013, you can customize both commandbar-based and Ribbon-based context menus. See Step 8. Customizing context menus in Office and Step 9. Customizing context menus in Outlook. Outlook toolbar and menu barWhile 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 emails only. To get this, just check the correct checkbox in the ItemTypes property editor. Connecting to existing command barsIn Office, all command bars are identified by their names. Specifying the name of a toolbar in the ADXCommandBar.CommandBarName property means referring to that toolbar. Use our free Built-in Controls Scanner to get the names of all built-in command bars in any Office 2000-2010 application. Connecting to existing CommandBar controlsAny CommandBar Control component connects to a built-in control using the Id property. That is, if you set the Id property of the component to an integer other than 1 and a built-in control having the same ID exists on the specified command bar, the component connects to the built-in control and ignores all other properties. If no such control is found, the component creates it on the command bar. Using the approach below, you can override the standard behavior of a built-in button on a given toolbar:
Also, you can use the Built-in Control Connector component, which allows overriding the standard action for any built-in control (without adding it onto any command bar):
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. How command bars and their controls are created and removed?When your add-in is being loaded by the host application, the add-in module raises the AddinInitialize event before processing command bar components. In most Office applications except for Outlook, this is the last event in which you may add/remove/modify command bar components onto/from/on the add-in module. For instance, you can delete some or all of the command bar components if the environment in which your add-in is being loaded doesn't meet some requirements. After that event, Add-in Express scans components on the add-in module, creates new or connects to existing toolbars and raises the AddinStartupComplete event. All command bar and commandbar control components provide the Temporary property of the Boolean type. Temporary toolbars and controls are not saved when the host application quits. This causes the creation of such toolbars and controls at every add-in startup. Permanent toolbars and controls are saved by the host application and restored at startup; i.e. permanent toolbars allow your add-in to load faster. But Word and Outlook require specific approaches to temporary/permanent toolbars and controls. Let's look at how command bars and controls are removed, however. When the user turns the add-in off in the COM Add-ins dialog, Add-in Express uses a method of the IDTExtenisbility2 interface to remove the command bars and controls. When the add-in is uninstalled, and there are non-temporary toolbars and controls in the add-in, Add-in Express starts the host application and removes the toolbars and controls. That is, temporary toolbars and controls allow your add-in to uninstall faster. Let's get back to Outlook and Word, however. It is strongly recommended that you use temporary command bars and controls in Outlook add-ins. If they are non-temporary, Add-in Express will run Outlook to remove the command bars when you uninstall the add-in. Now imagine Outlook asking the user to select a profile or enter a password... In Word add-ins, we strongly advise making both command bars and controls non-temporary. Word removes temporary command bars. However, it doesn't remove temporary command bar controls, at least some of them; it just hides them. When the add-in starts for the second time, Add-in Express finds such controls and connects to them. Accordingly, because Add-in Express doesn't change the visibility of existing controls, the controls are missing in the UI. Note that main and context menus are command bars. That is, in Word add-ins, custom controls added to these components must have Temporary = False, too. If you set Temporary = True for such controls (say, by accident), they will not be removed when you uninstall your add-in. That happens because Word has another peculiarity: it saves temporary controls when they are added to a built-in command bar. And all context menus are built-in command bars. To remove such controls, you will have to write some code or use a simple way: set Temporary to false for all controls, register the add-in on the affected PC, run Word. At this moment, the add-in finds this control and traces it from this moment on. Accordingly, when you unregister the add-in, the control is removed in a standard way. Several notes:When debugging your add-in, you need to unregister it before changing the Temporary property. After changing the property, register the add-in anew. For every permanent toolbar (ADXCommandBar.Temporary = False), Add-in Express creates a registry key in {HKLM or HKCU}\Software\Microsoft\Office\{host application}\Addins\{your add-in}\Commandbars when the host application quits. The key is used to detect a scenario in which the user removes the toolbar form the UI: if both the key and the toolbar are missing, Add-in Express creates the toolbar. You may need to use this fact in some situations. Command bars in the Ribbon UIBy default, Add-in Express doesn't show custom command bar controls or main menu items when your add-in is loaded by a Ribbon-enabled application. This behavior is controlled by the UseForRibbon property of the ADXCommandBar, ADXOlExplorerCommandBar,ADXOlInspectorCommandBar, ADXMainMenu, ADXOlExplorerMainMenu, or ADXOlInspectorMainMenu components. If you set it to True, the Ribbon places corresponding controls on the Add-ins tab in the Ribbon UI. Usually, you set that property at design time. You can also set this property at run time but this must be done before Add-in Express processes the corresponding component to create a command bar and its controls. The best moment for doing this is the AddinInitialize event of ADXAddinModule. As to the context menus, Ribbon-enabled applications of the Office 2007 suite demonstrate lack of coordination: most of them support customizing their context menus with command bar controls (remember, in Office 2007, context menus are still command bars) but the PowerPoint development team explicitly states that PowerPoint 2007 doesn't support this. Note that Office 2010 and above provides support for both commandbar-based and Ribbon-based context menus. see Step 9. Customizing Outlook context menus and Step 8. Customizing Office context menus. Command bar control properties and eventsThe main property of any command bar control (they descend from ADXCommandBarControl) is the Id property. A custom command bar control has ID = 1; all built-in controls have IDs of their own. To add a custom control to the toolbar, leave the Id unchanged. 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 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. See also Transparent icon on a CommandBarButton. Use the OlExplorerItemTypes, OlInspectorItemTypes, and OlItemTypesAction properties to add context-sensitivity to your 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 control, see Connecting to existing CommandBar controls. Command Bar control typesThe Office Object Model contains the following control types available for toolbars: button, combo box, and popup. 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 (see Toolbar Controls for Microsoft Office). You can add controls using that technology onto old-fashioned toolbars; that possibility is not available for Office applications showing the Ribbon UI. Note. that due to the nature of command bars, menu and context menu items can only be buttons and popups (item File in any main menu is a sample of a popup). |
