DFM-serialization in depth

• Download class serialization sample - 57.3 KB
• Download subcomponent serialization sample - 56.3 KB
• Download component tree serialization sample - 58 KB
• Download collection serialization sample - 57.1 KB

Introduction

DFM-serialization mechanism which Delphi ships with may be pretty useful. Usually the basics of this mechanism are well-known by Delphi programmers. But there are real-world scenarios when you should go beyond the basics and the mechanism actually allows you to do that. In the article I will start from the basics and then try to cover more complex situations.

About DFM-format 

DFM-format actually experienced some serious improvements over the history of Delphi. Historically it was binary and not readable. But we are talking about the current state of the format. The primary target of DFM-format was to store descriptions of the forms in order to make it simple to create form descriptions in design-time and create actual forms from descriptions in run-time. The big advantage of DFM-format is its native Delphi support (a little of coding is needed to implemet serialization support for Delphi object). The disadavntage of DFM-format is its low interoperability (when we need to integrate with some external systems it is more preferrable to use standard formats such as XML or JSON).

Object properties

Let's start from the simple example:

object DfmSampleForm: TDfmSampleForm
  Left = 0
  Top = 0
  Caption = 'DfmSampleForm'
  ClientHeight = 202
  ClientWidth = 221
  Color = clBtnFace
  ...
  OldCreateOrder = False
  PixelsPerInch = 96
  TextHeight = 13
end

It is a description of the form, which was generated by VCL Forms application wizard. I just modified some properties of the form. As you can see DFM-format is pretty straightforward. The description starts with object name and class type and inside this block all object properties with their values are presented each on its own string and with block indent. Here we can see properties with integer, boolean, string and enumeration data types.

Child components

If I will add some components onto the form they will appear inside DFM-file as child objects for the form object. For example when I added TMemo and TPanel with TButton on it onto the form the DFM-file became to look like this:

object DfmSampleForm: TDfmSampleForm
  ...
  object Memo: TMemo
    Left = 8
    Top = 8
    Width = 252
    Height = 217
    Anchors = [akLeft, akTop, akRight, akBottom]
    TabOrder = 0
    ...
  end
  object BottomPanel: TPanel
    Left = 0
    Top = 226
    Width = 268
    Height = 32
    Align = alBottom
    Anchors = [akRight, akBottom]
    ...
    object Button: TButton
      Left = 185
      Top = 5
      Width = 75
      Height = 25
      Anchors = [akRight, akBottom]
      Caption = 'Button'
      TabOrder = 0
    end
  end
end

As you can see the whole object tree was saved into one single DFM-format file. 

Custom classes serialization

In spite of the fact that DFM-serialization is primarily created to store form in the textual descriptions in design-time and to restore forms from those descriptions in run-time, it is actually pretty powerful serialization mechanism, which we can use in our projects for our own custom objects. 

Custom class

I created sample application, which contains the following class declaration:

type
  TEnum = (
    enumFirst,
    enumSecond,
    enumThird);

  TSet = set of TEnum;

  TDfmObject = class(TComponent)
  private
    FIntegerProperty: Integer;
    FDoubleProperty: Double;
    FEnumProperty: TEnum;
    FSetProperty: TSet;
    FStringProperty: String;
    FBooleanProperty: Boolean;
    FVariantProperty: Variant;
  published
    property IntegerProperty: Integer read FIntegerProperty write FIntegerProperty;
    property DoubleProperty: Double read FDoubleProperty write FDoubleProperty;
    property EnumProperty: TEnum read FEnumProperty write FEnumProperty;
    property SetProperty: TSet read FSetProperty write FSetProperty;
    property StringProperty: String read FStringProperty write FStringProperty;
    property BooleanProperty: Boolean read FBooleanProperty write FBooleanProperty;
    property VariantProperty: Variant read FVariantProperty write FVariantProperty;
  end;

...

initialization
  System.Classes.RegisterClass(TDfmObject);

...

Sample application form

In the sample application there are two buttons, one of which converts this object into DFM representation and stores it in TMemo component of the form and another button converts this object back from DFM representation in TMemo component into the object instance. 

Streaming implemetation

The methods which access DFM streaming mechanism to perform actual object serialization and deserialization look like this:

type
  TDfmSampleForm = class(TForm)
    ...
  private
    FDfmObject: TDfmObject;
    ...
  end;

procedure TDfmSampleForm.StoreButtonClick(Sender: TObject);
var
  MemoryStream: TMemoryStream;
  StringStream: TStringStream;
begin
  StoreProperties;
  MemoryStream := TMemoryStream.Create;
  try
    MemoryStream.WriteComponent(FDfmObject);
    MemoryStream.Position := 0;
    StringStream := TStringStream.Create;
    try
      ObjectBinaryToText(MemoryStream, StringStream);
      PropertiesMemo.Text := StringStream.DataString;
    finally
      StringStream.Free;
    end;
  finally
    MemoryStream.Free;
  end;
end;

procedure TDfmSampleForm.RestoreButtonClick(Sender: TObject);
var
  MemoryStream: TMemoryStream;
  StringStream: TStringStream;
begin
  StringStream := TStringStream.Create(PropertiesMemo.Text);
  try
    StringStream.Position := 0;
    MemoryStream := TMemoryStream.Create;
    try
      ObjectTextToBinary(StringStream, MemoryStream);
      MemoryStream.Position := 0;
      FDfmObject := MemoryStream.ReadComponent(FDfmObject) as TDfmObject;
    finally
      MemoryStream.Free;
    end;
  finally
    StringStream.Free;
  end;
  RestoreProperties;
end;

So we can use DFM-streaming mechanism to store and restore our own classes. There are quite of limitations on the types of properties, which we can use in the published class section (and which are that's why stored in the DFM). It is forbidden or not supported to use properties of type pointer, record, array, interface and object (in the case when the object is not inherited from TPersistent). It is quite interesting that Variant properties streaming is supported, but it requires that Variant property should have value which in its turn can be streamed.

Unicode support

The previously mentioned sample application allows to research the behavior of serialization mechanism, when unicode characters are used. Delphi fully supports unicode now, but in the DFM-file unicode characters appear as a sequence of symbol codes. It is good news, that Delphi supports unicode in DFM-files, but unfortunately when unicode characters are used in the string values DFM-file representaions of these values becomes not readable. Actually when non-latin characters, which we want to use in the DFM-file, fall into default operating system codepage for non-unicode programs we can use these symbols in the DFM-string values and Delphi streaming system will recognize these symbols. But Delphi makes no assumptions over the default operating system codepage for non-unicode programs, so all non-latin characters in the DFM-file by default are encoded with symbol codes. 

Postponed initialization

Sometimes you need to perform some actions after deserialization from DFM is completed. For example, if you develop a visual component you likely want to suppress updating the component during the time of deserialization and likely want to update component when deserialization is completed. Besides, there may be some properties which work only together and that's why you need the component to be completely deserialized to use these properties properly.

To handle such situations gracefully TComponent class supports Loaded method, which you can override in your descendant class. And also TComponent supports ComponentState property, which contains csLoading flag when component is being loaded from stream. It allows you to check if ComponentState property contains csLoading flag to suppress some actions which you don't need until object is fully deserialized.

Custom properties

It is possible to gain full control over property serialization and deserialization. For this we need to define custom methods to store object property in DFM-file and restore object property from DFM-file. When we do it we actually can store any object type, but we need to represent it through available primitive types. Also when we do it we can read some property and not write it or write some property, which was not read. It may become useful when we have legacy object properties, which differ from actual object properties and we need to perform some conversion. Internally we will use TReader and TWriter methods, which are actually very flexible. 

An example below shows the class, which uses custom property serialization mechanism:

type
  TDfmObject = class(TComponent)
  private
    ...
    FCustomProperty: TCustomProperty;
    procedure ReadCustomProperty(Reader: TReader);
    procedure WriteCustomProperty(Writer: TWriter);
  protected
    { TPersistent }
    procedure DefineProperties(Filer: TFiler); override;
  public
    property CustomProperty: TCustomProperty read FCustomProperty write FCustomProperty;
    ...
  end;

implementation

{ TDfmObject }

procedure TDfmObject.DefineProperties(Filer: TFiler);
begin
  inherited;
  Filer.DefineProperty('CustomProperty', ReadCustomProperty, WriteCustomProperty,
    (FCustomProperty.IntegerField <> 0) or
    (FCustomProperty.StringField <> ''));
end;

procedure TDfmObject.ReadCustomProperty(Reader: TReader);
begin
  Reader.ReadListBegin;
  FCustomProperty.IntegerField := Reader.ReadInteger;
  FCustomProperty.StringField := Reader.ReadString;
  Reader.ReadListEnd;
end;

procedure TDfmObject.WriteCustomProperty(Writer: TWriter);
begin
  Writer.WriteListBegin;
  Writer.WriteInteger(FCustomProperty.IntegerField);
  Writer.WriteString(FCustomProperty.StringField);
  Writer.WriteListEnd;
end;

The DFM-file with custom property will look like this:

object TDfmObject
  ...
  CustomProperty = (
    256
    'string')
end

Object tree serialization

In the previous example there was only one object, which was streamed. Actually it is rare situation: in real scenarios we usually have some object tree, which we want to store in DFM-format and later to restore from DFM-format. Delphi serialization mechanism supports several approaches, which allow to store a whole object tree in a single DFM-file. We will discuss these approaches now.

Collections support

Delphi supports collections of objects, which can be serialized into DFM. The advantage of using collections is Delphi support for editing collections in design-time (you can use standard editor and property inspector to setup a collection). And another advantage is support for serialization with no coding involved. The drawback of collections is the need to inherit from predefined class and that all items in the collection must inherit from one single class type.

To define our own collection we need to create a descendant of TCollectionItem class and, may be, a descendant of TCollection class (actually for serialization support we need to inherit from TOwnedCollection class). Having done it we can make published object property with TCollection class. An example below shows minmal required code to implement a serializable collection with custom items class:

type
  TDfmCollectionItem = class(TCollectionItem)
  private
    FIntegerProperty: Integer;
    FDoubleProperty: Double;
    FStringProperty: String;
  published
    property IntegerProperty: Integer read FIntegerProperty write FIntegerProperty;
    property DoubleProperty: Double read FDoubleProperty write FDoubleProperty;
    property StringProperty: String read FStringProperty write FStringProperty;
  end;

  TDfmObject = class(TComponent)
  private
    FDfmCollection: TOwnedCollection;
    procedure SetDfmCollection(const Value: TOwnedCollection);
  public
    { TComponent }
    constructor Create(AOwner: TComponent); override;
    { TObject }
    destructor Destroy; override;
  published
    property DfmCollection: TOwnedCollection read FDfmCollection write SetDfmCollection;
  end;

implementation

{ TDfmObject }

constructor TDfmObject.Create(AOwner: TComponent);
begin
  inherited;
  FDfmCollection := TOwnedCollection.Create(AOwner, TDfmCollectionItem);
end;

destructor TDfmObject.Destroy;
begin
  FDfmCollection.Free;
  inherited;
end;

procedure TDfmObject.SetDfmCollection(const Value: TOwnedCollection);
begin
  FDfmCollection.Assign(Value);
end;

The result DFM will look like this:

object TDfmObject
  DfmCollection = <
    item
      IntegerProperty = 144
      DoubleProperty = 1.200000000000000000
      StringProperty = 'second'
    end
    item
      IntegerProperty = 256
      DoubleProperty = 3.140000000000000000
      StringProperty = 'first'
    end>
end

You can use the attached sample application to experiment with collection serialization mechanism.

Subcomponents support

Sometimes a group of components exists as a whole. It means that all linked components are created and destroyed simultaneously. And sometimes we want some component to be the part of the other component and we want easily setup both components in design-time. For this scenario Delphi supports subcomponents mechanism. This mechanism allows for component to be stored between with all its subcomponents.

The following code shows simple example of subcomponent usage:

type
  TDfmObject = class;
  TDfmSubObject = class;

  TDfmObject = class(TComponent)
  private
    FStringProperty: String;
    FIntegerProperty: Integer;
    FSubObject: TDfmSubObject;
  public
    { TComponent }
    constructor Create(AOwner: TComponent); override;
  published
    property IntegerProperty: Integer read FIntegerProperty write FIntegerProperty;
    property StringProperty: String read FStringProperty write FStringProperty;
    property SubObject: TDfmSubObject read FSubObject;
  end;

  TDfmSubObject = class(TComponent)
  private
    FStringSubProperty: String;
    FIntegerSubProperty: Integer;
  published
    property IntegerSubProperty: Integer read FIntegerSubProperty write FIntegerSubProperty;
    property StringSubProperty: String read FStringSubProperty write FStringSubProperty;
  end;

implementation

{ TDfmObject }

constructor TDfmObject.Create(AOwner: TComponent);
begin
  inherited;
  FSubObject := TDfmSubObject.Create(Self);
  FSubObject.SetSubComponent(True);
end;

The result DFM-file looks like this:

object TDfmObject
  IntegerProperty = 256
  StringProperty = 'string'
  SubObject.IntegerSubProperty = 4092
  SubObject.StringSubProperty = 'substuing'
end

You can use attached sample application to experiment with subcomponent serialization mechanism.

Child components support

Sometimes you need to store a whole object tree inside the DFM-file and the items in the tree can have different classes. In this scenario you cannot use Delphi collections and you need to create component tree. Delphi TComponent class supports child components list. When you create child component, you just need to specify its parent component as owner. This allows you to create component tree. But by default child components are not stored in the DFM-file and for such storing to happen you need to override some TComponent class methods (namely GetChildOwner and GetChildren). The desired behavior of storing child component descriptions inside the DFM-file is already implemented for TCustomForm class so in our own implementation we just need to do something similar. 

An example below shows code of TComponent descendant class, which allows to store its child components inside DFM-file:

type
  TDfmObject = class(TComponent)
  private
    FNameProperty: String;
    FIntegerProperty: Integer;
    FStringProperty: String;
  protected
    { TPersistent }
    procedure AssignTo(Dest: TPersistent); override;
    { TComponent }
    procedure GetChildren(Proc: TGetChildProc; Root: TComponent); override;
    function GetChildOwner: TComponent; override;
  published
    property NameProperty: String read FNameProperty write FNameProperty;
    property IntegerProperty: Integer read FIntegerProperty write FIntegerProperty;
    property StringProperty: String read FStringProperty write FStringProperty;
  end;

implementation

{ TDfmObject }

procedure TDfmObject.AssignTo(Dest: TPersistent);
var
  DestDfmObject: TDfmObject;
begin
  if Dest is TDfmObject then
  begin
    DestDfmObject := Dest as TDfmObject;
    DestDfmObject.NameProperty := NameProperty;
    DestDfmObject.IntegerProperty := IntegerProperty;
    DestDfmObject.StringProperty := StringProperty;
  end;
end;

function TDfmObject.GetChildOwner: TComponent;
begin
  Result := Self;
end;

procedure TDfmObject.GetChildren(Proc: TGetChildProc; Root: TComponent);
var
  I: Integer;
  OwnedComponent: TComponent;
begin
  inherited GetChildren(Proc, Root);
  for I := 0 to ComponentCount - 1 do
    Proc(Components[I]);
end;

initialization
  System.Classes.RegisterClass(TDfmObject);

The result DFM-file looks like this:

object TDfmObject
  IntegerProperty = 0
  object TDfmObject
    NameProperty = 'Level1.1'
    IntegerProperty = 11
    object TInheritedDfmObject
      NameProperty = 'Level2.1'
      IntegerProperty = 21
    end
    object TInheritedDfmObject
      NameProperty = 'Level2.2'
      IntegerProperty = 22
    end
    object TInheritedDfmObject
      NameProperty = 'Level2.3'
      IntegerProperty = 23
    end
  end
  object TDfmObject
    NameProperty = 'Level1.2'
    IntegerProperty = 12
  end
  object TDfmObject
    NameProperty = 'Level1.3'
    IntegerProperty = 13
  end
end

You can use the attached sample application to experiment with object tree serialization mechanism.

Conclusions

In the article I tried to describe Delphi native serialization mechanism in depth (some topics are still not covered though). I hope that this will material help readers to understand that Delphi serialization mechanism is pretty useful and extendable. It is used mostly by component developers, but actually one can use it to store and restore any application object tree.