TColumns

Collection class that manages TColumn instances in a TeeGrid

Overview

TColumns is a collection class that manages TColumn instances. It provides methods for adding, accessing, and organizing columns, and includes a Spacing property to control horizontal separation between columns.

Key Properties

Items[Index] · TColumn

Access columns by numeric index.

var
  Col: TColumn;
begin
  Col := Grid.Columns[0]; // First column
end;

Items[Name] · TColumn

Access columns by name (header text).

var
  Col: TColumn;
begin
  Col := Grid.Columns['Customer Name'];
end;

This property is not available in Free Pascal (FPC).

Spacing · TCoordinate

Horizontal separation between columns in pixels. Controls the gap between adjacent columns.

Grid.Columns.Spacing.Value := 5; // 5 pixels between columns

Parent · TColumn

Returns the parent column if this is a sub-columns collection, or nil if this is a top-level columns collection.

Key Methods

Add · TColumn

Creates and adds a new column to the collection.

var
  Col: TColumn;
begin
  Col := Grid.Columns.Add; // Add empty column
end;

Add(AText) · TColumn

Creates and adds a new column with the specified header text.

var
  Col: TColumn;
begin
  Col := Grid.Columns.Add('Product Name');
end;

FindAt(X, MaxRight) · TColumn

Returns the column at the specified X coordinate, or nil if no column is found.

var
  Col: TColumn;
begin
  Col := Grid.Columns.FindAt(100, Grid.Width);
  if Assigned(Col) then
    ShowMessage('Column: ' + Col.Header.Text);
end;

FindFirst(AName) · TColumn

Finds the first column with the specified name (case-insensitive search).

var
  Col: TColumn;
begin
  Col := Grid.Columns.FindFirst('customer');
end;

FirstVisible · TColumn

Returns the first visible column in the collection.

var
  Col: TColumn;
begin
  Col := Grid.Columns.FirstVisible;
end;

LevelCount · Integer

Returns the maximum hierarchical depth of columns. Returns 1 for flat columns, 2 if any column has sub-columns, etc.

var
  Depth: Integer;
begin
  Depth := Grid.Columns.LevelCount;
end;

HasSpacing · Boolean

Returns true if column spacing is greater than zero.

Events

OnMoved · TColumnMovedEvent

Event triggered when a column is moved from one position to another.

procedure TForm1.ColumnsMoved(const AColumn: TColumn; 
  const AOld, ANew: Integer);
begin
  ShowMessage(Format('Column "%s" moved from %d to %d',
    [AColumn.Header.Text, AOld, ANew]));
end;

// Assign event
Grid.Columns.OnMoved := ColumnsMoved;

Usage Examples

Adding Columns

begin
  // Add multiple columns
  Grid.Columns.Add('ID');
  Grid.Columns.Add('Name');
  Grid.Columns.Add('Email');
  Grid.Columns.Add('Phone');
  
  // Configure spacing
  Grid.Columns.Spacing.Value := 10;
end;

Accessing Columns

var
  Col: TColumn;
  i: Integer;
begin
  // Access by index
  Col := Grid.Columns[0];
  Col.Width.Value := 100;
  
  // Access by name
  Col := Grid.Columns['Name'];
  Col.ReadOnly := True;
  
  // Iterate through all columns
  for i := 0 to Grid.Columns.Count - 1 do
  begin
    Col := Grid.Columns[i];
    // Process column
  end;
end;

Hierarchical Columns

var
  ParentCol: TColumn;
begin
  // Create parent column with sub-columns
  ParentCol := Grid.Columns.Add('Full Name');
  ParentCol.Items.Add('First Name');
  ParentCol.Items.Add('Last Name');
  
  ParentCol := Grid.Columns.Add('Address');
  ParentCol.Items.Add('Street');
  ParentCol.Items.Add('City');
  ParentCol.Items.Add('Zip Code');
  
  // Check hierarchical depth
  ShowMessage('Column levels: ' + IntToStr(Grid.Columns.LevelCount));
end;

Finding Columns

var
  Col: TColumn;
begin
  // Find by name (case-insensitive)
  Col := Grid.Columns.FindFirst('customer');
  if Assigned(Col) then
    Col.Visible := False;
  
  // Get first visible column
  Col := Grid.Columns.FirstVisible;
  if Assigned(Col) then
    ShowMessage('First visible: ' + Col.Header.Text);
end;

Column Spacing

begin
  // Set column spacing
  Grid.Columns.Spacing.Value := 5;
  
  // Check if spacing is enabled
  if Grid.Columns.HasSpacing then
    ShowMessage('Columns have spacing');
end;

Design-Time Support

The TColumns class includes internal support for design-time column editing through the OnGetFields and OnSetField events. These are used by the IDE’s column editor dialog.

Related Classes

• TColumn - Individual column class
• TRows - Grid rows class
• TRowGroup - Row group with columns