Visual Basic Concepts

Connecting or Disconnecting Add-Ins

Once an add-in is registered in the system registry and referenced in the Vbaddin.ini file (or the registry), it can be connected to the IDE. The connection allows the add-in to respond to events and perform activities. You can connect or disconnect an add-in either manually or programmatically.

Handling the OnConnection and OnDisconnection Events

Whether you manually or programmatically connect an add-in, the add-ins IDTExtensibility_OnConnection event procedure is called. When you disconnect it, the IDTExtensibility_OnDisconnection event is called.

Private Sub IDTExtensibility_OnConnection(ByVal _
VBInst As Object, ByVal ConnectMode As _
VBIDE.vbext_ConnectMode, ByVal AddInInst As _
VBIDE.AddIn, custom() As Variant)
   MsgBox "Add-in is now connected"
End Sub

Private Sub IDTExtensibility_OnDisconnection(ByVal _
RemoveMode As VBIDE.vbext_RemoveMode, _
Custom () as Variant)
   MsgBox "Add-in is now disconnected"
End Sub

Private Sub IDTExtensibility_OnStartupComplete _
(custom() As Variant)
   ' Comment to prevent procedure from being
   ' deleted on compilation.
End Sub

Private Sub IDTExtensibility_OnAddInsUpdate _
(custom() As Variant)
   ' Comment to prevent procedure from being
   ' deleted on compilation.
End Sub

In this case, the only thing the program does is display a message box to notify you when the add-in was connected or disconnected. The last two event procedures are not used in this example, but must be present for the add-in to work correctly.

What Do the Parameters Mean?

The VBInst parameter in the OnConnection event procedure is an object reference to the current instance of Visual Basic. This object is the means through which you can access the Visual Basic extensibility object model.

The ConnectMode parameter notifies Visual Basic as to how the add-in was invoked. It has three possible settings:

Vbext_cm_AfterStartup	Add-in was connected after startup of development environment.
Vbext_cm_Startup	Add-in was connected on standard startup of development environment.
Vbext_cm_ExternalStartup	Add-in was connected by something other than the Visual Basic development environment.

The RemoveMode parameter in the OnDisconnection event procedure notifies Visual Basic as to how the add-in was disconnected.

Manually Connecting and Disconnecting Add-Ins

The primary (and simplest) way to connect an add-in to Visual Basic is to manually select it in the Add-In Manager and select a load behavior for it in the Visual Basic Add-Ins menu. The primary way of disconnecting an add-in is to select it and clear the Loaded/Unloaded check box.

Note that an add-in isn’t truly connected or disconnected until you click the Add-In Manager's OK button. When you select an add-in and a load behavior, then click OK, Visual Basic immediately attempts to create an instance of the add-in. If it can do so, the add-in becomes active. If for some reason Visual Basic cannot create an instance of the add-in, you’ll get an error message. (See “Add-In Troubleshooting” in this chapter for probable causes and solutions to this.) When you disconnect the add-in, the memory the add-in occupied is released.

This is important to remember. If you close only the visible portions of a an add-in — by double-clicking its system menu or by clicking its close button, for example — its forms disappear from the screen, but the add-in is still present in memory. While it is possible to write code in the form’s Unload event to release certain handles and pointers to free up some memory, the add-in object itself will always stay resident in memory until the add-in is disconnected through the Add-In Manager dialog box.

Programmatically Connecting and Disconnecting Add-Ins

Another way that you can connect a previously unconnected add-in — programmatically and behind the scenes — is to set the Connect property of the AddIns collection to True, then use the Update method on the Addins collection in the OnAddInsUpdate event procedure.

Changing the AddIns collection’s Connect property to True sets the add-in’s connection flag from 0 to 1 (meaning that it is connected at IDE startup). This change triggers the OnAddInsUpdate event, which occurs whenever changes are made to any add-in listed in the Add-In Manager (or Vbaddin.ini file entries). Using the Update method on the AddIns collection forces the Add-In Manager to re-read the list of add-in entries in the Vbaddin.ini file or in the Add-In designer. When this occurs, since the flag is now set to True, the add-in is connected.

In this following example, Visual Basic iterates through the Addins collection to check whether the given add-in’s programmatic ID matches a programmatic ID in the list of available add-ins. This is done only to certify that the index number of the add-in that will be passed to the Connect property actually exists. You cannot directly enter the add-in’s programmatic ID as a parameter for the AddIns collection’s Connect property. Once the programmatic ID is ascertained as valid, the add-in’s Connect property is set to 1 (connected).

Alternatively, you may elect to insert the number of the add-in, but this is not recommended because the add-in's number may change if it is stopped and re-started.

Note   This example assumes that you’ve already set up the requisite variables for a basic add-in, such as a variable for the Visual Basic instance (here called "vbi"). These requisites are covered later in this chapter. You must also replace “proj.class” with the programmatic ID of the add-in you wish to activate.

Sub ConnectAddIn()
   For Each x In vbi.AddIns
   ' Go through each add-in in the collection.
      If x.ProgId = "proj.class" Then x.Connect = True
      ' If any of the progIDs match that of the given
      ' add-in, set its Connect flag to True.
   Next x
   ' Continue iterating through the collection.
End Sub

If you then perform an Update method on the AddIns collection, the collection is updated. Visual Basic then notices that the add-in is marked for connection, and connects it. To perform this update, add the following line of code to the OnAddInsUpdate event procedure in the class module:

vbi.AddIns.Update
' Perform an Update on the AddIns collection.

This method forces Visual Basic to re-read the Vbaddin.ini file or the Add-In designer list. Since the flag on the add-in you want to start has been set to 1, or connect, the add-in is connected.

To programmatically disconnect an add-in, follow the same procedure, only set the Connect property of the AddIns****collection to False.