Column System - TeeGrid

Overview

TeeGrid’s column system is built on a hierarchical model where columns can contain sub-columns, enabling sophisticated layouts like grouped headers and multi-level column organization.

TColumn Class

The TColumn class (defined in Tee.Grid.Columns.pas) represents a single column in the grid.

Core Properties

Header

TColumnHeader

Configures the column header display:

Text: Header caption
ParentFormat: Inherit formatting from parent
TextAlignment: Automatic or custom alignment
Format: Brush, stroke, font, and margins

Width

TColumnWidth

Column width configuration:

Automatic: Auto-size based on content
Value: Fixed pixel width
Percent: Percentage of available width (e.g., 25 for 25%)

Items

TColumns

Collection of sub-columns for hierarchical layouts. When a column has items, it acts as a container/group for its children.

Expanded

Boolean

default:"True"

Controls visibility of sub-columns. When False, child columns are hidden.

Visible

Boolean

default:"True"

Controls column visibility. Hidden columns don’t render or occupy space.

ReadOnly

Boolean

default:"False"

Prevents editing for this column. Users can select but not modify cell values.

Selectable

Boolean

default:"True"

Controls whether cells in this column can be selected.

Formatting Properties

Format

TFormat

Visual formatting:

Brush: Background fill
Stroke: Border and lines
Font: Text appearance

DataFormat

TDataFormat

Data-specific formatting:

Float: Number format string (default: “0.###”)
Date: Date format string
DateTime: DateTime format string
Time: Time format string

TextAlign

TTextAlign

Horizontal and vertical text alignment within cells:

Column.TextAlign.Horizontal := THorizontalAlign.Center;
Column.TextAlign.Vertical := TVerticalAlign.Center;

TextAlignment

TColumnTextAlign

Automatic: Right-align numbers, left-align text
Custom: Use explicitly set TextAlign values

Margins

TMargins

Cell content padding (Left, Top, Right, Bottom).

Advanced Features

Render

TRender

Custom renderer for cell content. Override default text rendering with:

Progress bars
Images
Buttons
Charts
Custom graphics

Locked

TColumnLocked

Pin columns:

None: Normal scrolling
Left: Fixed on left side
Right: Fixed on right side

ParentFormat

Boolean

default:"True"

When True, inherits formatting from parent column (if nested) or grid cells.

TagObject

TObject

User-defined object reference. TeeGrid uses this internally to link columns to data fields/properties.

EditorClass

TClass

Custom editor control class for cell editing. Override default TEdit behavior.

TColumns Collection

The TColumns class manages a collection of TColumn objects.

Creating Columns

var
  Col: TColumn;
begin
  // Add empty column
  Col := TeeGrid1.Columns.Add;
  Col.Header.Text := 'Name';
  
  // Add with text
  Col := TeeGrid1.Columns.Add('Email');
end;

Column Spacing

// Set spacing between columns
TeeGrid1.Columns.Spacing.Value := 2; // 2 pixels between columns

Hierarchical Columns

TeeGrid supports nested columns for grouped headers and complex layouts:

var
  Group: TColumn;
begin
  // Create a parent column group
  Group := TeeGrid1.Columns.Add('Personal Info');
  
  // Add child columns
  Group.Items.Add('First Name');
  Group.Items.Add('Last Name');
  Group.Items.Add('Age');
  
  // Create another group
  Group := TeeGrid1.Columns.Add('Contact');
  Group.Items.Add('Email');
  Group.Items.Add('Phone');
  
  // Can nest multiple levels
  with Group.Items.Add('Address') do
  begin
    Items.Add('Street');
    Items.Add('City');
    Items.Add('ZIP');
  end;
end;

Visual Result:

┌────────────────────────────┬─────────────────────────────────────┐
│      Personal Info         │             Contact                 │
├──────────┬──────────┬──────┼──────────┬────────┬────────────────┤
│First Name│Last Name │  Age │  Email   │ Phone  │    Address     │
│          │          │      │          │        ├─────┬────┬─────┤
│          │          │      │          │        │Street│City│ ZIP │
├──────────┴──────────┴──────┴──────────┴────────┴─────┴────┴─────┤
│                         Data Rows...                              │

Working with Hierarchy

Expand/Collapse
Navigation
Level Information

// Collapse a column group (hides child columns)
TeeGrid1.Columns[0].Expanded := False;

// Expand it again
TeeGrid1.Columns[0].Expanded := True;

// Check if column has children
if TeeGrid1.Columns[0].HasItems then
  ShowMessage('This column has sub-columns');

var
  Col, ParentCol: TColumn;
begin
  Col := TeeGrid1.Columns[0].Items[1]; // Child column
  
  // Get parent column
  ParentCol := Col.Parent;
  
  // Get parent collection
  if Col.ParentColumns <> nil then
    ShowMessage('Parent collection count: ' + IntToStr(Col.ParentColumns.Count));
  
  // Get top-level parent
  if Col.TopParent <> nil then
    ShowMessage('Top-level parent');
end;

var
  Col: TColumn;
  Level: Integer;
begin
  Col := TeeGrid1.Columns[0].Items[0].Items[2];
  
  // Get nesting level (0 = top level)
  Level := Col.Level;
  
  // Get maximum level in entire grid
  Level := TeeGrid1.Columns.LevelCount;
end;

Column Width Management

TeeGrid provides flexible width calculation:

Automatic Width

// Auto-size based on content
Column.Width.Automatic := True;

// Grid calculates width by:
// 1. Measuring header text
// 2. Calling TVirtualData.AutoWidth() for content
// 3. Taking the maximum

Fixed Width

// Set explicit pixel width
Column.Width.Automatic := False;
Column.Width.Value := 150;

Percentage Width

// Use percentage of available width
Column.Width.Automatic := False;
Column.Width.Percent := 25; // 25% of grid width

Mixed Widths

// Combine different width types
TeeGrid1.Columns[0].Width.Value := 50;      // Fixed 50px
TeeGrid1.Columns[1].Width.Automatic := True; // Auto-size
TeeGrid1.Columns[2].Width.Percent := 30;    // 30% of remaining space
TeeGrid1.Columns[3].Width.Percent := 70;    // 70% of remaining space

Locked Columns

Freeze columns at the left or right edge:

// Lock first column (e.g., ID or Name)
TeeGrid1.Columns[0].Locked := TColumnLocked.Left;

// Lock last column (e.g., Total or Actions)
TeeGrid1.Columns[TeeGrid1.Columns.Count - 1].Locked := TColumnLocked.Right;

// Locked columns remain visible while others scroll horizontally

Custom Column Events

OnPaint Event

Customize cell painting on a per-column basis:

procedure TForm1.ColumnPaint(const Sender: TColumn; var AData: TRenderData; 
  var DefaultPaint: Boolean);
begin
  // Custom painting for this column
  if AData.Row mod 2 = 0 then
    AData.Painter.Fill(AData.Rect, TColors.LightGray);
  
  // Set DefaultPaint := False to skip default rendering
end;

begin
  TeeGrid1.Columns[2].OnPaint := ColumnPaint;
end;

Visible Columns

Internal helper class TVisibleColumns tracks currently visible columns:

// TeeGrid uses this internally to:
// - Determine which columns to render
// - Handle mouse hit testing
// - Calculate scrollbar ranges
// - Navigate with keyboard (Tab, arrow keys)

Indicator Column

Special column showing row state:

// Configure indicator
TeeGrid1.Indicator.Visible := True;
TeeGrid1.Indicator.Width.Value := 20;
TeeGrid1.Indicator.Format.Brush.Color := TColors.LightBlue;

// The indicator shows:
// - Triangle for current row
// - Different symbols for edit/insert state

Column Reordering

Columns can be moved programmatically:

var
  Col: TColumn;
begin
  // Move column from position 2 to position 0
  Col := TeeGrid1.Columns[2];
  Col.Index := 0;
  
  // Or swap two columns
  TeeGrid1.Columns[0].Index := 3; // Moves column 0 to position 3
end;

Data Type Alignment

Automatic alignment based on data types:

// When TextAlignment = Automatic (default):
// - Numbers: Right-aligned
// - Dates/Times: Center-aligned
// - Strings: Left-aligned
// - Booleans: Center-aligned

// Override for specific column:
Column.TextAlignment := TColumnTextAlign.Custom;
Column.TextAlign.Horizontal := THorizontalAlign.Center;

Column Iteration

var
  Column: TColumn;
  I: Integer;
begin
  // Simple iteration
  for I := 0 to TeeGrid1.Columns.Count - 1 do
  begin
    Column := TeeGrid1.Columns[I];
    // Process column
  end;
  
  // Include nested columns
  procedure ProcessColumns(Columns: TColumns);
  var
    I: Integer;
  begin
    for I := 0 to Columns.Count - 1 do
    begin
      // Process this column
      ShowMessage(Columns[I].Header.Text);
      
      // Recurse into children
      if Columns[I].HasItems then
        ProcessColumns(Columns[I].Items);
    end;
  end;
  
  ProcessColumns(TeeGrid1.Columns);
end;

Column Best Practices

Performance

Minimize custom painting in OnPaint - it’s called for every visible cell
Use ParentFormat := True when possible to reduce memory
Avoid complex calculations in data format strings

Usability

Use descriptive header text
Set appropriate column widths for content type
Consider locked columns for key fields
Make calculated/read-only columns obviously non-editable

Hierarchy

Limit nesting to 2-3 levels for readability
Use meaningful group names
Consider whether hierarchy adds value vs complexity

Formatting

Use consistent date/number formats across similar columns
Align numbers to the right for easy comparison
Apply data formats at column level, not in AsString()

Common Patterns

Calculated Column

var
  TotalCol: TColumn;
begin
  // Add calculated column
  TotalCol := TeeGrid1.Columns.Add('Total');
  TotalCol.ReadOnly := True;
  TotalCol.DataFormat.Float := '$0.00';
  
  // Calculation happens in TVirtualData.AsString()
end;

Image Column

uses Tee.Grid.Columns, Tee.Renders;

var
  ImageCol: TColumn;
begin
  ImageCol := TeeGrid1.Columns.Add('Photo');
  ImageCol.Render := TImageRender.Create(TeeGrid1);
  ImageCol.Width.Value := 100;
end;

Boolean Column (Checkboxes)

var
  BoolCol: TColumn;
begin
  BoolCol := TeeGrid1.Columns.Add('Active');
  // TeeGrid automatically renders booleans as checkboxes
  BoolCol.TextAlign.Horizontal := THorizontalAlign.Center;
end;

Next Steps

Custom Renderers

Create custom column rendering

Data Binding

Learn how columns connect to data

Locked Columns

Deep dive into column freezing

TColumn API

Complete API reference

Get Started

Core Concepts

Data Sources

Features

UI Customization

Framework Integration

​Overview

​TColumn Class

​Core Properties

​Formatting Properties

​Advanced Features

​TColumns Collection

​Creating Columns

​Column Spacing

​Hierarchical Columns

​Working with Hierarchy

​Column Width Management

​Automatic Width

​Fixed Width

​Percentage Width

​Mixed Widths

​Locked Columns

​Custom Column Events

​OnPaint Event

​Visible Columns

​Indicator Column

​Column Reordering

​Data Type Alignment

​Column Iteration

​Column Best Practices

​Common Patterns

​Calculated Column

​Image Column

​Boolean Column (Checkboxes)

​Next Steps

Custom Renderers

Data Binding

Locked Columns

TColumn API

Build docs developers (and LLMs) love

Overview

TColumn Class

Core Properties

Formatting Properties

Advanced Features

TColumns Collection

Creating Columns

Column Spacing

Hierarchical Columns

Working with Hierarchy

Column Width Management

Automatic Width

Fixed Width

Percentage Width

Mixed Widths

Locked Columns

Custom Column Events

OnPaint Event

Visible Columns

Indicator Column

Column Reordering

Data Type Alignment

Column Iteration

Column Best Practices

Common Patterns

Calculated Column

Image Column

Boolean Column (Checkboxes)

Next Steps