Best Practices When Developing Command Bars for the Microsoft Office System
Frank C. Rice
Microsoft® Office System
Summary: Command bars allow users to carry out actions in applications in the Microsoft Office System. Learn about some best practices that you can use when developing command bars. (6 printed pages)
Adding Controls to Command Bars
Using the Visual Studio .NET Shared Add-in Wizard
Adding Command Bars and Menu Items
Deprecated Application Programming Interfaces
Using Themes with Your Add-in
Command bars allow you to carry out actions in applications in the Microsoft® Office System. Command bars come in three forms — toolbars, menus, and pop-up menus. Pop-up menus are displayed in three ways: as menus that drop down from menu bars, as submenus that cascade off menu commands, and as shortcut menus. This article looks at some of the best practices that you should consider when developing command bars.
You can use the following code to put controls at the beginning of each command bar in a document in Microsoft Office Word 2003. This example also includes code that resets the command bars to remove the controls. You can modify the code to use with other applications in the Microsoft Office System.
Sub Word_Command_Bars() On Error GoTo Errorhandler Dim myControl As CommandBarControl Dim cmdBar As CommandBar For Each cmdBar In Application.CommandBars Set myControl = cmdBar.Controls _ .Add(Type:=msoControlPopup, Before:=1, Temporary:=True) With myControl .Caption = cmdBar.Name End With Next Exit Sub Errorhandler: Debug.Print cmdBar.Name Resume Next End Sub Sub Word_Command_Bars_Reset() On Error GoTo Errorhandler Dim cmdBar As CommandBar For Each cmdBar In Application.CommandBars cmdBar.Reset Next Exit Sub Errorhandler: Debug.Print x.Name Resume Next End Sub
The following is a list of tips to assist you when creating custom command bars.
- Only include essential code for connecting to the CommandBar objects in the Connect class. The Connect class implements methods of the IDTExtensibility2 interface that connect to the command bars. Create additional classes for your add-in, as appropriate. Putting all your code in the Connect class makes it difficult to maintain, and harder to reuse the code for other projects.
- Do not use try/catch blocks for program logic, but instead use them for catching runtime errors. Throwing exceptions is costly in terms of performance. In addition, catching exceptions when an If statement is sufficient can mask bugs in the code. As a rule, exceptions should not be thrown during the normal execution of code.
- When writing files to disk, use the following environment variables:
"$APPDATA\Microsoft\Office", if APPDATA is available
- HOMEDRIVE — Returns the drive letter of the local workstation that is connected to the user's home directory. Set based on the value of the home directory. The user's home directory is specified in the Local Users and Groups node of the Computer Management console.
- HOMEPATH — Returns the full path of the user's home directory. Set based on the value of the home directory. The user's home directory is specified in the Local Users and Groups node of the Computer Management console.
- APPDATA — Returns the default data storage location for applications.
Using the user directories avoids the problem of hard-coding paths and directories for storing data, and puts data files in a logical place that users can understand, as opposed to using C:\TEMP.
The following tips apply to using the Shared Add-in Wizard in Visual Studio .NET to create command bars.
- The wizard implements the IDTExtensibility2 interface for you and registers your add-in, both of which save a lot of time and effort. For more information, see Developing with Visual Studio .NET.
- The wizard also creates Setup.msi and an MSI file for easy deployment.
- You should choose the programming language that is appropriate for your needs. For example, Microsoft Visual C# and Microsoft Visual Basic® are easier to use than C++, but you sacrifice performance and code size.
- You should also be sure your Setup project includes all the necessary references to run on the client computer, for example, references to the Microsoft .NET Framework, Common Language Runtime, and so forth.
The following tips apply to adding command bars and menu items.
- Temporary parameter: When adding a custom command bar or menu item, consider whether or not to make it temporary, that is, it is deleted when the Office application is closed. The following table illustrates some of the differences between setting the Temporary parameter to True or False.
Table 1. Comparison showing whether to use the Temporary parameter.
Temporary parameter settings Advantages Disadvantages True Cleans itself up. User can't customize the add-ins position. False User can customize add-in position. Removing the add-in does not remove the custom user interface.
In addition, setting the parameter to True forces you to recreate the command bar or menu every time, but helps prevent the possibility of duplicate menu items or menu items that hang around even if the add-in has been uninstalled. Setting the Temporary parameter is usually preferable because it keeps your toolbars clean. The main disadvantage of a temporary toolbar is that its position is not customizable by default, but you can write code to save position and visibility more easily than you can clean up a non-temporary toolbar.
- When looking for a CommandBar object, use the Id or Name parameter; do not hard code the index as it can change from one version of Office to another. The Id and Name will not change. For example:
Set cb = Application.CommandBars.FindControl(Id:=1) is okay. Set cb = Application.CommandBars("Standard") is okay. Set cb = Application.CommandBars(1) is unreliable.
- When setting properties on a built-in Office CommandBar object, be prepared for it to fail. If this occurs, check the CommandBar.Protection property to verify whether the CommandBar object is protected from certain changes. The Protection property gets or sets the way the specified command bar is protected from user customization. In addition, disabled and non-visible CommandBars objects have many property restrictions.
This section reviews tips for event handling.
- When using the .NET Framework, you need to keep a reference to any CommandBarButton, CommandBarComboBox, or CommandBarControl objects that have event handlers attached to them. Otherwise the item is removed by garbage collection and your event handler code does not run.
- Be sure to set the Tag property on your controls when adding event handlers or the event handlers do not work reliably as CommandBar sets are merged and copied. Office uses Tags to keep track of event handlers for a specific CommandBarControl. If the Tag property is left blank, the event handler does not copy over properly.
For the CopyFace and PasteFace methods, use Picture and Mask properties instead. To copy the image from a built-in Office CommandBarButton, use FaceId. The CopyFace and PasteFace methods modify the Microsoft Windows® clipboard which can be frustrating for users who don't understand why their clipboard data is corrupted or overwritten. Picture and Mask can also support gradients in Office 2003 running on Windows XP using themes.
Some of the common user interface elements of Windows have a new look in Windows XP which you can apply to your add-ins. For more information, see Microsoft Knowledge Base Article — 307855 HOW TO: Configure Desktop Themes in Windows XP and Microsoft Knowledge Base Article — 830033 HOW TO: Enable Office COM Add-ins to Opt-in to Windows XP Themes.
This article presents best practices that can assist you when developing command bars and command bar controls. Using one or more of these tips can make your code more efficient and easy to develop.