More of this Feature • Page 1: Component references • Page 2: Sets • Page 4: Collections • Page 5: Sub-properties • Download Demo Projects

Join the Discussion "Post your questions, concerns, views and comments to this article..." Discuss!

Related Resources • Custom VCL development • VCL with source • Third party VCL • VCL using

   Binary properties
Sometimes it is necessary to write your own streaming routines to read and write custom property types (This is how Delphi reads / writes the Top and Left properties for non visible components without actually publishing those properties in the object inspector).

For example, I once wrote a component to shape a form based on a bitmap image. My code at the time to convert a bitmap to a window-region was extremely slow and would not possibly be of any use at runtime. My solution was to convert the data at design time, and stream the binary data that resulted from the conversion. To create binary properties is a three step process.

1. Write a method to write the data.
2. Write a method to read the data.
3. Tell Delphi that we have a binary property, and pass our read / write methods.

type
  TBinaryComponent = class(TComponent)
  private
    FBinaryData : Pointer;
    FBinaryDataSize : DWord;
    procedure WriteData(S : TStream);
    procedure ReadData(S : TStream);
  protected
    procedure DefineProperties(Filer : TFiler); override;
  public
    constructor Create(AOwner : TComponent); override;
  end;

DefineProperties is called by Delphi when it needs to stream our component. All we need to do is to override this method, and add a property using either TFiler.DefineProperty or TFiler.DefineBinaryProperty.

procedure TFiler.DefineBinaryProperty(const Name: string;
  ReadData, WriteData: TStreamProc;
  HasData: Boolean); 
 
constructor TBinaryComponent.Create(AOwner: TComponent);
begin
  inherited;
  FBinaryDataSize := 0;
end;

procedure TBinaryComponent.DefineProperties(Filer: TFiler);
var
  HasData : Boolean;
begin
  inherited;
  HasData := FBinaryDataSize <> 0;
  Filer.DefineBinaryProperty('BinaryData',ReadData, 
    WriteData, HasData );
end;

procedure TBinaryComponent.ReadData(S: TStream);
begin
  S.Read(FBinaryDataSize, SizeOf(DWord));
  if FBinaryDataSize > 0 then begin
    GetMem(FBinaryData, FBinaryDataSize);
    S.Read(FBinaryData^, FBinaryDataSize);
  end;
end;

procedure TBinaryComponent.WriteData(S: TStream);
begin
  //This will not be called if FBinaryDataSize = 0

  S.Write(FBinaryDataSize, Sizeof(DWord));
  S.Write(FBinaryData^, FBinaryDataSize);
end;

Firstly we override DefineProperties. Once we have done this we define a binary property with the values
· BinaryData : The invisible property name to be used.
· ReadData : The procedure responsible for reading the data.
· WriteData : The procedure responsible for writing the data.
· HasData : If this is false, the WriteData procedure is not even called.

   Persistency
A quick explanation of persistency is in order as we shall refer to it in the following sections. Persistency is what makes it possible for Delphi to read and write the properties of all of its components. TComponent derives from a class called TPersistent. TPersistent is simply a Delphi class capable of having its properties read and written by Delphi, which means that any descendents of TPersistent also have this same capability.

Next page > Collections > Page 1, 2, 3, 4, 5

Creating Custom Delphi Components >>
>> Part III.