Working with the IDTExtensibility2 Event Procedures

Article
06/14/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

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.

The OnConnection Event

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 user starts the host application and the add-in's load behavior is specified to load when the application starts.
The user loads the add-in in the COM Add-ins dialog box.
The Connect property of the corresponding COMAddIn object is set to True. For more information about the COMAddIn object, search the Microsoft® Office Visual Basic Reference Help index for "COMAddIn object."

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	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_External	Does not apply to building COM add-ins for Microsoft® Office XP applications.
ext_cm_Startup	Add-in was loaded on startup.

If you are building a COM add-in that will run in more than one host application, you might find that you call the same code from each add-in designer's OnConnection event. For example, you might create a new command bar button in the OnConnection event procedure in the same way within each add-in designer. If so, it is 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. 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 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 the item does exist, the procedure returns a reference to the existing menu item rather than creating a new one. The OnConnection event procedure then assigns the reference returned by the CreateAddInCommandBarButton procedure to a variable (p_ctlBtnEvents) that has 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.

The OnDisconnection Event

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 user clears the check box next to the add-in in the COM Add-ins dialog box.
The host application closes. If the add-in is loaded when the application closes, it is unloaded. If the add-in's load behavior is set to Startup, it is reloaded when the application starts again.
The Connect property of the corresponding COMAddIn object is set to False.

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 that 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 is 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

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 that should not 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

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

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 both are loaded currently, and then add-in C is 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 XP applications.

Share via