Collections

DFM-Translator > Special assignments > Collections

A collection-valued property is a special kind of DFM assignment. Its value is enclosed in angle brackets (< and >) and consists of one or more item blocks.

Each item block begins with the keyword item, contains the property assignments for one collection item, and ends with the keyword end.

The general structure is:

  object xxx1: Txxx

  ...

    yyys = <

      item

        zzz = ...

      end

      item

        zzz = ...

      end>

  end

Collections with an Add method

The Panels property of a status bar is an example of such a collection:

  object StatusBar: TStatusBar

    Left = 0

    Top = 132

    Width = 609

    Height = 19

    Panels = <

      item

        Width = 120

      end

      item

        Alignment = taCenter

        Width = 60

      end

      item

        Width = 50

      end>

  end                                    

By default, Delphi2C# translates this collection as follows:

      StatusBar = new TStatusBar(this);

      StatusBar.Parent = this;

      StatusBar.Left = 0;

      StatusBar.Top = 132;

      StatusBar.Width = 609;

      StatusBar.Height = 19;

      StatusBar.Panels.Add();

      StatusBar.Panels.Items[0].Width = 120;

      StatusBar.Panels.Add();

      StatusBar.Panels.Items[1].Alignment = TAlignment.taCenter;

      StatusBar.Panels.Items[1].Width = 60;

      StatusBar.Panels.Add();

      StatusBar.Panels.Items[2].Width = 50;                  ...                                                               

The calls to Add are necessary because each collection item must be created before values can be assigned to its properties.

Collections without an Add method

Not every collection provides an Add method. The FieldDefs property of TClientDataSet is an example:

  object ClientDataSet1: TClientDataSet

    Active = True

    Aggregates = <>

    FileName = 

      'C:\Users\Public\Documents\Embarcadero\Studio\22.0\Samples\Data\b' +

      'iolife.cds'

    FieldDefs = <

      item

        Name = 'Species No'

        DataType = ftFloat

      end

      item

        Name = 'Category'

        DataType = ftString

        Size = 15

      end>

  end

The generated code has a similar structure, but TFieldDefs cannot be handled in the same way as TStatusPanels because it has no Add method.

This case can be handled by a DFM conversion function:

ClientDataSet1 = new TClientDataSet(this); 

OnDataSetBegin(ClientDataSet1); 

ClientDataSet1.FileName = "C:\\Users\\Public\\Documents\\Embarcadero\\Studio\\22.0\\Samples\\Data\\biolife.cds"; 

GetTFieldDefsitem(ClientDataSet1.FieldDefs, 0).Name = "Species No"; 

GetTFieldDefsitem(ClientDataSet1.FieldDefs, 0).DataType = TFieldType.ftFloat; 

GetTFieldDefsitem(ClientDataSet1.FieldDefs, 1).Name = "Category"; 

GetTFieldDefsitem(ClientDataSet1.FieldDefs, 1).DataType = TFieldType.ftString; 

GetTFieldDefsitem(ClientDataSet1.FieldDefs, 1).Size = 15;

OnDataSetEnd(ClientDataSet1); 

The empty Aggregates collection does not contain any items and therefore requires no item assignments.

Getter functions for collection items

DFM conversion functions for collection items begin with the prefix Get. This is followed by the collection type and the word item.

For the two examples above, the corresponding functions are:

TStatusPanel GetTStatusPanelsitem(TStatusPanels xp, int xiIndex)

TFieldDef GetTFieldDefsitem(TFieldDefs xp, int xiIndex)

For example, GetTStatusPanelsitem can be implemented as follows:

public static TStatusPanel GetTStatusPanelsitem(TStatusPanels xp, int xiIndex)

{

    if (xp.Count == xiIndex)

        xp.Add();

    return xp.Items[xiIndex];

}

The function creates the requested item if necessary and then returns it. Delphi2C# can therefore generate assignments such as:

GetTStatusPanelsitem(StatusBar.Panels, 0).Width = 120;

GetTStatusPanelsitem(StatusBar.Panels, 1).Alignment = TAlignment.taCenter;

GetTStatusPanelsitem(StatusBar.Panels, 1).Width = 60;

GetTStatusPanelsitem(StatusBar.Panels, 2).Width = 50;

GetTFieldDefsitem follows the same principle, but uses AddFieldDef instead of Add to create a field definition.

Alternative getter names

The collection-based naming convention cannot be used for every component. For example, some collections used by TActionList do not expose a property that returns the complete collection. They provide access only to individual items by index.

For such cases, Delphi2C# also recognizes getter functions whose names are based on the type of the component that owns the collection.

The name may end with either:

For a TStatusBar, the following three naming schemes are equivalent:

TStatusPanel GetTStatusPanelsitem(TStatusPanels xp, int xiIndex)

TStatusPanel GetTStatusBarPanels(TStatusBar xp, int xiIndex)

TStatusPanel GetTStatusBaritem(TStatusBar xp, int xiIndex)

The first function receives the collection itself:

GetTStatusPanelsitem(StatusBar.Panels, 0).Width = 120;

The other two functions receive the component that owns the collection:

GetTStatusBarPanels(StatusBar, 1).Alignment = TAlignment.taCenter;

GetTStatusBaritem(StatusBar, 2).Width = 50;

The owner-based forms are particularly useful if Delphi2C# cannot determine the type of a collection property. This may happen if the source files are incomplete or if the property is not declared explicitly and is accessible only through DefineProperties.

This page belongs to the Delphi2C# Documentation