| Microsoft Office 2000/Visual Basic Programmer's Guide | |
The IDTExtensibility2 library provides five events that you can use to manipulate your add-in and the host application: OnConnection, OnDisconnection, OnAddInsUpdate, OnStartupComplete, and OnBeginShutdown. The following sections describe each of these event procedures.
Note If you don't have Visual Basic 6.0, you can try the sample add-in in Word, Excel, or PowerPoint, and then view the code in the add-in's modules by opening them in a text editor such as Notepad.
The OnConnection event occurs when the COM add-in is loaded (connected). An add-in can be loaded in one of the following ways:
The OnConnection event procedure takes four arguments, described in the following table.
| Argument | Type | Description |
| Application | Object | Provides a reference to the application in which the COM add-in is currently running. |
| ConnectMode | Custom Long | A constant that specifies how the add-in was loaded. |
| AddInInst | Object (COMAddIn) | A COMAddIn object that refers to the instance of the class module in which code is currently running. You can use this argument to return the programmatic identifier for the add-in. |
| Custom() | Variant | An array of Variant type values that provides additional data. The numeric value of the first element in this array indicates how the host application was started: from the user interface (1); by embedding a document created in the host application in another application (2); or through Automation (3). |
The constants for the ConnectMode argument are grouped in the ext_ConnectMode enumeration. These constants are described in the following table.
| Constant | Description |
| ext_cm_AfterStartup | Add-in was loaded after the application started, or by setting the Connect property of the corresponding COMAddIn object to True. |
| ext_cm_CommandLine | Does not apply to building COM add-ins for Office 2000 applications. |
| ext_cm_External | Does not apply to building COM add-ins for Office 2000 applications. |
| ext_cm_Startup | Add-in was loaded on startup. |
If you're building a COM add-in that will run in more than one host application, you may find that you call the same code from each add-in designer's OnConnection event. For example, you may create a new command bar button in the OnConnection event procedure in the same way within each add-in designer. If so, it's more efficient to create a public procedure in a standard module and call it from within the OnConnection event procedure for each add-in designer than to include the same code in each add-in designer.
The following example shows the OnConnection event procedure as it appears in the dsrImageWord add-in designer in the Image Gallery sample project, located in the ODETools\V9\Samples\OPG\Samples\CH11\ImageGallery subfolder on the Office 2000 Developer CD-ROM. The OnConnection event procedure calls the CreateAddInCommandBarButton procedure in the modSharedCode module. This procedure creates a new command bar button and returns a reference to it. The OnConnection event procedure then assigns this reference to a private event-ready variable of type CommandBarButton.
' Event-ready variable declared in add-in designer's module.
Private WithEvents p_ctlBtnEvents As Office.CommandBarButton
Private Sub IDTExtensibility2_OnConnection(ByVal Application As Object, _
ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _
ByVal AddInInst As Object, _
custom() As Variant)
' Call shared code to create new command bar button
' and return a reference to it. Assign reference to
' event-ready CommandBarButton object declared with
' WithEvents within this module.
Set p_ctlBtnEvents = CreateAddInCommandBarButton(Application, _
ConnectMode, AddInInst)
End Sub
' Public function in modSharedCode module.
Public Function CreateAddInCommandBarButton(ByVal Application As Object, _
ByVal ConnectMode As AddInDesignerObjects.ext_ConnectMode, _
ByVal AddInInst As Object) As Office.CommandBarButton
' This procedure assigns a reference to the Application
' object passed to the OnConnection event to a global
' object variable. It then creates a new command bar
' button and returns a reference to the button to the
' OnConnection event procedure. The advantage to putting
' this code in a public module is that if you have more
' than one add-in designer in the project, you can call
' this procedure from each of them rather than duplicating
' the code.
Dim cbrMenu As Office.CommandBar
Dim ctlBtnAddIn As Office.CommandBarButton
On Error GoTo CreateAddInCommandBarButton_Err
' Return reference to Application object and store it
' in public variable so that other procedures in add-in
' can use it.
Set gobjAppInstance = Application
' Return reference to command bar.
Set cbrMenu = gobjAppInstance.CommandBars(CBR_NAME)
' Add button to call add-in from command bar, if it doesn't
' already exist.
' Constants are declared at module level.
' Look for button on command bar.
Set ctlBtnAddIn = cbrMenu.FindControl(Tag:=CTL_KEY)
If ctlBtnAddIn Is Nothing Then
' Add new button.
Set ctlBtnAddIn = cbrMenu.Controls.Add(Type:=msoControlButton, _
Parameter:=CTL_KEY)
' Set button's Caption, Tag, Style, and OnAction properties.
With ctlBtnAddIn
.Caption = CTL_CAPTION
.Tag = CTL_KEY
.Style = msoButtonCaption
' Use AddInInst argument to return reference
' to this add-in.
.OnAction = PROG_ID_START & AddInInst.ProgId _
& PROG_ID_END
End With
End If
' Return reference to new commandbar button.
Set CreateAddInCommandBarButton = ctlBtnAddIn
CreateAddInCommandBarButton_End:
Exit Function
CreateAddInCommandBarButton_Err:
' Call generic error handler for add-in.
AddInErr Err
Resume CreateAddInCommandBarButton_End
End Function
The CreateAddInCommandBarButton procedure first performs a critical step: it assigns the object passed to the procedure in the Application argument to a public module-level object variable. This object variable persists as long as the COM add-in is loaded, so that any other procedures in the module can determine in what application the add-in is currently running.
A public module-level variable declared in a standard module in a COM add-in remains in existence from the time the add-in is loaded to the time it is unloaded.
This procedure also contains code that creates a new menu item on the Tools menu of the host application the first time the add-in is loaded. Before creating the new menu item, the procedure checks to see whether the item already exists; if it does, the procedure returns a reference to the existing menu item rather than creating a new one. The OnConnection event procedures then assigns the reference returned by the CreateAddInCommandBarButton procedure to a variable (p_ctlBtnEvents) that's been declared by using the WithEvents keyword, so that the menu item's Click event procedure will be triggered when the user clicks the new menu item. For more information about creating a menu item for a COM add-in, see "Hooking a COM Add-in Up to a Command Bar Control" later in this chapter. For more information about using the WithEvents keyword to sink command bar events, see Chapter 6, "Working with Shared Office Components," and Chapter 9, "Custom Classes and Objects."
The OnDisconnection event occurs when the COM add-in is unloaded. You can use the OnDisconnection event procedure to run code that restores any changes made to the application by the add-in and to perform general clean-up operations.
An add-in can be unloaded in one of the following ways:
The OnDisconnection event procedure takes two arguments, described in the following table.
| Argument | Type | Description |
| RemoveMode | Custom Long | A constant that specifies how the add-in was unloaded. |
| custom() | Variant | An array of Variant type values that provides additional data. The numeric value of the first element in this array indicates how the host application was started: from the user interface (1); by embedding a document created in the host application in another application (2); or through Automation (3). |
The following table lists the available constants for the RemoveMode method, which are grouped in the ext_DisconnectionMode enumeration.
| Constant | Description |
| ext_dm_HostShutdown | Add-in was unloaded when the application was closed. |
| ext_dm_UserClosed | Add-in was unloaded when the user cleared the corresponding check box in the COM Add-ins dialog box, or when the Connect property of the corresponding COMAddIn object was set to False. |
The following code shows the OnDisconnection event procedure as it appears in the dsrImageWord designer in the Image Gallery project, located in the ODETools\V9\Samples\OPG\Samples\CH11\ImageGallery subfolder on the Office 2000 Developer CD-ROM. The OnDisconnection event procedure calls the RemoveAddInCommandBarButton procedure located in the modSharedCode module. If the user unloads the add-in, the add-in's menu command is deleted; otherwise it's maintained for the next time the user starts the application:
Private Sub IDTExtensibility2_OnDisconnection(ByVal _
RemoveMode As AddInDesignerObjects.ext_DisconnectMode, _
custom() As Variant)
' Call common procedure to disconnect add-in.
RemoveAddInCommandBarButton RemoveMode
End Sub
Function RemoveAddInCommandBarButton(ByVal _
RemoveMode As AddInDesignerObjects.ext_DisconnectMode)
' This procedure removes the command bar button for
' the add-in if the user disconnected it.
On Error GoTo RemoveAddInCommandBarButton_Err
' If user unloaded add-in, remove button. Otherwise,
' add-in is being unloaded because application is
' closing; in that case, leave button as is.
If RemoveMode = ext_dm_UserClosed Then
On Error Resume Next
' Delete custom command bar button.
gobjAppInstance.CommandBars(CBR_NAME).Controls(CTL_NAME).Delete
On Error GoTo RemoveAddInCommandBarButton_Err
End If
RemoveAddInCommandBarButton_End:
Exit Function
RemoveAddInCommandBarButton_Err:
AddInErr Err
Resume RemoveAddInCommandBarButton_End
End Function
The OnStartupComplete event occurs when the host application completes its startup routines, in the case where the COM add-in loads at startup. If the add-in is not loaded when the application loads, the OnStartupComplete event does not occur, even when the user loads the add-in in the COM Add-ins dialog box. When this event does occur, it occurs after the OnConnection event.
You can use the OnStartupComplete event procedure to run code that interacts with the application and shouldn't be run until the application has finished loading. For example, if you want to display a form that gives users a choice of documents to create when they start the application, you can put that code in the OnStartupComplete event procedure.
The OnBeginShutdown event occurs when the host application begins its shutdown routines, in the case where the application closes while the COM add-in is still loaded. If the add-in is not currently loaded when the application closes, the OnBeginShutdown event does not occur. When this event does occur, it occurs before the OnDisconnection event.
You can use the OnBeginShutdown event procedure to run code when the user closes the application. For example, you can run code that saves form data to a file.
The OnAddInsUpdate event occurs when the set of loaded COM add-ins changes. When an add-in is loaded or unloaded, the OnAddInsUpdate event occurs in any other loaded add-ins. For example, if add-ins A and B are both currently loaded, and add-in C is then loaded, the OnAddInsUpdate event occurs in add-ins A and B. If C is unloaded, the OnAddInsUpdate event occurs again in add-ins A and B.
If you have an add-in that depends on another add-in, you can use the OnAddInsUpdate event procedure in the dependent add-in to determine whether the other add-in has been loaded or unloaded.
Note The OnStartupComplete, OnBeginShutdown, and OnAddInsUpdate event procedures each provide only a single argument, the Custom() argument, which is an empty array of Variant type values. This argument is ignored in COM add-ins for Office 2000 applications.