Migrating your applications from previous versions of JEDI VCL


Introduction

Since the previous release JVCL has undergone some major changes. Old components have been bug fixed, enhanced, merged and removed, new components and libraries have been added, units have been renamed and the previous monolithic package has been split into several smaller packages. The folder structure has also changed: Source files have been rearranged into design and run folders, packages have been moved into separate folders based on the supported compiler version.

 

Taken together, moving your applications from JVCL 2.10 to the current version can seem to be quite a daunting task and many things can go wrong if migration tasks aren't performed in the right order using the right tools. This document is a help in making this migration as easy as possible. 

 

Please note that although the document refers to "Delphi" in several places, the instructions applies equally to other versions of Borland GUI's (like C++Builder and Kylix) unless the text specifically says otherwise.

 

General migration issues

 

Before you start moving your application to the latest JVCL, you must make sure that you can go back if something goes wrong. To accomplish this, you must perform the following steps:

 

You also need to make sure that Delphi doesn't use use the old JVCL sources and/or binaries once you've started the migration. To make sure that none of the old files are used by Delphi, you should

 

Your computer should now be "JVCL free" and you are ready to start migrating.

 

Step one - installation

 

Before you can start using the new JVCL, you need to install it. Follow the instructions in install.htm to install JCL/JVCL. Add any required paths to the Environment Options in Delphi. Since it is impossible to know what JVCL packages you will actually need in your development, we recommend that you start by installing all of them. You can go back later and remove or deactivate those that you don't use.

 

Make sure that you can use the JVCL components by creating a new empty project, drop a few JVCL components on the form and try to run it. If the application builds and runs without errors, you are ready to start using JVCL.

 

Step two - search and replace

 

After successfully installing JVCL, you need to go through your application sources outside Delphi and replace any occurrences of old unit, class and type names with the new names. You can do this manually by referencing the list of renames in readme.htm and changelog.txt but it is a lot simpler to use the JVCL Convert program and the provided conversion data file.

 

JVCL Convert is a tool that can search a set of selected files and replace occurrences of one text with another by reading the entries in a conversion file. A conversion file contains pairs of old/new values.

 

The source to JVCL convert is in the <JVCL>\devtools\JVCLConvert, a precompiled exe is in <JVCL>\devtools\bin and all available dat files are in <JVCL>\converter.

 

A conversion file named JVCL3.dat is provided with the download of JVCL. Run the JVCLConvert program with the JVCL3.dat file on your application source files. You can know try to open your project in Delphi. If it opens and compiles without problem, you are finished and can start using JVCL 3.

 

Step three - replace removed components

 

In some cases, the simple replacement of unit, class and type names isn't sufficient to make your application run. For example, if you use a component that has been removed or replaced by  another component, properties will most likely be named differently or the components design might be so different that the old properties aren't even usable with the new component. You could even be forced to recode the logic in your application to match the workings of the new component. Some suggestions for dealing with common problems are given below.

 

The only way to sort these problems out is to compare the old components design with the new one and make decision based on that. In rare cases, you can't replace the old component with a new one and need to keep the old one in use. We never delete components once they have been added to JVCL. Instead, all old components are available in the \archive folder (this folder is only included in the full install). To use, you will need to manually add the component unit(s) to a package of your choice and you will most likely also have to write a Register procedure to install it in Delphi.

 

Step four - future proof your application

 

Although we don't anticipate that we will ever do such a complete overhaul of the JVCL again, you still need to future proof your applications so the next version of JVCL doesn't catch you by surprise. Since almost all the duplicate components in JVCL have been merged, there are not many that we think will change. But you should still consider the following:

 

 

Migrating from pre-JVCL donated libraries

 

As well as providing a JVCLConvert file to update JVCL 2.10 code, the JVCL distribution includes converter files for the various donated libraries that have been adopted into JVCL. These are found in the converter folder as shown:

 

Pre-JVCL library JVCL Convert file
RALib converter\RALib.dat
Globus Lib converter\Globus.dat
Jans converter\Jans.dat
KWizard converter\KWizard2JVCL.dat
UTF (Unified Time Framework) converter\UTFToJVCL.dat
dxPack II converter\dxPackToJVCL.dat
dxDotNetPack II converter\dxDotNetToJVCL.dat
DockPresident 1.03 converter\DockPresidentToJVCL.dat
RxLib See note below

 

Migrating from RxLib to JVCL

 

The converter\RxLib.dat and converter\RxToJVCLApp.dat files converts between RxLib and JVCL2.10 and the resulting names might not be compatible with the latest release. To fix this, first convert using RxToJVCLApp.dat and then run again using converter\JVCL3.dat.

 

Migrating from Globus to JVCL 3.5

 

The converter\Globus.dat file converts between Globus and JVCL 3.00 initial release. However, as the Globus components are being merged into the JVCL, the names and properties change in a way that makes it almost impossible to use the converter. Thus, please refer to the following document where you will find a list of equivalent components and properties.

 

Manual component replacement

 

Here are some obsolete or changed components from JVCL 2.10 that are not converted automatically or not fully converted by JVCLConvert, and must be dealt with manually. The suggested basic techniques are intended to get you going quickly, but you must check that they make sense in your own circumstances. It is also very incomplete.

 

Note that the following suggestions assume that, as suggested above, you have converted all your DFM form files into text, so that they can be edited with an ordinary text editor. You may find it easier to change the DFMs outside the Delphi IDE using Notepad or your choice of editor, only switching back to Delphi to check that the form file loads.

 

TJvIntegerEdit

Search and replace TJvIntegerEdit with TJvValidateEdit in PAS and DFM files, and delete JvTypedEdit from the Uses clause in the PAS. Since TJvValidateEdit defaults to integer edits, this usually suffices.

 

Beware if the Value property of TJvIntegerEdit is read in by TJvFormStorage. This fails (does nothing) silently. You can use the Text property instead, but this leads to incompatibility with existing INI files or Regsitry keys. A rather horrible workaround is to use the Text property and implement an OnTranslatePropertyName to map the Text property to the Value property. Note that this is being worked on and a fix will be provided shortly.

 

TJvFloatEdit2

Search and replace TJvFloatEdit with TJvValidateEdit in PAS and DFM files, and delete JvTypedEdit from the Uses clause in the PAS. Then set the DisplayFormat property to dfFloat. If you have set the MaxDecimals property, then rename it to DecimalPlaces and set TrimDecimals to True.


TJvImageSquare

In DFM files, replace the BackColor property by Color and ImageList by Images.


TJvxCurrencyEdit

Usually used as an Integer edit, therefore again replaced by TJvValidateEdit. Search/Replace TJVxCurrencyEdit to TJvValidateEdit in PAS and DFM files, then delete the DisplayFormat property of TJVxCurrencyEdit controls in the DFM (if you don't, Delphi may throw an AV attempting to load the form).

 

This should allow you to load the form in the IDE - now check it still does what you want. You should also set the DisplayFormat property to dfCurrency.

 

TJvFormStorage

TJvFormStorage's functionality has been split across multiple components in JVCL. When you try to load a form with an old component, Delphi may well complain about properties that no longer exist, such as IniFilename and IniSection.

 

If you used TJvFormStorage to store settings in an INI file, drop an TJvAppIniFileStorage on the form (from the JvPersistence tab), and set the AppStorage property of your FormStorage to point to it.

 

TJvAppIniFileStorage.FileName property replaces the old IniFilename. If you supply a full path for the file TJvAppIniFileStorage.Location should be set to flCustom to get the component to use your path.
If TJvAppIniFileStorage.Location is left at its default value flExeFile then the file will be written in the .EXE's launch directory.

 

TJvFormStorage.AppStoragePath replaces the old IniSection property. Don't be fazed by the way it appends a backslash when you do it interactively. This doesn't appear in the Section title. If the section name is not significant, or is blank, leave it to default - it will use the Form name, just like a blank IniSection of old.

 

If you used a FormStorage to use the Registry, instead drop a TJvAppRegistryStorage onto the form instead. You may also decide to use the XML component.

 

TJvTimerEvent

Loading a JVCL 2.10 form containing a TJvTimerList into the Delphi IDE, you will get an error that
'TJvTimerEvent cannot be found'.

This is caused by a change in TJvTimerList's DFM format. The simplest way to explain is with an example:

Old Format:

  object tlMain: TJvTimerList
Left = 376
Top = 181
object teFormVisible: TJvTimerEvent
Cycled = False
Enabled = False
Interval = 1
OnTimer = teFormVisibleTimer
end
object teDefaultRefresh: TJvTimerEvent
OnTimer = teDefaultRefreshTimer
end
object teDelayedGridUpdate: TJvTimerEvent
Enabled = False
Interval = 0
OnTimer = teDelayedGridUpdateTimer
end
object teDelayedCellEdit: TJvTimerEvent
Enabled = False
Interval = 0
OnTimer = teDelayedCellEditTimer
end
end
New Format:
  object tlMain: TJvTimerList
Events = <
item
Name = 'teFormVisible'
Cycled = False
Enabled = False
Interval = 1
OnTimer = teFormVisibleTimer
end
item
Name = 'teDefaultRefresh'
OnTimer = teDefaultRefreshTimer
end
item
Name = 'teDelayedGridUpdate'
Enabled = False
Interval = 0
OnTimer = teDelayedGridUpdateTimer
end
item
Name = 'teDelayedCellEdit'
Enabled = False
Interval = 0
OnTimer = teDelayedCellEditTimer
end>
Left = 376
Top = 181
end

The simplest solution is just to edit the text from one format to the other.

 

Note that you also have to edit any code in the PAS file that refers to the TTimerEvent directly. For example you have to change this code

 teDelayedCellEdit.Enabled := False;

to this

 tlMain.Events.ItemByName('teDelayedCellEdit').Enabled := False;

 

TJvTransparentButton2

TJvTransparentButton2 will have been replaced automatically by TJvTransparentButton by the converter. However, the Image related properties will not and as such you have to take manual steps. ActiveImage is replaced by Images.ActiveImage and so on for the others. As the converter uses a simple "old"/"new" replacement scheme, it was not possible to put those replacements in as some other components also use a property called ActiveImage (or other) that must not be replaced. Hence the need to replace the properties manually, or if you do a global search an replace, you have to check that only the TJvTransparentButton instances have been modified.