The basic elements of a COM add-in consist of connecting and disconnecting the add-in, exposing the add-in to Office through registration in the Windows Registry, and accessing the methods and properties in an Office application. Two main parts of the COM add-in model address the basic elements. The first is the IDTExtensibility2 interface. The second is how and where a COM add-in is registered in the Windows Registry. This section explains both the IDTExtensibility2 interface and the registration of COM add-ins.
From a technical perspective, when Office loads a COM add-in into an application, it determines if the interface IDTExtensibility2 exists in the COM add-in. Because using the Add-in Designer will keep you from understanding what it means to implement an interface, it won't be discussed here. Instead, this section discusses the five IDTExtensibility2 methods OnConnection, OnAddInsUpdate, OnStartupComplete, OnBeginShutdown, and OnDisconnection because Office calls them when a COM add-in is loaded or unloaded.
The description of each method tells you when it is called by Office and lists the information you can retrieve from the method. To a Visual Basic programmer, the methods of the IDTExtensibility2 interface act and behave like events. When you connect an add-in to Office, the OnConnection method is called automatically in an action that's similar to the execution of an event procedure. When you disconnect a COM add-in, the OnDisconnection method is called automatically. The methods of the IDTExtensibility2 interface are executed in the following sequence:
| Execution order and Method | Description of when the procedure is called |
|---|---|
| 1. OnConnection | Called when the add-in is loaded into the Office application. |
| 2. OnAddInsUpdate | Called when the add-in is loaded into the Office application and after the OnConnection procedure is called. If other COM add-ins are also loaded, the OnAddInsUpdate procedure is called in the other COM add-ins sequentially. |
| 3. OnStartupComplete | Called if the add-in is loaded when the application is started. This procedure is called after the OnConnection and OnAddInsUpdate procedures, when the application that loads the add-in is started. |
| 4. OnBeginShutdown | Called when the application is exiting. |
| 5. OnDisconnection | Called when the add-in is being unloaded by the application, either when the application is exiting or when the user clears the COM add-in item in the COM Add-Ins dialog box. |
No matter how or when you load the add-in, the OnConnection procedure is always called. Use the OnConnection procedure to set a public variable representing the Application object of the application loading the add-in so that other procedures in your add-in can use this Application object.
Syntax
Private Sub IDTExtensibility2_OnConnection( _
ByVal Application As Object, _
ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _
ByVal AddInInst As Object, custom() As Variant)
|
| Argument | Description |
|---|---|
| Application | An object representing the Application object of the Office application that's loading the COM add-in. |
| ConnectMode | Can be one of the ext_ConnectMode constant values specified in the table below. |
| AddInInst | Represents the COMAddIn object defined in the Microsoft Office 9.0 Object Library. Specifically, the AddInInst object variable represents the COM add-in itself. |
| custom() | An array of variant expressions to hold user-defined data. Office sets the first element of the custom() array to a value that represents how the Office application is started. |
The following table represents the ext_ConnectMode constant that Office will set the ConnectMode argument to in the OnConnection procedure. There are two other ext_ConnectMode constants, ext_cm_External and ext_cm_CommandLine, that Office never sets.
| Constant | Value | Description |
|---|---|---|
| ext_cm_AfterStartup | 0 | Value returned if the add-in is loaded after the Office application starts. If an add-in is demand-loaded or if your add-in is loaded through the COM Add-Ins dialog box, this value will be set to the ConnectMode argument. |
| ext_cm_Startup | 1 | Value returned if the add-in is loaded when the Office application starts. |
The OnAddInsUpdate procedure is called when the load state of an add-in is changed. For example, when an add-in is loaded or unloaded, the OnAddInsUpdate procedure is called within the add-in that is being loaded or unloaded—and called in any other COM add-in that is currently loaded.
Syntax
Private Sub IDTExtensibility2_OnAddInsUpdate( _
custom() As Variant)
|
The OnStartupComplete procedure is called when the startup sequence of an Office application is complete. This procedure is called only in a boot-loaded add-in.
Syntax
Private Sub IDTExtensibility2_OnStartupComplete( _
custom() As Variant)
|
So what's the difference between the OnConnection procedure and the OnStartupComplete procedure? The OnConnection procedure is the first procedure called when the Office application loads the COM add-in. The instance of the Application object of the Office application loading the COM add-in is passed to the OnConnection procedure.
You can store the instance of the Application object globally so you can use it throughout your COM add-in.
The OnStartupComplete procedure is called after the OnConnection procedure—but only when all COM add-ins loaded at startup are in memory. That is, first the OnConnection procedure is called for every COM add-in that is to be loaded. Once every add-in is loaded, the OnStartupComplete procedure is called for every COM add-in that's in memory.
The OnBeginShutdown procedure is called when the shut-down sequence of an Office application begins. This procedure is called only in add-ins that are loaded in memory when the application shuts down.
Syntax
Private Sub IDTExtensibility2_OnBeginShutdown( _
custom() As Variant)
|
The OnDisconnection procedure is always called, no matter how or when you unload the add-in. You should use the RemoveMode argument in the OnDisconnection procedure in scenarios where the add-in needs to determine whether it should remove any command bar customizations that it made when it loaded. If the user disconnects an add-in through the COM Add-Ins dialog box, the add-in should remove any menu and toolbar customizations it added to the Office application.
Syntax
Private Sub IDTExtensibility2_OnDisconnection( _ ByVal RemoveMode As AddInDesignerObjects.ext_DisconnectMode, _ custom() As Variant) |
The following table represents the ext_ DisconnectMode constant that Office will set the RemoveMode argument to in the OnDisconnection procedure.
| Constant | Value | Description |
|---|---|---|
| ext_dm_HostShutdown | 0 | Value returned when the add-in is disconnected by the application during its shut-down sequence. |
| ext_dm_UserClosed | 1 | Value returned after the user clears the add-in item listed in the Available Add-ins list box in the COM Add-Ins dialog box. |
Once you've written code in any of the IDTExtensibility2 method procedures and throughout your COM add-in, two things need to happen so the COM add-in is recognized by an Office application as an available add-in. Both involve the Windows Registry. The first is to register the add-in on the end user's machine so that the system knows where it's located on the machine. The second is to register the add-in under an Office application key so that Office knows what add-ins are available and when it should be loaded.
In Visual Basic 6.0, when you click Make ProjectName.dll on the File menu and then click OK in the Make Project dialog box, Visual Basic automatically registers the COM add-in in the Windows system registry. The act of compiling the .dll registers it in the Windows system registry, and the system now knows where to locate the add-in. The Package and Deployment Wizard will also register a COM add-in so that the system on your end user's machine will know where to locate the add-in. Even though the add-in is registered on the machine, it still has to be registered where an Office 2000 application will know to load it.
You have two ways to register a COM add-in for use in an Office 2000 application: with a REG file or with the Microsoft Add-in Designer. If you use the Add-in Designer, you don't need a REG file. A REG file allows an add-in to be quickly registered for any Office 2000 application without adding the Addin Class to your COM add-in project in Visual Basic 6.0. A REG file's contents indicate where a COM add-in is registered for an Office 2000 application in the Windows Registry. In the section "How Do I…" later in this chapter, the example under the heading "…Create a COM Add-In Without Using the Add-In Designer" describes how to use a REG file for registering a COM add-in.
COM add-ins are registered under the following key in the Windows Registry:
[HKCU\Software\Microsoft\Office\<app>\AddIns\Prog.ID] |
HKCU is the short form for the HKEY_CURRENT_USER key. The text <app> represents the name of any Office application. For example, Word, Excel, PowerPoint, Access, or Outlook, would replace <app>. The programmatic identifier, or ProgID, would replace the text "Prog.ID" for your COM add-in. The section "How Do I…?" later in this chapter describes how to determine and set the programmatic identifier of a COM add-in in Visual Basic 6.0. The following graphic shows how a COM add-in for Word would appear in the Windows registry.
You can also register a COM add-in under the HKEY_LOCAL_MACHINE key. The structure of the key under the HKEY_CURRENT_USER key is exactly the same under the HKEY_LOCAL_MACHINE key. The Add-in Designer used in Visual Basic registers a COM add-in under the HKEY_CURRENT_USER key by default.
Under each COM add-in key, you need to add and set a LoadBehavior value. The LoadBehavior value determines how your add-in will be loaded. Generally, you'll set the load behavior to one of the values listed in the following table, which also gives examples of when you would use a specific value:
| Load behavior | Registry value | Example |
|---|---|---|
| None | 0 | Helper add-in or library of functions needed by other add-ins only at certain times. You don't have to register the helper add-in because you can always call it in Visual Basic code using CreateObject. However, if the helper add-in also has some user interface and custom commands that are shown only when the helper add-in is needed, you should register the add-in for Office. |
| Startup | 3 | Always load the add-in. See the following section, "Boot-Load versus Demand-Load COM Add-Ins." |
| Load on demand | 9 | Loaded when needed. See the following section, "Boot-Load versus Demand-Load COM Add-Ins." |
| Load at next startup only | 10 (hex) or 16 (decimal) |
Use this value so that your add-in has the opportunity to add custom commands at the application's next startup. Office sets this value back to 9 to be demand-loaded later by the custom command. |
The load behavior values listed in the table also appear in the Initial Load Behavior drop-down list in the Add-in Designer in Visual Basic, as shown in the following illustration.
Boot-Load versus Demand-Load COM Add-Ins
Based on the functionality they provide, most add-ins can be categorized as one of either two types (or a combination of both). The first type provides functionality when the user clicks a menu item, a toolbar button, or some other command bar customization. An add-in that needs to be loaded only when a menu item or toolbar button is clicked is called a demand-loaded add-in.
The second type is loaded all of the time and just handles document events such as opening, closing, or saving. This kind of add-in can also handle events like selection change or double-clicking in a Word, Excel, or PowerPoint document. An add-in that needs to be loaded all of the time to respond to application events is called a boot-loaded add-in. This add-in loads when the Office application starts, or boots, and so once your users are ready to use the application, your add-in will be available.
When your add-in monitors events such as saving a document, your add-in may want to determine the file location where the document will be saved. If the document is to be saved to a specific folder, your COM add-in may then determine if specific document properties, such as Title or Comments, are set. Chapter 5, "Managing Documents with Events," describes how to handle the document Save event and determine where the user wants to save a document.
If your add-in monitors the Selection Change event for the active window in Word, Excel, or PowerPoint, see Chapter 10, "Handling Window and Content Interaction Events," for information on how to update a command bar customization based on the selection.
You can also write add-ins that both monitor application events and respond when the user clicks a command bar customization.
At startup of an Office application, Office reads the \Software\Microsoft\Office\<app>\AddIns key for the application (<app> represents the name of the application being started). Office builds the list of available COM add-ins first from the key HKEY_LOCAL_MACHINE (HKLM) and then from the key HKEY_ CURRENT_USER (HKCU). Office first reads from HKLM because if a duplicate COM add-in entry exists under both keys of the registry, the add-in registered under HKLM takes precedence and the HKCU key is ignored. This feature ensures that if an administrator registers an add-in under HKLM, it's always guaranteed to load for all of the machine's users.
Once the list of add-ins is built during the initialization sequence of the Office application, Office starts loading each add-in (at the end of the initialization sequence) whose load behavior is set in the registry to be loaded at startup. In the Windows Registry, the LoadBehavior value would be set to 3.