Microsoft Office 2000/Visual Basic Programmer's Guide

Hooking a COM Add-in Up to a Command Bar Control

If your COM add-in has a user interface, it needs to be integrated with the host application in some way so that the user can interact with it. For example, the user interface for your COM add-in most likely includes a form. At some point, code in the add-in needs to be run in order to display the form.

One way to integrate your add-in with an application's user interface is to include code in the OnConnection event procedure that creates a new command bar control (toolbar button or menu item) in the host application. When your add-in is loaded, the user can click the button or menu item to work with the add-in.

The critical aspect of integrating an add-in through a command bar control is the process of setting up the event sink. You must create a command bar control that is event-ready so that its Click event is triggered when the user clicks the control. You can use the WithEvents keyword to create an event-ready command bar control.

If you set the load behavior for your add-in to Load at Next Startup Only, you also need to set the OnAction property for the command bar control. If you don't set the OnAction property, the add-in will load the first time the application starts. The next time you start the application, however, the load behavior for the add-in will be set to Load on Demand, and the command bar control that you've created for the add-in won't load the add-in unless the OnAction property has been set.

Even if your add-in is not demand-loaded, it's a good idea to set this property in your code in case you later change the load behavior for the add-in. The syntax for setting the OnAction property for a COM add-in is

ctlButton.OnAction = "!<ProgID>"

where ctlButton is the CommandBarButton object and ProgID is the programmatic identifier for the add-in. The programmatic identifier is the subkey that's created for the add-in in the Windows registry. Each add-in designer or class module that implements the IDTExtensibility2 library in the COM add-in project adds its own programmatic identifier to the registry, beneath the AddIns subkey for the host application in which it will run. The programmatic identifier for a COM add-in consists of the name of the project followed by the name of the add-in designer or class module. For example, the programmatic identifier for the ImageGallery add-in for Word is ImageGallery.dsrImageWord.

To return the programmatic identifier for an add-in, you can use the AddInInst argument that's passed to the OnConnection event procedure. This argument provides a reference to the add-in designer or class module in which code is currently running. The AddInInst argument is an object of type COMAddIn, which has a ProgId property that returns the programmatic identifier. Note that you need to concatenate the !< and > delimiters before and after the programmatic identifier string to properly set the OnAction property.

Important   If your add-in will run in Word, you also need to set the Tag property for the CommandBarButton object to a unique String value. This ensures that the command bar button will respond to the Click event and load the add-in for each new document window that the user opens. Because the Tag property provides you with additional information about the control, it's a good idea to set the Tag property for a command bar button that loads a COM add-in in any host application.

To create a command bar control that displays the add-in's form

1. In the add-in designer's module, use the WithEvents keyword to declare a module-level variable of type CommandBarButton. This creates an event-ready CommandBarButton object.
   
   
2. In the same module, create the Click event procedure stub for the CommandBarButton object by clicking the name of the object variable in the Object box and then clicking Click in the Procedure box.
   
   
3. Write code within the event procedure stub to open the form when the Click event occurs.
   
   
4. In the OnConnection event procedure, check to see whether the command bar control already exists, and return a reference to it if it does. If it doesn't exist, create the new command bar control and return a reference to it. You need to check whether the command bar control exists so that you don't create a new control each time your code runs.
   
   
5. When you create the new command bar control, set the Tag property for the CommandBarButton object to a unique string. This is necessary only for COM add-ins running in Word, but it's recommended for COM add-ins running in any host application.
   
   
6. When you create the new command bar control, set the OnAction property for the command bar control if the COM add-in is to be demand-loaded. If you fail to set the OnAction property, the command bar button will load the add-in the first time the application starts, but will not load the add-in when the application is closed and reopened.
   
   
7. Within the OnConnection event procedure, assign the reference to the command bar control to the event-ready CommandBarButton object variable.
   
   
8. Add code to the OnDisconnection event to remove the command bar control when the add-in is unloaded.

The add-in designer in the COM add-in template project includes code that performs all these steps to create a menu item on the Tools menu. By default, the template project has a reference set to the Microsoft Office 9.0 object library so that you can work with Office command bars.

For more information about using the WithEvents keyword and sinking events, see Chapter 9, "Custom Classes and Objects." For more information about working with command bars and their events, see Chapter 6, "Working with Shared Office Components."