Creating the Add-In Class
If a class is to be used as an add-in, it must have certain standard property values, and it must provide certain standard subroutines. Some of these are slightly different in Visual Basic 4 and Visual Basic 5. The following two sections, Class Properties in Visual Basic 4 and Class Properties in Visual Basic 5, describe the properties that should be set for an add-in. The next three sections describe the standard ConnectAddIn, DisconnectAddIn, and AfterClick subroutines that should be provided by the add-in class.
Class Properties in Visual Basic 4
In Visual Basic 4, the Public property of the add-in class should be set to true. This can be done using the class module's Properties window. Setting Public to true allows client applications to create instances of the class. Since the Visual Basic development environment is not part of the application, it needs permission to create objects of this class.
The class module's Instancing variable should be set to Creatable SingleUse (1) or Creatable MultiUse (2). This indicates how the server should provide objects from the class. If Instancing is set to Creatable SingleUse, the system will create a separate server for each client requesting an instance of the class.
If Instancing is set to Creatable MultiUse, the system will allow one server to serve more than one client at a time. The clients will be assigned different class objects, but they will run in the same execution space. If the server application uses global variables, all of the clients will have access to the same global variables through their server objects. Since the system will not need to start several servers to satisfy multiple client requests, satisfying client's may be faster if Instancing is Creatable MultiUse. On the other hand, the server must be careful that multiple clients do not interfere with each other while accessing global variables.
Class Properties in Visual Basic 5
In Visual Basic 5, add-ins do not have a Public property. The Instancing variable determines both how the server provides objects and whether the objects can be created by external applications. For an add-in, the Instancing property should be set to MultiUse (5). This indicates both that external applications can create instances of the object and that a single server will provide multiple server objects. As is the case in Visual Basic 4, the server must ensure that multiple clients do not interfere with each other while accessing global variables.
ConnectAddIn
Visual Basic expects add-ins to implement two standard subroutines: ConnectAddIn and DisconnectAddIn. The Add-In Manager uses these routines to connect and disconnect the add-in server from the Add-Ins menu. When the Add-In Manager installs an add-in in the Visual Basic development environment, it invokes the add-in's ConnectAddIn subroutine. This routine should take whatever action is necessary to incorporate the server into the Visual Basic environment. Generally, this means placing new submenus and menu items in the Add-Ins menu.
Figure 4.5 shows the Visual Basic 4 Add-Ins menu after the PropertySetter server has installed itself. PropertySetter adds a single menu command, Set Properties, to the Add-In menu.
Figure 4.5: The Add-Ins menu with PropertySetter installed.
Visual Basic provides a number of objects that the add-in can use to manipulate the programming environment. These objects are defined in a development environment module that the add-in project must reference. In Visual Basic 4, this is done using the References... command in the Tools menu. In the References dialog, the Microsoft Visual Basic 4.0 Development Environment entry should be selected. In Visual Basic 5, the corresponding dialog is presented by the References... command in the Project menu. In this dialog, the Microsoft Visual Basic 5.0 Extensibility reference should be selected.
The ConnectAddIn subroutine is passed a single parameter of type VBIDE.Application. This object is a reference to the running Visual Basic development environment. The ConnectAddIn subroutine can access other objects such as the menus, forms, and controls in the current environment using this object. PropertySetter's ConnectAddIn subroutine begins by saving a reference to the VBIDE.Application object for later use. Next the subroutine creates a new menu item in the Add-Ins menu. The VBIDE.Applicationí's AddInMenu property is a reference to the Add-Ins menu object. That object's MenuItems property is a collection containing objects that describe the items in the menu. ConnectAddIn uses this collection's Add function to create the new menu command.
The Add function returns an object of type VBIDE.MenuLine. This object represents the new command line in the menu. VBIDE.MenuLine objects provide a function ConnectEvents that associates the menu item with an event handler object that should be activated when the item is selected. When the developer selects the item from the Add-Ins menu, Visual Basic invokes the event handler object's AfterClick subroutine.
To respond to the menu item, the add-in should contain an event handler class that has an AfterClick subroutine. The ConnectAddIn subroutine should create an instance of this class and pass it to the menu item's ConnectEvents function. Since the add-in server creates this object, not the client, the event handler class does not need to have its Instancing property set to allow outside applications to create event handler objects directly.
In the PropertySetter application, the PropSet class provides the AfterClick event handler routine as well as the ConnectAddIn and DisconnectAddIn subroutines. Because Since PropertySetter provides only a single menu item, these three subroutines can all be contained by one class without causing confusion. However, a program could implement an add-in that provided more than one command in the Add-Ins menu. In that case, it could create a different event handler class for each of the menu commands. The Scroller add-in described in Chapter 7 demonstrates how to build an add-in that provides more than one Add-Ins menu item.
After the ConnectEvents function attaches the event handler object to the menu item, it returns a connection ID. The program should save this ID for later use. Subroutine DisconnectAddIn needs this ID to properly remove the add-in from the Add-Ins menu. The following code shows the ConnectAddIn subroutine used by the PropertySetter add-in. The global variables VBInstance, SetPropLine, and SetPropID are set by ConnectAddIn and are used later by DisconnectAddIn.
' The environment instance.
Dim VBInstance As VBIDE.Application
' The menu command line.
Dim SetPropLine As VBIDE.MenuLine
' The event connection ID. This represents the
' event handler to menu line connection.
Dim SetPropID As Long
Sub ConnectAddIn(vb_instance As VBIDE.Application)
' Save the Visual Basic instance for later.
Set VBInstance = vb_instance
' Add the command.
Set SetPropLine = _
VBInstance.AddInMenu.MenuItems.Add("&Set Properties...")
' Connect the event handler object to the menu line.
SetPropID = SetPropLine.ConnectEvents(Me)
End Sub
[Home Page] [Tutorial Page] [Main Add-In Page] [Next Lesson] [Prev Lesson]