DOCUMENT:Q141932 11-JAN-2001 [vbwin] TITLE :HOWTO: Create a Basic Add-In Using Visual Basic 4.0 PRODUCT :Microsoft Visual Basic for Windows PROD/VER:WINDOWS:4.0 OPER/SYS: KEYWORDS:kbAddIn kbVBp400 kbGrpDSVB kbDSupport ====================================================================== ------------------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual Basic Standard Edition, 32-bit, for Windows, version 4.0 - Microsoft Visual Basic Professional Edition, 16-bit, for Windows, version 4.0 - Microsoft Visual Basic Professional Edition, 32-bit, for Windows, version 4.0 - Microsoft Visual Basic Enterprise Edition, 16-bit, for Windows, version 4.0 - Microsoft Visual Basic Enterprise Edition, 32-bit, for Windows, version 4.0 ------------------------------------------------------------------------------- SUMMARY ======= This article describes how to create the basic framework of a working Visual Basic 4.0 add-in. MORE INFORMATION ================ Creating a Minimal Add-in ------------------------- At its minimum, a Visual Basic add-in is an OLE automation server that provides an object with both ConnectAddin and DisconnectAddin methods. The server can be written in any language that can create OLE automation servers. The steps to create the minimal add-in using Visual Basic 4.0 are documented in this article. Then, this article shows you how to make some basic enhancements that the majority of add-ins will need. 1. Start Project: The first step in creating the minimal add-in is to start a new project. The minimal add-in does not need the default form; so, remove the form from the project. 2. Create Sub Main: The minimal add-in needs a starting point. So, add a new standard (.BAS) module to the project. Then, add an empty Sub Main procedure to the module: Sub Main() End Sub 3. Create a Class: The heart of the add-in is the public-creatable OLE automation object. The following are the steps for creating this object: a. Add a new Class (.cls) module to the project. b. Set the following properties on the new class: Property Value -------------------------------------------------------------- Instancing 2 - Creatable MultiUse Name MinimalAddIn Public True 4. Expose ConnectAddIn and DisconnectAddIn Methods: When the automation manager loads an add-in, it looks for and calls the ConnectAddin method. The add-in manager passes an instance of the Application object to the ConnectAddin method. The add-in can then use this object for automating the Visual Basic design environment. In the minimal add-in, show a message in this method of the class with the following code: Public Sub ConnectAddIn(VBInstance As Object) MsgBox "ConnectAddIn" End Sub Similarly, the add-in manager looks for and calls the DisconnectAddIn method when unloading an add-in. In the minimal add-in, show a message in this method of the class with the following code: Public Sub DisconnectAddIn() MsgBox "DisconnectAddIn" End Sub 5. Set the Project Options: At this point you have added all the code necessary for the minimal add-in. However, you need to set the project options to expose this project as an OLE automation server. Set the following in the Tools/Options dialog box: Option Value ----------------------------------------------------------- Start up Form Sub Main Project Name Example Start Mode OLE Server Error Trapping Break in Class Module 6. Make Add-In available to Add-In Manager: Now you need to make the minimal add-in available to the Add-In manager. The add-in looks in Vb.ini under either the Add-Ins16 or Add-Ins32 section depending on whether you are running the 16-bit or 32-bit versions of Visual Basic. The add-in manager looks for available add-ins in the form of ProgID=n, where ProgID is the OLE Automation ProgID for your class and n is 0 or 1. 0 means the add-in is available but Visual Basic doesn't have it loaded. 1 means that the add-in is or should be loaded. For the minimal add- in in 32-bit Visual Basic, you need to add the following to the Vb.ini: [Add-Ins32] Example.MinimalAddIn=0 7. Testing the Add-In: That is it for the minimal add-in. Now you can test it. Go ahead and start up the add-in by running the project. To test it you must start up a second instance of Visual Basic. In the second instance, bring up the Add-In Manager dialog box. There should be a check box with ProgID Example.MinimalAddin next to it. Check the box and click OK. The Add-In Manager will call the ConnectAddin method of the minimal add-in and the add- in will display the message box "ConnectAddIn." Now go back to the Add-In Manager in the second instance of Visual Basic. Clear Example.MinimalAddin and click OK. The Add-In Manager will call the DisconnectAddIn method and the add-in will display the message box "DisconnectAddIn." Expanding the Minimal Add-in ---------------------------- The minimal add-in demonstrated the absolute minimum requirements for creating an add-in. However, there are some basic things that most add-ins need to do. In this section you will expand upon the minimal add-in to create a basic add-in that automatically adds itself to Vb.ini and adds a menu to the Visual Basic Add-In menu. 1. Reference VBIDE: In the minimal add-in you did not use the Visual Basic IDE add-in object model. Any add-in that needs to program the IDE must add a reference to the "Microsoft Visual Basic 4.0 Development Environment" object library. Almost all add-ins need to add a reference to this library. For the basic add-in, we need to use the library to declare variables and to add a menu. So, add a reference to this library in the Tools/References dialog box. 2. Change the Class Name: To help distinguish the basic add-in from the minimal add-in, change the Name property of the class module to BasicAddIn. 3. Store the Instance of the Application Object: Most add-ins need to store the instance of the Application object that is passed in through the ConnectAddIn method so that it can be used later to automate the IDE. For the basic add-in, this means that you need to declare an object in the class to store the instance. To do this you need to add the following to the general declarations section of the class: Private ThisInstance As VBIDE.Application When the ConnectAddIn method is called, the ThisInstance variable needs to be set to the instance passed in. To do this, change the ConnectAddIn method to the following: Public Sub ConnectAddIn(VBInstance As Object) Set ThisInstance = VBInstance End Sub 4. Adding and Removing a MenuLine: The majority of add-ins also need to add a menu item to the Add-In menu so that users can trigger some functionality in their add-in. In the basic add- in, you simply show a message if the user clicks the menu item. Before adding the code to create the menu, you need to add two variables to the general declarations section of the class: Private AddInMenuLine As VBIDE.MenuLine Private hMenuLine As Long The AddInMenuLine object is used to store a reference to the newly created menu and the hMenuLine is used to store a handle that will be discussed shortly. Now you can add the code necessary for adding the MenuLine to the ConnectAddIn method: Set AddInMenuLine = ThisInstance.AddInMenu.MenuItems.Add("Basic Add-In") This adds a MenuLine to the Add-In menu with the caption "Basic Add-In" and sets a reference to the object. After adding the MenuLine you need to connect the MenuLine to an event handler. In this case the AfterClick event of the MenuLine object is what you want to handle. First you need to create an event handler for the AfterClick in the class. The AfterClick event handler should look like the following: Public Sub AfterClick() MsgBox "Basic Add-In Example" End Sub Now that you have an event handler you need to add code to the ConnectAddIn method that connects the MenuLine to the class. To do this you need to call the ConnectEvents method of the MenuLine object. This method returns a handle that we will use later to disconnect the event handler. Here is the code for connecting the events to the class: hMenuLine = AddInMenuLine.ConnectEvents(Me) You also need to add code to the DisconnectAddIn method that disconnects the event handler and removes the MenuLine. The events are disconnected by calling the DisconnectEvents method of the MenuLine object and the MenuLine is removed by calling the Remove method of the MenuItems collection: AddInMenuLine.DisconnectEvents hMenuLine ThisInstance.AddInMenu.MenuItems.Remove AddInMenuLine At this point, the entire class module should look something like the following: Option Explicit Private ThisInstance As VBIDE.Application Private AddInMenuLine As VBIDE.MenuLine Private hMenuLine As Long Public Sub ConnectAddIn(VBInstance As Object) Set ThisInstance = VBInstance Set AddInMenuLine = ThisInstance.AddInMenu.MenuItems.Add("Basic Add-_ In") hMenuLine = AddInMenuLine.ConnectEvents(Me) End Sub Public Sub DisconnectAddIn(Mode As Integer) AddInMenuLine.DisconnectEvents hMenuLine ThisInstance.AddInMenu.MenuItems.Remove AddInMenuLine End Sub Public Sub AfterClick() MsgBox "Basic Add-In Example" End Sub 5. Automatically Adding Add-In to Vb.ini: In the minimal add-in, you added the add-in to the Vb.ini by hand. However, it is much easier for the user to install the add-in if it does this automatically. To do this requires the use of GetPrivateProfileString to check if it has already been added and WritePrivateProfileString to add it if it isn't there. A good place to put this code is in the Sub Main for EXE servers. However, for DLL servers, the Sub Main is not executed so this does not work. If you are creating a DLL server you will have to put this code somewhere else, such as in your setup program: #If Win16 Then Declare Function WritePrivateProfileString Lib "KERNEL" ( _ ByVal AppName As String, ByVal KeyName As String, _ ByVal keydefault As String, ByVal FileName As String) As Integer Declare Function GetPrivateProfileString Lib "KERNEL" ( _ ByVal AppName As String, ByVal KeyName As String, _ ByVal keydefault As String, ByVal ReturnString As String, _ ByVal NumBytes As Integer, ByVal FileName As String) As Integer #ElseIf Win32 Then Declare Function WritePrivateProfileString Lib "KERNEL32" _ Alias "WritePrivateProfileStringA" (ByVal AppName As String, _ ByVal KeyName As String, ByVal keydefault As String, _ ByVal FileName As String) As Long Declare Function GetPrivateProfileString Lib "KERNEL32" _ Alias "GetPrivateProfileStringA" (ByVal AppName As String, _ ByVal KeyName As String, ByVal keydefault As String, _ ByVal ReturnString As String, ByVal NumBytes As Long, _ ByVal FileName As String) As Long #End If Sub Main() #If Win16 Then Const Section = "Add-Ins16" #ElseIf Win32 Then Const Section = "Add-Ins32" #End If Const BufSize = 255 Dim Ret As Variant Dim RetStr As String 'Check to see if the entry is already in the Vb.ini file. 'Add if not. RetStr = Space(BufSize) Ret = GetPrivateProfileString(Section, "Example.BasicAddin", _ "NotFound", RetStr, BufSize, "VB.INI") RetStr = Left(RetStr, Ret) If RetStr = "NotFound" Then WritePrivateProfileString Section, "Example.BasicAddin", _ "0", "VB.INI" End If End Sub 6. Testing the Basic Add-In: At this point the basic Add-in has been created. To test it, run the project. Then, start a second instance of Visual Basic. From the second instance, go to the Add-In manager and check Example.BasicAddIn. Then go to the Visual Basic Add-In menu. You should see a newly added menu item under the Visual Basic Add-In menu. Click the menu and the message box should be displayed. Additional query words: addin addins ====================================================================== Keywords : kbAddIn kbVBp400 kbGrpDSVB kbDSupport Technology : kbVBSearch kbAudDeveloper kbVB400Search kbVB400 kbVB16bitSearch Version : WINDOWS:4.0 Issue type : kbhowto ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 2001.