VB2Delphi Migration Kit Help

Copyright(c) 2008-2009 Albert Almeida (caviola@gmail.com)

About Conversion Maps

VB2Delphi lets you transform expressions that refer to entities in external VB libraries to match analogous entities in Delphi's libraries. You can, for example, change a VB control's type name to the equivalent Delphi VCL component's type name or change the order of arguemnts in a method call to conform to the prototype of a Delphi method that offers the same funtionality.

You describe the contents of a VB library and the pertinent transformations in a conversion map file. VB2Delphi uses the information inside a conversion map for two purposes: (1) to perform type resolution on an expression that refers to an external name and (2) to obtain the pertinent transformation to generate the Delphi expression. Transformations are applied at the expression level and are specified on a per-entity basis using mapping templates.

For example, with the aid of an appropriate convertion map(s) VB2Delphi can perform all these code transformations:

VB Delphi
p = MyForm.Point(x, y) p := MyForm.Canvas.Pixels[x, y];
D = VBA.CVDate("07/12/1979") D := VarToDateTime('07/12/1979');
If MsgBox("Sure?", VbYesNo) = vbYes Then if Application.MessageBox('Sure?', '', MB_YESNO) = ID_YES then
Dim vt as VBA.VbVarType var vt : TVarType;
br = vbAbort br := ID_ABORT;
SavePicture pic, "mypic.bmp" pic.SaveToFile('mypic.bmp');
MyProperty = 10 * n MyPropertyProc( 10 * n );

Structure of a Conversion Map File

The structure of a map is tree-based and hence easily represented in XML. A map consists of a root library element with any number of enum, record, module and class sub-elements that describe the member types of the library. These type description elements may contain any number of const, var, func, sub, propget and propput sub-elements that describe the members of these types. The following table shows all valid element names, their meaning and applicable sub-elements.

Element Meaning Sub-Elements
library The root element of a map file. enum
record
module
class
enum Describes an enumerated type. const
record Describes a record type. var
module Describes a set of static members. var
sub
func
propget
propput
class Describes a class type. var
sub
func
propget
propput
const Describes a constant.  
var Describes a record field or a module/class variable/property.  
sub Describes a subroutine.  
func Describes a function.  
propput Describes a property letter/setter function.  
propget Describes a property getter function.  

The following tables shows the applicable attributes for each element and their meanings

Attribute Meaning Applies To
name The name of the described VB entity.This is the only mandatory attribute.
 All elements.
argc The number of arguments expected by a VB sub, func, propget or propput.
This attribute is not mandatory but you are advised to always provide it as it's used to more accurately identify the entity to which a given name refers in an expression. 		func
sub
propget
propput
type Specifies the type of a variable or the return type of a function/property.
Intrinsic VB types are represented with their own names, e.g. string as well as user defined types, e.g. ClipBoardConstants.
When referencing a type from another library the type name should be qualified with the library name just like in VB, e.g. stdole.Font.
 var
func
propget
baseClass Specifies the class from which to inherit some of the members descriptions.
For example, we can put all common members of the VB intrinsic controls in the Control class.
This way we don't need to declare the Width property in both TextBox and Label.
Instead, we declare Width only in Control and make TextBox and Label inherit from Control with baseClass="Control". 		class
map Mapping template string.
Only the actual external name and its arguments(if any) may be changed.
More on this in the following section. 		All elements.
nameMap Specifies solely a name substitution. All elements.
fullMap Mapping template string. All parts of the expression may be changed.
More on this in the following section. 		All elements.

Here is a sample conversion map file that only describes the contents of a VB library. 

<?xml version="1.0" encoding="iso-8859-1" ?>
<library name="VBA">
  <module name="Constants">
    <const name="vbCrLf"/>
    <const name="vbNullChar"/>
  </module>
  <module name="Strings">
    <func name="Space" type="string"/>
    <func name="Left" type="string"/>
  </module>
  <enum name="VbVarType"/>
</library>

A conversion map file must have the same name as the file containing the library that it describes suffixed with the .vb2d extension. For example, your custom conversion map for the Common Controls Library COMCT232.OCX must be named COMCT232.OCX.vb2d. The exception to this convention are the names for the VB standard library maps, which are: VB.vb2d, VBA.vb2d and VBRUN.vb2d. Keep in mind that a library name is not the same thing as the library file name. Considering the above example, the library file name is COMCT232.OCX but the library name is ComCtl2. Likewise, the library file name for the Data Grid Control is MSDATGRD.OCX but the library name is MSDataGridLib. The library name is what goes in the name attribute of the one and only library element of a conversion map file. When VB2Delphi is analyzing a project file (.VBP) or a form (.FRM) and it encounters a Reference or Object line it extract the library name, appends .vb2d to it and searches for the resulting file name in the directory where the conversion maps reside. The default path for maps is maps in the instalation directory. The maps for the VB standard library are always loaded automatically.

The GenVB2D program generates skeleton conversion map files. This tool takes a library file path and generates by default a conversion map with all the entities defined in the library.

Mapping Template Syntax

A mapping template is an string containing regular text and special placeholders variables that let you access specific parts of an expression. In general, a VB expression involving a name has the following form:

qualifier.externalName(arg1, arg2...argN) = value

Of course, all parts are not always present and neither they apply to every kind of expression. The value part applies only to assignments, the (arg1, arg2...argN) part to functions/subroutines/properties taking arguments and qualifier is present only in members-access expressions. The following tables shows some sample expressions and their parts according to the general form:

Expression Meaning Qualifier External Name Arguments Value
VBA.VbVarType A type reference. VBA VbVarType
vbOKCancel An enumerated constant. vbOKCancel
Err.Raise 12, "Error!" A subroutine call. Err Raise 12, "Error!"
Err.HelpFile = "help.hlp" An assignment statement. Err HelpFile "help.hlp"
Hobbies("albert") = "Card Magic/Dancing" A property-put statement. Hobbies "albert" "Card Magic/Dancing"

When VB2Delphi encounters an expression refering to an external name, it takes the mapping template along with the expression parts and applies the requested substitutions to produce the Delphi expression.

The following table describes the syntax of these placeholder variables. Inside a mapping template anything that doesn't conform to this syntax is considered regular text and is left untouched.

Placeholder Meaning
%Q. Replace by qualifier if provided.
Note that this may be followed a dot char.
If the qualifier has been provided it's replaced followed by the dot char.
Otherwise the dot is not written.
%W Replace by qualifier.
If the expression is not explicitly qualified this is replaced by the most recent "With" statement expression.
%n{alt} Replace by argument at position "n".
If argument "n" is omitted the optional mapping template "alt" is processed.
To avoid potential infine recursion, if "alt" contains an argument placeholder, its "alt" is not processed this time.
%V Refers to the value of an assignment.

The following table shows some sample uses of the placeholder variables.

VB Template Delphi
p = MyForm.Point(x, y) Canvas.Pixels[%1, %2]
Template specified for Point. 		p := MyForm.Canvas.Pixels[x, y];
D = VBA.CVDate("07/12/1979") VarToDateTime(%1)
Template specified for CVDate.		 D := VarToDateTime('07/12/1979');
If MsgBox("Sure?", VbYesNo) = vbYes Then Application.MessageBox(%1, %3{''}, %2)
Template specified for MsgBox.		 if Application.MessageBox('Sure?', '', MB_YESNO) = ID_YES then
Dim vt as VBA.VbVarType TVarType
Template specified for VbVarType.		 var vt : TVarType;
br = vbAbort ID_ABORT
Template specified for vbAbort.		 br := ID_ABORT;
SavePicture pic, "mypic.bmp" %1.SaveToFile(%2)
Template specified for SavePicture. 		pic.SaveToFile('mypic.bmp');
MyProperty = 10 * n MyPropertyProc(%V)
Template specified for MyProperty.
This is an example of a fullMap. 		MyPropertyProc( 10 * n );

For more mapping templates examples see VBA.vb2d.