Same Classes, Different Units

One of the cornerstones of the source-code compatibility between CLX and VCL is the fact that similar classes in the two libraries have the same class name. For example, each library has a class called TButton representing a push button; the methods and properties are so similar that this code will work with both libraries:

with TButton.Create (Self) do
begin
  SetBounds (20, 20, 80, 35);
  Caption := 'New';
  Parent := Self;
end;

The two TButton classes can have the same name because they are saved in two different units, called StdCtrls and QStdCtrls. Of course, you cannot have the two components available at design time in the palette, because the Delphi IDE can register only components with unique names. The entire VisualCLX library is defined by units corresponding to the VCL units, but with the letter Q as a prefix—so there is a QForms unit, a QDialogs unit, a QGraphics unit, and so on. A few peculiar units, such as QStyle, have no corresponding unit in VCL because they map to features of Qt with no correspondence in the Windows API.

Notice that there are no compile settings or other hidden techniques to distinguish between the two libraries; what matters is the set of units referenced in the code. Remember that these references must be consistent—you cannot mix visual controls of the two libraries in a single form or even in a single program.

DFM and XFM

As you create a form at design time, it is saved to a form definition file. Traditional VCL applications use the DFM extension, which stands for Delphi form module. CLX applications use the XFM extension, which stands for cross-platform (X) form module. A form module is the result of streaming the form and its components: The two libraries share the streaming code, so they produce a similar effect. The format of DFM and XFM files, which can be based on a textual or binary representation, is identical.

So, the reason for having two different extensions doesn't lie in internal compiler tricks or incompatible formats. It is merely an indication to programmers and to the IDE of the type of components you should expect to find within that definition (this indication is not included in the file).

If you want to convert a DFM file into an XFM file, you can simply rename the file. However, expect to find some differences in the properties, events, and available components— reopening the form definition for a different library will probably cause quite a few warnings.

As an example, I've built two identical applications, LibComp and QLibComp, with only a few components and a single event handler. Listing 5.1 presents the textual form definitions for two applications, built using the same steps in the Delphi IDE, after choosing a CLX or VCL application. I've marked differences in bold; as you can see, there are very few, most relating to the form and its font. OldCreateOrder is a legacy property used for compatibility with Delphi 3 and older code; standard colors have different names; and CLX saves the scroll bars' ranges.

Listing 5.1: An XFM File (Left) and an Equivalent DFM File (Right)

object Form1: TForm1              object Form1: TForm1
  Left = 192                        Left = 192
  Top = 107                         Top = 107
  Width = 350                       Width = 350
  Height = 210                      Height = 210
  Caption = 'QLibComp'              Caption = 'LibComp'
 Color = clBackground              Color = clBtnFace
 VertScrollBar.Range = 161         Font.Charset = DEFAULT_CHARSET
 HorzScrollBar.Range = 297         Font.Color = clWindowText
                                   Font.Height = -11
                                   Font.Name = 'MS Sans Serif'
                                   Font.Style = []
  TextHeight = 13                   TextHeight = 13
  TextWidth = 6                     OldCreateOrder = False
  PixelsPerInch = 96                PixelsPerInch = 96
  object Button1: TButton           object Button1: TButton
    Left = 56                         Left = 56
    Top = 64                          Top = 64
    Width = 75                        Width = 75
    Height = 25                       Height = 25
    Caption = 'Add'                   Caption = 'Add'
    TabOrder = 0                      TabOrder = 0
    OnClick = Button1Click            OnClick = Button1Click
 end                               end
  object Edit1: TEdit               object Edit1: TEdit
    Left = 40                         Left = 40
    Top = 32                          Top = 32
    Width = 105                       Width = 105
    Height = 21                       Height = 21
    TabOrder = 1                      TabOrder = 1
    Text = 'my name'                  Text = 'my name'
 end                               end
  object ListBox1: TListBox         object ListBox1: TListBox
    Left = 176                        Left = 176
    Top = 32                          Top = 32
    Width = 121                       Width = 121
    Height = 129                      Height = 129
    Rows = 3                          ItemHeight = 13
    Items.Strings = (                 Items.Strings = (
      'marco'                           'marco'
      'john'                            'john'
      'helen')                          'helen')
    TabOrder = 2                      TabOrder = 2
 end                               end
end                               end

uses Statements

If you look at the source code of a VCL or CLX application, the only relevant difference relates to the uses statements. The form of the CLX application has the following initial code:

unit QLibCompForm;
interface
uses
  SysUtils, Types, Classes, QGraphics, QControls, QForms, QDialogs, QStdCtrls;

The form of the VCL program has the traditional uses statement:

unit LibCompForm;
interface
uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, StdCtrls;

The code of the class and of the only event handler is absolutely identical. Of course, the compiler directive {$R *.dfm} is replaced by {$R *.xfm} in the CLX version of a standard program.

Disabling the Dual Library Help Support

When you press the F1 key in the editor to ask for help on a routine, class, or method of the Delphi library, you'll usually get a choice between the VCL and CLX declarations of the same feature. You'll need to make a choice to proceed to the related help page, which can be quite annoying after a while (especially because the two pages are often identical).

If you don't care about CLX and are planning to use only VCL (or vice versa), you can disable this alternative by choosing the Help ® Customize command, removing everything with CLX in the name from Contents, Index, and Link, and saving the project. Then restart the Delphi IDE, and the Help engine won't bother asking you about CLX any more. Of course, don't forget to add those help files again if you decide to begin using CLX. Similarly, you can reduce the memory occupation and load time of the Delphi IDE by uninstalling all the CLX-related packages.

Running It on Linux

The real issue of choosing the library resolves to the importance of Linux or Unicode for you and your users. It's important to notice that if you create a CLX application, you'll be able to recompile it unchanged (with the exact source code) with Kylix, producing a native Linux application, unless you've done any Windows API programming at all, in which case conditional compilation will be essential.

As an example, I've recompiled the QLibComp example introduced earlier. Figure 5.2 shows it running; you can also see the Kylix IDE in action on KDE.

Figure 5.2: An application written with CLX can be directly recompiled under Linux with Kylix (displayed in the background).

Conditional Compilation for Libraries

If you want to keep a single source code file but compile with VCL on Windows and CXL on Linux, you can use platform-specific symbols (such as $IFDEF LINUX) to distinguish the two situations in case of conditional compilation. But what if you want to be able to compile a portion of code for both libraries on Windows?

You can either define a symbol of your own and use conditional compilation, or (at times) test for the presence of identifiers that exist only in VCL or CLX:

{$IF Declared(QForms)}
  ...CLX-specific code
{$IFEND}