VCL to FMX Migration

Overview

Migrating a TeeTree application from VCL to FireMonkey (FMX) enables cross-platform deployment while maintaining most of your existing code. This guide covers the key differences and required changes.

Quick Migration Checklist

Update Unit References

Replace VCL units with FMX equivalents

Update Color Constants

Change VCL colors to TAlphaColors

Update Component Types

Replace VCL controls with FMX controls

Handle Platform Differences

Adapt code for mobile and desktop platforms

Test on All Platforms

Verify functionality on each target platform

Unit References

Replace VCL Units with FMX

uses
  Windows, Messages, SysUtils, Classes, Graphics, 
  Controls, Forms, Dialogs, ExtCtrls, StdCtrls, 
  Printers, ImgList,
  TeeProcs, TeeTree, TeCanvas, TreeEd;

Key Unit Mappings

VCL Unit	FMX Unit	Notes
`TeeTree`	`FMXTee.Tree`	Main tree component
`TeeProcs`	`FMXTee.Procs`	Helper procedures
`TeCanvas`	`FMXTee.Canvas`	Canvas operations
`Graphics`	`FMX.Graphics`	Graphics types
`Controls`	`FMX.Controls`	Control base classes
`Forms`	`FMX.Forms`	Form classes
`Dialogs`	`FMX.Dialogs`	Dialog functions
`StdCtrls`	`FMX.StdCtrls`	Standard controls
`ExtCtrls`	`FMX.Layouts`	Panels become layouts
`Printers`	`FMX.Printer`	Desktop only
`ImgList`	N/A	Use different approach

Color System Changes

VCL to FMX Color Conversion

procedure TForm1.SetVCLColors;
begin
  Tree1.Color := clWhite;
  Node1.Brush.Color := clBlue;
  Node1.Border.Color := clBlack;
  Node1.Font.Color := clRed;
  
  // Custom color
  Node1.Brush.Color := RGB(255, 128, 0);
end;

Color Constant Mapping

VCL Constant	FMX Constant
`clWhite`	`TAlphaColors.White`
`clBlack`	`TAlphaColors.Black`
`clRed`	`TAlphaColors.Red`
`clBlue`	`TAlphaColors.Blue`
`clGreen`	`TAlphaColors.Green`
`clYellow`	`TAlphaColors.Yellow`
`clGray`	`TAlphaColors.Gray`
`clSilver`	`TAlphaColors.Silver`
`clNavy`	`TAlphaColors.Navy`
`clNone`	`TAlphaColors.Null`

Component Property Changes

Control Alignment

Tree1.Align := alClient;
Panel1.Align := alTop;
Button1.Align := alBottom;

Bevel Styles

Tree1.BevelOuter := bvLowered;
Tree1.BevelInner := bvNone;
Tree1.BevelWidth := 1;

TeeTree-Specific Changes

No Breaking Changes in Core API

Good news! The core TeeTree API remains virtually identical between VCL and FMX. Most of your tree manipulation code will work without changes.

// This code works identically in both VCL and FMX!
procedure TForm1.CreateTreeStructure;
var
  Root, Child: TTreeNodeShape;
begin
  Root := Tree1.Add('Root');
  Child := Root.AddChild('Child 1');
  Root.AddChild('Child 2');
  Root.AddChild('Child 3');
  
  Root.Expanded := True;
  Child.Selected := True;
  
  // Styling
  Root.Brush.Color := {VCL: clBlue} {FMX: TAlphaColors.Blue};
  Root.Font.Size := 12;
  Root.Border.Width := 2;
end;

Minor Constant Differences

const
  TeeDefaultBoxSize = 4;
  TreeMsg_TeeExtension = 'tte';

Event Handler Signatures

Coordinate Types

FMX uses Single (float) instead of Integer for some coordinates:

procedure TForm1.FormMouseMove(Sender: TObject; 
  Shift: TShiftState; X, Y: Integer);
begin
  // X, Y are Integer
end;

TeeTree Events Remain the Same

// Both VCL and FMX use identical signatures:

procedure TForm1.Tree1ClickShape(Sender: TTreeNodeShape;
  Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
begin
  ShowMessage('Clicked: ' + Sender.Text[0]);
end;

procedure TForm1.Tree1SelectShape(Sender: TTreeNodeShape);
begin
  Caption := 'Selected: ' + Sender.Text[0];
end;

Platform-Specific Code

Conditional Compilation

procedure TForm1.PlatformSpecificFeatures;
begin
  {$IFDEF MSWINDOWS}
  // Windows-specific code (both VCL and FMX)
  Tree1.CopyToClipboardMetafile;
  {$ENDIF}
  
  {$IFDEF FMX}
  // FMX-specific code (all platforms)
  Tree1.Touch.InteractiveGestures := [TInteractiveGesture.Zoom];
  {$ENDIF}
  
  {$IFNDEF FMX}
  // VCL-specific code
  Tree1.PrintPreview;
  {$ENDIF}
  
  {$IF DEFINED(IOS) OR DEFINED(ANDROID)}
  // Mobile platforms
  Tree1.Selected.HandleSize := 10;  // Larger for touch
  {$ENDIF}
end;

Feature Availability Matrix

Feature	VCL	FMX Windows	FMX macOS	FMX Mobile
Core tree operations	✅	✅	✅	✅
Node styling	✅	✅	✅	✅
Connections	✅	✅	✅	✅
Printing	✅	✅	✅	❌
Clipboard (Bitmap)	✅	✅	✅	❌
Clipboard (Metafile)	✅	✅	❌	❌
ImageList	✅	❌*	❌*	❌*
Touch gestures	❌	✅	✅	✅
Custom cursors	✅	✅	⚠️	⚠️
Transparency	⚠️	✅	✅	✅
GPU acceleration	❌	✅	✅	✅

*Use alternative approaches in FMX

Common Migration Scenarios

Replacing ImageList

procedure TForm1.SetupVCLImages;
begin
  Tree1.Images := ImageList1;
  Node1.ImageListIndex := 0;
  Node2.ImageListIndex := 1;
end;

Printing Code

uses
  Printers;

procedure TForm1.PrintTree;
begin
  Tree1.PrintPreview;
end;

Form Styling

procedure TForm1.SetupVCLForm;
begin
  Color := clBtnFace;
  Font.Name := 'Tahoma';
  Font.Size := 8;
end;

Step-by-Step Migration Process

Step 1: Create FMX Project

// File > New > Multi-Device Application - Delphi
// Choose Blank Application template

Step 2: Copy and Convert Form

Create a new FMX form with the same name
Manually recreate the form layout (cannot directly convert .dfm to .fmx)
Place TTree component from Tool Palette

Step 3: Update Code

// 1. Update uses clause (see above)
// 2. Replace color constants
// 3. Update alignment constants
// 4. Add conditional compilation where needed

Step 4: Test on Multiple Platforms

// Test on each target platform:
// - Windows 32/64
// - macOS
// - iOS (if targeting)
// - Android (if targeting)

Migration Tools

Search and Replace Patterns

Colors
Alignment
Units

Find	Replace
`clWhite`	`TAlphaColors.White`
`clBlack`	`TAlphaColors.Black`
`clRed`	`TAlphaColors.Red`
`clBlue`	`TAlphaColors.Blue`
`clGreen`	`TAlphaColors.Green`

Find	Replace
`alClient`	`TAlignLayout.Client`
`alTop`	`TAlignLayout.Top`
`alBottom`	`TAlignLayout.Bottom`
`alLeft`	`TAlignLayout.Left`
`alRight`	`TAlignLayout.Right`

Find	Replace
`TeeTree`	`FMXTee.Tree`
`TeeProcs`	`FMXTee.Procs`
`TeCanvas`	`FMXTee.Canvas`

Testing Your Migration

Validation Checklist

Common Issues and Solutions

Issue: Colors Look Different

FMX uses RGBA color space. Ensure you’re using TAlphaColors constants.

// Wrong
Node.Brush.Color := clBlue;  // VCL constant

// Correct
Node.Brush.Color := TAlphaColors.Blue;

Issue: Text Too Small on Mobile

procedure TForm1.FixMobileFonts;
begin
  {$IF DEFINED(IOS) OR DEFINED(ANDROID)}
  Tree1.Font.Size := 16;  // Larger for mobile
  {$ELSE}
  Tree1.Font.Size := 10;  // Desktop size
  {$ENDIF}
end;

Issue: Touch Targets Too Small

procedure TForm1.FixTouchTargets;
begin
  {$IF DEFINED(IOS) OR DEFINED(ANDROID)}
  // Make nodes larger for touch
  Tree1.GlobalFormat.ChildManager.HorizMargin := 30;
  Tree1.GlobalFormat.ChildManager.VertMargin := 20;
  {$ENDIF}
end;

Best Practices

Test on all target platforms early and often
Use conditional compilation for platform-specific features
Design with touch in mind if targeting mobile
Keep a VCL version if Windows-only features are critical
Use TAlphaColors from the start in new FMX code

When Not to Migrate

Consider keeping VCL if:

Application is Windows-only and will remain so
Heavy reliance on Windows-specific features
Performance is critical (VCL is faster on Windows)
Using many third-party VCL-only components
Target users are all on Windows desktop

Get Started

Core Concepts

Guides

VCL & FMX

​Overview

​Quick Migration Checklist

​Unit References

​Replace VCL Units with FMX

​Key Unit Mappings

​Color System Changes

​VCL to FMX Color Conversion

​Color Constant Mapping

​Component Property Changes

​Control Alignment

​Bevel Styles

​TeeTree-Specific Changes

​No Breaking Changes in Core API

​Minor Constant Differences

​Event Handler Signatures

​Coordinate Types

​TeeTree Events Remain the Same

​Platform-Specific Code

​Conditional Compilation

​Feature Availability Matrix

​Common Migration Scenarios

​Replacing ImageList

​Printing Code

​Form Styling

​Step-by-Step Migration Process

​Step 1: Create FMX Project

​Step 2: Copy and Convert Form

​Step 3: Update Code

​Step 4: Test on Multiple Platforms

​Migration Tools

​Search and Replace Patterns

​Testing Your Migration

​Validation Checklist

​Common Issues and Solutions

​Issue: Colors Look Different

​Issue: Text Too Small on Mobile

​Issue: Touch Targets Too Small

​Best Practices

​When Not to Migrate

​See Also

Build docs developers (and LLMs) love

Overview

Quick Migration Checklist

Unit References

Replace VCL Units with FMX

Key Unit Mappings

Color System Changes

VCL to FMX Color Conversion

Color Constant Mapping

Component Property Changes

Control Alignment

Bevel Styles

TeeTree-Specific Changes

No Breaking Changes in Core API

Minor Constant Differences

Event Handler Signatures

Coordinate Types

TeeTree Events Remain the Same

Platform-Specific Code

Conditional Compilation

Feature Availability Matrix

Common Migration Scenarios

Replacing ImageList

Printing Code

Form Styling

Step-by-Step Migration Process

Step 1: Create FMX Project

Step 2: Copy and Convert Form

Step 3: Update Code

Step 4: Test on Multiple Platforms

Migration Tools

Search and Replace Patterns

Testing Your Migration

Validation Checklist

Common Issues and Solutions

Issue: Colors Look Different

Issue: Text Too Small on Mobile

Issue: Touch Targets Too Small

Best Practices

When Not to Migrate

See Also