Streaming components

From Free Pascal wiki
Jump to navigationJump to search

Introduction

Normally, when you want to store data on disk or to network streams, you must write code for loading and saving each property. This tutorial describes how to write classes, that can be loaded from and saved to streams without writing extra load/save code by using the RTTI.

There is an example in the lazarus sources, demonstrating how to save a TGroupBox with a TCheckBox child to a stream and read the stream back to create a copy of both components.

 See <lazaruspath>/examples/componentstreaming/

TComponent / TPersistent

The class TPersistent is defined in the unit Classes and is uses the {$M+} compiler switch. This switch tells the compiler to create Run Time Type Information (RTTI). This means it and all its descendants get a new class section published. 'Published' properties are visible as 'public', but additonally their structure is accessible at run time. That means all published properties can be read and written at run time. The IDE for instance uses this to work with components it never heard of.

TComponent extends TPersistent by the ability to have child components. This is important for streaming, where one component is the root component also called lookup root with a list of child components.

TReader / TWriter

These are the worker classes, which reads/writes a TComponent to/from a stream (See CreateLRSReader and CreateLRSWriter). They use a Driver to read/write a special format. At the moment there are a reader (TLRSObjectReader) and a writer (TLRSObjectWriter) for binary object format defined in the LResources unit and a writer (TXMLObjectWriter) for TDOMDocument defined in Laz_XMLStreaming. The LResources unit also contains functions to convert binary format to text and back (LRSObjectBinaryToText, LRSObjectTextToBinary). The LCL prefers UTF8 for strings, while Delphi prefers Widestrings. So there some conversion functions as well.

Writing your own component - Part 1

A custom component can be as simple as: type

 TMyComponent = class(TComponent)
 private
   FID: integer;
 published
   property ID: integer read FID write FID;
 end;

Writing a component to a stream

The unit LResources has a function for that:

 procedure WriteComponentAsBinaryToStream(AStream: TStream; AComponent: TComponent);

It writes a component in binary format to the stream. For example:

procedure TForm1.Button1Click(Sender: TObject);
var
  AStream: TMemoryStream;
begin
  AStream:=TMemoryStream.Create;
  try
    WriteComponentAsBinaryToStream(AStream,AGroupBox);
    ... save stream somewhere ...
  finally
    AStream.Free;
  end;
end;

Reading a component from a stream

The unit LResources has a function for that:

 procedure ReadComponentFromBinaryStream(AStream: TStream;
   var RootComponent: TComponent; OnFindComponentClass: TFindComponentClassEvent; TheOwner: TComponent = nil);
  • AStream is the stream containing a component in binary format.
  • RootComponent is either an existing component, which data will be overwritten, or it is nil and a new component will be created.
  • OnFindComponentClass is a function, that is used by TReader to get the class from the classnames in the stream. For example:
procedure TCompStreamDemoForm.OnFindClass(Reader: TReader;
  const AClassName: string; var ComponentClass: TComponentClass);
begin
  if CompareText(AClassName,'TGroupBox')=0 then
    ComponentClass:=TGroupBox
  else if CompareText(AClassName,'TCheckBox')=0 then
    ComponentClass:=TCheckBox;
end;
  • TheOwner is the component owner, when creating a new component.

Streamable properties

There are some limitations, what types TReader/TWriter can stream:

  • Base types can be streamed: string, integer, char, single, double, extended, byte, word, cardinal, shortint, method pointers, etc. .
  • TPersistent and descendants can be streamed

Streaming custom Data - DefineProperties

You can stream additinal arbitrary data by overriding DefineProperties. This allows to stream all data, that have no base types. For example to stream a variable ARect: TRect of your component, override DefineProperties with:

You can stream additinal arbitrary data by overriding DefineProperties. This allows to stream all data, that have no base types. For example to stream a variable FMyRect: TRect of your component, add the following three methods to your component:

procedure DefineProperties(Filer: TFiler); override;
procedure ReadMyRect(Reader: TReader);
procedure WriteMyRect(Writer: TWriter);
<pre>

With the following code:

<pre>
procedure TRPWorldPropertiesMessage.DefineProperties(Filer: TFiler);
var
  MyRectMustBeSaved: Boolean;
begin
  inherited DefineProperties(Filer);
  MyRectMustBeSaved:=(MyRect.Left<>0)
                     or (MyRect.Top<>0)
                     or (MyRect.Right<>0)
                     or (MyRect.Bottom<>0);
  Filer.DefineProperty('MyRect',@ReadMyRect,@WriteMyRect,MyRectMustBeSaved);
end;

procedure TRPWorldPropertiesMessage.ReadMyRect(Reader: TReader);
begin
  with Reader do begin
    ReadListBegin;
    FMyRect.Left:=ReadInteger;
    FMyRect.Top:=ReadInteger;
    FMyRect.Right:=ReadInteger;
    FMyRect.Bottom:=ReadInteger;
    ReadListEnd;
  end;
end;

procedure TRPWorldPropertiesMessage.WriteMyRect(Writer: TWriter);
begin
  with Writer do begin
    WriteListBegin;
    WriteInteger(FMyRect.Left);
    WriteInteger(FMyRect.Top);
    WriteInteger(FMyRect.Right);
    WriteInteger(FMyRect.Bottom);
    WriteListEnd;
  end;
end;