DOCUMENT:Q188577 28-AUG-1998 [vbwin] TITLE :HOWTO: What is the Licenses Collection Used For? PRODUCT :Microsoft Visual Basic for Windows PROD/VER:WINDOWS:6.0 OPER/SYS:WINDOWS KEYWORDS: ====================================================================== --------------------------------------------------------------------- The information in this article applies to: - Microsoft Visual Basic Learning, Professional, and Enterprise Editions for Windows, version 6.0 --------------------------------------------------------------------- SUMMARY ======= Visual Basic 6.0 allows you to dynamically load ActiveX controls when an application is running. Some ActiveX controls require the use of a license in order for them to be used within a program. The Licenses Collection of an application contains the license information for all loaded ActiveX controls and allows you to add and remove these Licenses as needed. This article demonstrates how to create an ActiveX Control that requires a license and how to load that control dynamically. MORE INFORMATION ================ ActiveX controls used within a Visual Basic 6.0 application may require a license. During development, you can add references to controls within your project and use these controls as you would use intrinsic Visual Basic controls. At compile-time, Visual Basic will incorporate the license for a control into the EXE, so the control can be used in that application on other machines without needing the license on that machine. Steps to Create an ActiveX Control ---------------------------------- 1. Create a New ActiveX Control project in Visual Basic. 2. Add a Label to the control, and set the label's caption to "Test Control." 3. Select Project1 Properties from the Project menu. 4. On the "General" tab, check "Require License Key." This will ensure a design-time license is required for using this control. 5. Add the following code to the UserControl1 object: Private Sub UserControl_Initialize() UserControl.BackColor = vbBlue End Sub1 6. Save the project and make the .OCX. NOTE: The ProgId (Programmatic Identifier) of the ActiveX control will be Project1.Usercontrol1. ProgIds will be discussed in more detail later in this article. Steps to Create a Test Client for the License Control ----------------------------------------------------- 1. Create a new Standard EXE project in Visual Basic. Form1 will be created by default. 2. Add two CommandButtons to Form1. 3. Add the following code to Form1: Option Explicit ' create an object reference so a control can be dynamically loaded ' during run-time. Private ctlMyTestControl As VBControlExtender Private Sub Command1_Click() ' The test control will be loaded without its design-time license ' first. This will result in an error that will be trapped or ' reported in a MSGBOX. On Error GoTo NoLicense ' load the test control dynamically. Set ctlMyTestControl = Form1.Controls.Add("Project1.UserControl1", _ "ctlTest") ' show the test control. ctlMyTestControl.Visible = True ' exit this function. Exit Sub NoLicense: ' make sure the error is about the license for this control. If Err.Number = 731 Then MsgBox "You need a License to dynamically load this ActiveX" & _ & " control" End If End Sub Private Sub Command2_Click() ' add the license of the test ActiveX control to the ' running application and then dynamically load the ' control. Licenses.Add "Project1.usercontrol1" ' load the test control dynamically. Set ctlMyTestControl = Form1.Controls.Add("Project1.UserControl1", _ "ctlTest") ' show the test control. ctlMyTestControl.Visible = True End Sub 4. Press the F5 key to run the project. 5. Press the "Command1" button. This will load the ActiveX UserControl without loading its design-time license. You will receive an error message. 6. Press the "Command2" button. This will load the ActiveX UserControls license and then dynamically load the control and display it on the form. Caveats About ActiveX Control and Licenses ------------------------------------------ - ActiveX controls referenced within a Visual Basic project do not need to have their licenses loaded before dynamically loading them. They are already included within the Licenses Collection and trying to add a license twice will result in a trappable run-time error. - Simply copying and registering a Visual Basic ActiveX UserControl onto a target machine does not mean the license will be installed. You need to distribute the ActiveX control through the Package and Deployment Wizard and have the end user install the control before the ActiveX control can be dynamically loaded during run-time. - Trying to add a license to the License Collection of an ActiveX control that does not need one will result in a trappable run-time error. - The Licenses Collection has two properties for each item; a LicenseKey and a ProgId. The LicenseKey item is encrypted so the actual license for an ActiveX control is not revealed to either the developer or the end user. - It is common to reference a control during development and forget to remove its reference before compiling and distributing the end application. Select the "Remove Information About Unused ActiveX Controls" from the Project Properties Make Tab to remove references to UserControls that you might have added during development time, but are only used dynamically at runtime. This will ensure that the license information for unused controls are not included within the EXE. ProgIds for ActiveX Controls ---------------------------- In order to load an ActiveX control Dynamically, you need to know the ProgId of the control. If the control was developed by you in Visual Basic 6.0, the ProgId will follow the PROJECTNAME.CONTROLNAME convention. To learn the ProgId for an ActiveX control, add a reference to the control to a project. Use the Object Browser (F2) to see all the object models available. If you are going to load an ActiveX control at run-time and perform license checking, make sure you remove the reference to the control from the project, or select the "Remove Information About Unused Active Controls" option mentioned above. Additional query words: kbDSupport kbdss kbCtrl kbCtrlCreate kbVBp600 kbVBp ====================================================================== Version : WINDOWS:6.0 Platform : WINDOWS 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 1998.