Best Practices When Developing Command Bars for the Microsoft Office System

 

Andy Chang
Frank C. Rice
Microsoft Corporation

December 2003

Applies to:
    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)

Contents

Introduction
Adding Controls to Command Bars
General Tips
Using the Visual Studio .NET Shared Add-in Wizard
Adding Command Bars and Menu Items
Event Handlers
Deprecated Application Programming Interfaces
Using Themes with Your Add-in
Conclusion

Introduction

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.

Adding Controls to 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

General Tips

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:

    "$HOMEDRIVE:\$HOMEPATH\Application Data\Microsoft\Office"
    

    -OR-

    "$APPDATA\Microsoft\Office", if APPDATA is available
    

    -OR-

    "$APPDATA\Company_name\Add-in_Name\" 
    

    where:

    • 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.

Using the Visual Studio .NET Shared Add-in Wizard

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.

Adding Command Bars and Menu Items

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.

Event Handlers

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.

Deprecated Application Programming Interfaces

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.

Using Themes with Your Add-in

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.

Conclusion

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.

© Microsoft Corporation. All rights reserved.