2.1 Mapping Packs: Optional Third-Party Component Support
A mapping pack is an optional JSON file that gives the converter explicit knowledge about component libraries outside standard VCL. The converter still performs the normal VCL-to-FMX migration work on its own but mapping packs add a separate, visible layer for third-party controls so those decisions can be reviewed instead of hidden inside converter code.
Use mapping packs when a project contains controls from libraries such as DevExpress, TMS, Raize/Konopka, JVCL, EhLib, InfoPower, TeeChart, FastReport, Devart, IntraWeb, UniGUI, or VirtualTreeView. The pack can identify the original VCL class, choose a safe action, map simple properties and events, and explain anything that still requires manual review. This version includes mapping packs for the stated third-party vendors, but while these are included, they do not represent full conversions of the components but rather as much as possible at this point in Delphi FMX.
A mapping pack does not install a vendor product, prove that a commercial component has a full FMX equivalent, or remove the need to test the converted application. Its purpose is to make third-party handling predictable: simple controls may convert, approximate controls may convert with warnings, complex controls may be report-only, and nonvisual or cross-platform items may be preserved when that is the safest choice. Again, they do not represent full conversions of the components but rather as much as possible at this point.
Mapping-pack actions
| Action | What it means for the user |
|---|---|
| convert | The converter can generate the target FMX component with reasonable confidence. |
| partial | The converter can generate an approximate FMX component, but the report must describe the limitations. |
| manual_review | The converter should report the component and avoid unsafe automatic conversion. |
| detect_only | The converter identifies the component or vendor but does not generate a replacement. |
| preserve | The converter may keep the original class/reference when preservation is safer or explicitly intended. |
For normal operation, keep the mapping_packs folder beside VCL2FMXConverter.exe, in whatever folder you install it.
For example if the converter structure is similar to: C:\converter\VCL2FMXConverter.exe
then the mapping packs would be in: C:\converter\mapping_packs\
The packs act as companion files in unison with the converter executable. After a run, review the generated report and their associated report sections for loaded packs, converted third-party components, partial conversions, detect-only findings, preserved components, unknown third-party-looking components, and manual-review reasons.
How to read mapping-pack results
The generated report is a detailed audit trail. If a pack converts a component, the report should say which pack was used and what confidence level was declared. If a pack only detects a component, the report should explain why no FMX replacement was generated.
When testing without owning the vendor library, a mock DFM can still exercise the mapping logic because the converter reads class names from the DFM. That kind of test confirms loader behavior, rule selection, generated output, and report wording, but it does not validate the real vendor component's runtime behavior. The following is an example of a mock .dfm which may be modified for your own use for testing:object FormDevExpressMock: TFormDevExpressMock
Left = 0
Top = 0
Caption = 'DevExpress Mapping Pack Mock Test'
ClientHeight = 360
ClientWidth = 560
object cxButton1: TcxButton
Left = 24
Top = 24
Width = 120
Height = 32
Caption = 'Click Me'
Enabled = True
Visible = True
Hint = 'Button hint'
OnClick = cxButton1Click
end
object cxTextEdit1: TcxTextEdit
Left = 24
Top = 72
Width = 180
Height = 24
Text = 'Sample text'
Enabled = True
Visible = True
OnChange = cxTextEdit1Change
end
object cxMemo1: TcxMemo
Left = 24
Top = 112
Width = 220
Height = 80
Text = 'Sample memo'
Enabled = True
Visible = True
end
object cxMaskEdit1: TcxMaskEdit
Left = 24
Top = 208
Width = 180
Height = 24
Text = '12345'
end
object cxGrid1: TcxGrid
Left = 260
Top = 24
Width = 260
Height = 180
end
object dxRibbon1: TdxRibbon
Left = 0
Top = 264
Width = 560
Height = 80
end
end
Here is the companion .pas file that goes with this .dfmunit UnitDevExpressMock;
interface
uses
System.SysUtils, System.Classes, Vcl.Forms;
type
TFormDevExpressMock = class(TForm)
cxButton1: TcxButton;
cxTextEdit1: TcxTextEdit;
cxMemo1: TcxMemo;
cxMaskEdit1: TcxMaskEdit;
cxGrid1: TcxGrid;
dxRibbon1: TdxRibbon;
procedure cxButton1Click(Sender: TObject);
procedure cxTextEdit1Change(Sender: TObject);
end;
implementation
{$R *.dfm}
procedure TFormDevExpressMock.cxButton1Click(Sender: TObject);
begin
end;
procedure TFormDevExpressMock.cxTextEdit1Change(Sender: TObject);
begin
end;
end.