ActiveX Controls: VBX Control Migration

  • Article

|  Overview |  How Do I |  FAQ |  |  Sample

SVBX control migration was available only through the VBX template tool, a part of the ControlWizard found in version 1.x of the CDK. Because this tool was removed from the ControlWizard shipped with Visual C++ 4.0, migrating existing VBX controls requires version 1.x of the CDK. The only option for VBX migration using VC ++ 4.0 is to create a framework from ControlWizard and manually port the entire code base of the VBX control into the ActiveX control framework.

As stated above, developers with existing VBX controls can use the VBX template tool, found in the CDK ControlWizard, to convert existing VBX controls to the ActiveX control format.

The VBX template tool helps you migrate your VBX custom control to an ActiveX control. The template tool uses model information in the .VBX file and creates a Visual C++ project file, as well as source code files for creating the ActiveX control. These files can be compiled and linked to produce a working framework for the ActiveX control.

Once this framework is built and tested, the next step is to take code from your VBX source files and place it in the appropriate areas of the generated OLE source files. The transplanted code will probably require some degree of modification to work in the new source code files.

This article explains:

  • Preparing your .VBX source code files for conversion

  • Using the VBX template tool

  • What gets converted

  • Building and testing the framework of your ActiveX control

  • Where to go from here

If you want to port your ActiveX control framework to Visual C++ 4.0, see the article ActiveX Controls: Converting a CDK Project to a Visual C++ Project.

Preparing the VBX Custom Control

For the VBX template tool to properly translate the VBX control, you must expose the VBX control model information to the template builder, using the VBGetModelInfo function. If your VBX source code does not already define this function, first define a MODELINFO structure containing a specific Visual Basic version number, and a NULL-terminated array of MODEL structures. The MFC ActiveX controls sample CIRC3, listed under , defines the MODELINFO structure as follows:

LPMODEL modellistCircle[] =
    {
    &modelCircle,
    NULL
    };

Note   Remember to NULL-terminate the array of model pointers.

MODELINFO modelinfoCircle =
    {
    VB_VERSION,        // VB version being used
    modellistCircle    // MODEL list
    };

Note   If your .VBX file provides different models to support earlier versions, you should create similar MODELINFO structures to point to those models. The CIRC3 custom control, for example, also defines ModelinfoCircle_VB1 and ModelinfoCircle_VB2 structures.

Once you have defined the MODELINFO structure(s), you can define the VBGetModelInfo function, as an export, in your source code. The MFC ActiveX controls sample CIRC3, listed under , defines the function:

LPMODELINFO FAR PASCAL _export VBGetModelInfo
(
    USHORT usVersion
)
{
    if (usVersion <= VB100_VERSION)
        return &modelinfoCircle_Vb1;

    if (usVersion <= VB200_VERSION)
        return &modelinfoCircle_Vb2;
    else
        return &modelinfoCircle;
}

Once this function is defined, rebuild your VBX control before using the template tool.

Running the VBX Template Tool

After your VBX control has been built with the VBGetModelInfo function, as described in the previous topic, you are ready to run the VBX template tool.

As mentioned before, you must be using the ControlWizard that shipped with version 1.x of the CDK. The template tool is not available with Visual C++ 4.0.

If you only need to use the ControlWizard shipped with version 1.x of the CDK, you can copy two files from the distribution CD. These two files, CTLWZLIB.DLL and MFCCTLWZ.EXE, is in the vc152\msvccdk directory of the Visual C++ Version 1.52 CD.

To run the VBX template tool

  1. Start ControlWizard by running MFCCTLWZ.EXE from the DOS command prompt or Windows Explorer.

  2. When the ControlWizard dialog box appears, change to the desired drive and directory and enter a project name. ControlWizard automatically creates a new subdirectory with the same name as the project.

  3. Click Control Options. When the Control Options dialog box appears, choose the Use VBX Control as Template check box.

  4. Click Select VBX Control.

  5. In the Use VBX Control as Template dialog box, type the .VBX file name, including the drive and directory path. Alternatively, you can click Browse to locate and select your .VBX file. All control names defined in the .VBX file are displayed in the control name drop-down list. Select the desired control name from the drop-down list.

    Note   If you select a .VBX file that does not properly export the model information (as described in the Note in Preparing the VBX Custom Control), Visual C++ may crash at this point.

  6. Click OK twice to close the Use VBX Control as Template box and the Control Options box. Click OK from ControlWizard to prepare to create the template.

  7. When the New Control Information box appears, a summary of  the generated files is displayed. Click Create to create all the files for the ActiveX control.

  8. When the VBX template tool is finished, your project directory should contain the following files (the files listed here assume the VBX example control, CIRC3.VBX, was used as the project):

    • CIRC3.CLW

    • CIRC3.CPP

    • CIRC332.DEF

    • CIRC3.DEF

    • CIRC3.H

    • CIRC3.ICO

    • CIRC3.MAK

    • CIRC332.MAK

    • MAKEFILE

    • CIRC3.ODL

    • CIRC3.RC

    • CIRC3.RC2

    • CIRC3CTL.BMP

    • CIRC3CTL.CPP

    • CIRC3CTL.H

    • CIRC3PPG.CPP

    • CIRC3PPG.H

    • README.TXT

    • RESOURCE.H

    • STDAFX.CPP

    • STDAFX.H

In addition, a subdirectory for the Type library file is created. If you are using the 16-bit version of the CDK, it is called TLB16. If you are using the 32-bit version of the CDK, it is called OBJDU.

The README.TXT file contains a summary description of each file created by the VBX template tool. These files are all that is required to build a complete working framework of the new ActiveX control.

What Gets Converted

The template generated by the VBX template tool is similar to the "blank" template that is generated when you use ControlWizard to create a new control, with the following differences:

Stock Properties and Events

ControlWizard converts most of the standard properties and events in your .VBX to fully implemented stock properties and events in the template's source code.

Stock properties supported by the VBX template tool include:

  • BorderStyle

  • Enabled

  • Font

  • Caption

  • Text

  • ForeColor

  • BackColor

  • hWnd

Stock events supported by the VBX template tool include:

  • Click

  • DblClick

  • KeyDown

  • KeyPress

  • KeyUp

  • MouseDown

  • MouseMove

  • MouseUp

Note   A number of properties not mentioned above that were formerly standard in the .VBX Control model are automatically supported by ActiveX as standard "extender" properties (e.g., Left, Top, Height, Width). Therefore, these properties are not needed in an ActiveX control, and are not converted by the VBX template tool.

Currently Unimplemented Properties and Events

Stock properties of the VBX model not supported:

  • DragIcon

  • DragMode

  • MouseCursor

  • MousePointer

Stock events of the VBX model not supported:

  • DragDrop

  • DragOver

  • LinkOpen

  • LinkClose

  • LinkError

  • LinkNotify

Custom Properties and Events

Custom properties and events in your VBX control are provided in the template as stub functions. In order to make these properties and events functional, you must port the implementation code from your VBX control’s source files into the appropriate files in the new control template. These places are indicated by similar comments in the template's source code files:

    // TODO: Initialize your control's instance data here.

Building and Testing the ActiveX Control Framework

After ControlWizard generates the basic framework for your VBX control, build and test the control to familiarize yourself with ActiveX control behavior. The following sections describe this process and demonstrate how to use Test Container to test your new ActiveX control.

Creating the Type Library for the ActiveX Control

Note that the following information only applies if you are using the 16-bit version of Visual C++. If you are using the 32-bit version of Visual C++, the type library is automatically generated by the control makefile.

Before you can compile and link the control template, you must create a type library, used by control containers that use your control. This will be based on the information contained in the Object Description Library (.ODL) file created by the porting tool.

To create the type library

  1. Load the project make file that you generated by running the VBX template tool.

  2. On the Tools menu, click Make TypeLib. MKTYPLIB.EXE creates a type library based on the .ODL file in the project. After building successfully, MKTYPLIB automatically adds the resulting *.TLB file to your project. The information in this .TLB file will be built into your .DLL as a resource.

Compiling, Linking, and Registering the ActiveX Control Framework

Note that the following information only applies if you are using the 16-bit version of Visual C++.

After creating the Type Library, you can build the framework control by choosing Build from the Visual C++ Project menu.

When the project has built successfully, you must register the new control before you can test it. Choose Register Control from the Tools menu. A message box appears, indicating that the control was successfully registered.

Testing the ActiveX Control Framework

For procedures on testing your ActiveX control framework, see the article Test Container.

Where to Go From Here

When you are satisfied that the control framework is working properly, the next step is to port the implementation of your ActiveX control's custom properties and events from your VBX source code to the new control's source code files. To do this, use ClassWizard and the implementation guidelines in the ActiveX controls articles. Remember to back up your files frequently and to use Test Container to test each new block of code as you go.

Once the VBX control is ported to a CDK project, you could port the CDK project to Visual C++ 4.0 by following the steps given in the article ActiveX Controls: Converting a CDK Project to a Visual C++ Project.