String-Based Grids

Overview

TeeGrid provides two classes for string-based grid data, similar to VCL’s TStringGrid:

TStringsData: Maintains an internal 2D array of strings (like TStringGrid)
TVirtualModeData: Virtual mode with events for custom data storage

Both provide a simple column × row grid without complex data binding.

TStringsData: String Array Storage

TStringsData stores cell values in memory, perfect for replacing TStringGrid:

uses Tee.GridData.Strings;

var
  Data: TStringsData;
  Row: Integer;
begin
  // Create grid: 5 columns × 100,000 rows
  Data := TStringsData.Create(5, 100000);
  
  // Set column headers
  Data.Headers[0] := 'Column A';
  Data.Headers[1] := 'Column B';
  Data.Headers[2] := 'Column C';
  
  // Fill cells
  for Row := 0 to Data.Rows - 1 do
  begin
    Data[0, Row] := 'A' + IntToStr(Row);
    Data[1, Row] := 'B' + IntToStr(Row);
    Data[2, Row] := 'C' + IntToStr(Row);
  end;
  
  // Assign to grid
  TeeGrid1.Data := Data;
end;

TStringsData uses the default property Cells[Column, Row] so you can use array syntax: Data[Col, Row]

Creating and Resizing

Multiple ways to initialize grid size:

var
  Data: TStringsData;
begin
  // Option 1: Specify size in constructor
  Data := TStringsData.Create(10, 1000);
  
  // Option 2: Create empty, then set size
  Data := TStringsData.Create;
  Data.Columns := 10;
  Data.Rows := 1000;
  
  // Option 3: Use Resize method
  Data := TStringsData.Create;
  Data.Resize(10, 1000);
  
  TeeGrid1.Data := Data;
end;

Working with Cells

Access and modify cell values:

var
  Data: TStringsData;
  Value: String;
begin
  Data := TStringsData.Create(5, 10);
  
  // Set cell value
  Data[2, 3] := 'Hello';
  Data.Cells[2, 3] := 'World';
  
  // Get cell value
  Value := Data[2, 3];
  
  // Multi-line text (line breaks supported)
  Data[1, 5] := 'Line 1' + #13#10 + 'Line 2';
  
  TeeGrid1.Data := Data;
end;

TeeGrid automatically handles multi-line text. Enable TeeGrid1.Rows.Height.Automatic := True to adjust row heights dynamically.

Column Headers

Set custom header text for each column:

var
  Data: TStringsData;
begin
  Data := TStringsData.Create(3, 100);
  
  // Set headers
  Data.Headers[0] := 'Name';
  Data.Headers[1] := 'Age';
  Data.Headers[2] := 'City';
  
  // Multi-line headers
  Data.Headers[0] := 'Customer' + #13#10 + 'Name';
  
  TeeGrid1.Data := Data;
end;

Performance Optimization

For large grids (millions of cells), optimize rendering:

var
  Data: TStringsData;
begin
  // Pass default column width to skip auto-calculation (much faster)
  Data := TStringsData.Create(1000, 100000, 60);  // 60 pixels default width
  
  // Alternatively, disable auto-width after creation
  Data := TStringsData.Create(1000, 100000);
  TeeGrid1.Columns.AutoWidth := False;
  TeeGrid1.Columns.DefaultWidth := 60;
  
  TeeGrid1.Data := Data;
end;

Speed Tips for Large Grids

When displaying huge grids (1000 × 100,000 = 100 million cells):

Disable alternating row colors: TeeGrid1.Rows.Alternate.Hide
Disable header gradients: TeeGrid1.Header.Format.Brush.Gradient.Hide
Hide scrollbars if not needed: TeeGrid1.ScrollBars.Visible := False
Use fixed row height: TeeGrid1.Rows.Height.Value := 24
Provide default column width in constructor

TVirtualModeData: Event-Driven

TVirtualModeData doesn’t store data internally — you provide values through events:

uses Tee.GridData.Strings;

type
  TMyForm = class(TForm)
    TeeGrid1: TTeeGrid;
    procedure FormCreate(Sender: TObject);
  private
    Data: TVirtualModeData;
    procedure GetCell(Sender: TObject; const AColumn: TColumn;
      const ARow: Integer; var AValue: String);
    procedure SetCell(Sender: TObject; const AColumn: TColumn;
      const ARow: Integer; var AValue: String);
  end;

implementation

procedure TMyForm.FormCreate(Sender: TObject);
var
  t: Integer;
begin
  // Create virtual grid: 10 columns × 20,000 rows × 60px width
  Data := TVirtualModeData.Create(10, 20000, 60);
  
  // Set column headers
  for t := 0 to Data.Columns - 1 do
    Data.Headers[t] := 'Col ' + IntToStr(t);
  
  // Assign event handlers
  Data.OnGetValue := GetCell;
  Data.OnSetValue := SetCell;
  
  // Assign to grid
  TeeGrid1.Data := Data;
end;

procedure TMyForm.GetCell(Sender: TObject; const AColumn: TColumn;
  const ARow: Integer; var AValue: String);
begin
  // Return value from your data source
  // In this example, just calculate a string
  AValue := IntToStr(Data.IndexOf(AColumn)) + ' × ' + IntToStr(ARow);
end;

procedure TMyForm.SetCell(Sender: TObject; const AColumn: TColumn;
  const ARow: Integer; var AValue: String);
begin
  // Store the new value in your data source
  // Called when user edits a cell
end;

Virtual Mode Benefits: No memory overhead for cell storage. Perfect for computed values, database-backed data, or grids with billions of cells.

Real-World Example

Complete TStringGrid replacement example:

unit Unit_StringGrid;

interface

uses
  System.SysUtils, System.Classes,
  Vcl.Forms, Vcl.Controls, Vcl.StdCtrls, Vcl.ExtCtrls,
  VCLTee.Grid, Tee.GridData.Strings;

type
  TStringGridForm = class(TForm)
    TeeGrid1: TTeeGrid;
    Panel1: TPanel;
    EColumns: TEdit;
    ERows: TEdit;
    Button1: TButton;
    procedure FormCreate(Sender: TObject);
    procedure FormDestroy(Sender: TObject);
    procedure EColumnsChange(Sender: TObject);
    procedure ERowsChange(Sender: TObject);
    procedure TeeGrid1Select(Sender: TObject);
  private
    Data: TStringsData;
  end;

implementation

procedure TStringGridForm.FormCreate(Sender: TObject);
var
  Row: Integer;
begin
  // Create grid data
  Data := TStringsData.Create(1000, 100000, 60);
  
  // Set headers
  Data.Headers[0] := 'A' + #13#10 + 'Text';
  Data.Headers[1] := 'B';
  Data.Headers[2] := 'C';
  Data.Headers[3] := 'Status';
  
  // Fill cells
  for Row := 0 to Data.Rows - 1 do
  begin
    Data[0, Row] := 'A' + IntToStr(Row);
    Data[1, Row] := 'B' + IntToStr(Row);
    Data[2, Row] := 'C' + IntToStr(Row);
    
    if Random(100) < 30 then
      Data[3, Row] := 'OK';
  end;
  
  // Multi-line cell
  Data[2, 4] := Data[2, 4] + #13#10 + 'This is a long line';
  
  // Assign to grid
  TeeGrid1.Data := Data;
  
  // Set default row height
  TeeGrid1.Rows.Height.Value := 32;
  
  // Update UI
  EColumns.Text := IntToStr(Data.Columns);
  ERows.Text := IntToStr(Data.Rows);
end;

procedure TStringGridForm.FormDestroy(Sender: TObject);
begin
  // TeeGrid owns the Data object, but it's good practice to nil the reference
  Data := nil;
end;

procedure TStringGridForm.EColumnsChange(Sender: TObject);
var
  NewCols: Integer;
begin
  if TryStrToInt(EColumns.Text, NewCols) then
  begin
    TStringsData(TeeGrid1.Data).Columns := NewCols;
    TeeGrid1.Invalidate;
  end;
end;

procedure TStringGridForm.ERowsChange(Sender: TObject);
var
  NewRows: Integer;
begin
  if TryStrToInt(ERows.Text, NewRows) then
  begin
    TStringsData(TeeGrid1.Data).Rows := NewRows;
    TeeGrid1.Invalidate;
  end;
end;

procedure TStringGridForm.TeeGrid1Select(Sender: TObject);
var
  Sel: TGridSelection;
begin
  Sel := TeeGrid1.Grid.Current.Selected;
  
  if not Sel.IsEmpty then
    Panel1.Caption := Format('Selected: %s, Row: %d, Value: %s',
      [Sel.Column.Header.Text, Sel.Row,
       TeeGrid1.Grid.Current.Data.AsString(Sel.Column, Sel.Row)]);
end;

end.

Custom Cell Rendering

Override cell painting for custom display:

uses Tee.Painter, Tee.Renders;

procedure TMyForm.FormCreate(Sender: TObject);
begin
  Data := TStringsData.Create(5, 100);
  TeeGrid1.Data := Data;
  
  // Custom paint for column 3
  TeeGrid1.Columns[3].OnPaint := PaintStatusColumn;
end;

procedure TMyForm.PaintStatusColumn(
  const Sender: TColumn;
  var AData: TRenderData;
  var DefaultPaint: Boolean
);
var
  CellRect: TRectF;
begin
  // Custom rendering for "OK" cells
  if SameText(AData.Data, 'OK') then
  begin
    DefaultPaint := False;  // Skip default text rendering
    
    CellRect := AData.Bounds;
    CellRect.Inflate(-8, -6);
    
    // Draw custom content (e.g., an image)
    AData.Painter.Draw(OkPicture, CellRect);
  end
  else
    DefaultPaint := True;  // Use default rendering
end;

Cell Formatting

Apply custom formatting to specific cells:

uses Tee.Format, System.UIConsts;

procedure TMyForm.FormCreate(Sender: TObject);
var
  Row: TRow;
begin
  Data := TStringsData.Create(5, 100);
  TeeGrid1.Data := Data;
  
  // Format entire row
  Row := TeeGrid1.Rows.Items.AddRow(7);
  Row.Format.Brush.Color := TColors.Red;
  Row.Format.Font.Color := claWhite;
  Row.Format.Brush.Show;
  
  // Format individual cell
  TeeGrid1.CellFormat.AddCell(3, 4);
  TeeGrid1.CellFormat.Cell[3, 4].Format.Brush.Color := TColors.Green;
  TeeGrid1.CellFormat.Cell[3, 4].Format.Font.Color := claYellow;
  TeeGrid1.CellFormat.Cell[3, 4].Format.Brush.Show;
end;

Sub-Bands (Grouping Rows)

Insert separator bands between rows:

uses Tee.Grid.Bands;

procedure TMyForm.FormCreate(Sender: TObject);
var
  Title: TTextBand;
begin
  Data := TStringsData.Create(5, 100);
  TeeGrid1.Data := Data;
  
  // Insert a sub-band at row 20
  Title := TTextBand.Create(TeeGrid1.Rows.SubBands);
  Title.Text := 'Section Title' + #13#10 + 'Subtitle';
  Title.Format.Font.Style := [fsBold];
  Title.Format.Brush.Show;
  Title.Format.Brush.Color := TColors.LightBlue;
  
  TeeGrid1.Rows.SubBands.Row[20] := Title;
end;

Comparison: TStringsData vs TVirtualModeData

Feature	TStringsData	TVirtualModeData
Storage	Internal 2D string array	Event-driven, no storage
Memory	O(columns × rows)	O(1)
Performance	Fast for small/medium grids	Fast for any size
Use Case	Direct TStringGrid replacement	Computed values, external data
Editing	Built-in cell storage	You handle storage in events

Common Patterns

CSV Import

Import CSV data into TStringsData:

procedure LoadCSV(const FileName: String; Data: TStringsData);
var
  CSV: TStringList;
  Row, Col: Integer;
  Values: TArray<String>;
begin
  CSV := TStringList.Create;
  try
    CSV.LoadFromFile(FileName);
    Data.Rows := CSV.Count;
    
    for Row := 0 to CSV.Count - 1 do
    begin
      Values := CSV[Row].Split([',']);
      
      if Length(Values) > Data.Columns then
        Data.Columns := Length(Values);
      
      for Col := 0 to High(Values) do
        Data[Col, Row] := Values[Col];
    end;
  finally
    CSV.Free;
  end;
end;

Formula Calculation

Use TVirtualModeData for spreadsheet-like formulas:

procedure TMyForm.GetCell(Sender: TObject; const AColumn: TColumn;
  const ARow: Integer; var AValue: String);
var
  ColIndex: Integer;
begin
  ColIndex := Data.IndexOf(AColumn);
  
  // First column: row numbers
  if ColIndex = 0 then
    AValue := IntToStr(ARow + 1)
  // Sum column: calculate sum
  else if ColIndex = 5 then
    AValue := FloatToStr(CalculateRowSum(ARow))
  else
    AValue := FDataArray[ColIndex, ARow];
end;

Search Highlight

Highlight search results:

procedure TMyForm.SearchAndHighlight(const SearchText: String);
var
  Row, Col: Integer;
begin
  for Row := 0 to Data.Rows - 1 do
    for Col := 0 to Data.Columns - 1 do
      if Pos(SearchText, Data[Col, Row]) > 0 then
      begin
        TeeGrid1.CellFormat.AddCell(Col, Row);
        TeeGrid1.CellFormat.Cell[Col, Row].Format.Brush.Color := TColors.Yellow;
        TeeGrid1.CellFormat.Cell[Col, Row].Format.Brush.Show;
      end;
end;

Next Steps

DataSet Binding

Connect to TDataSet and TDataSource

Arrays and Lists

Bind TArray<T> and TList<T> using RTTI

Custom Data

Create custom TVirtualData implementations

Rendering API

Customize cell appearance and painting

Get Started

Core Concepts

Data Sources

Features

UI Customization

Framework Integration

String-Based Grids

Overview

TStringsData: String Array Storage

Creating and Resizing

Working with Cells

Column Headers

Performance Optimization

TVirtualModeData: Event-Driven

Real-World Example

Custom Cell Rendering

Cell Formatting

Sub-Bands (Grouping Rows)

Comparison: TStringsData vs TVirtualModeData

Common Patterns

Next Steps

DataSet Binding

Arrays and Lists

Custom Data

Rendering API

Build docs developers (and LLMs) love

Get Started

Core Concepts

Data Sources

Features

UI Customization

Framework Integration

​Overview

​TStringsData: String Array Storage

​Creating and Resizing

​Working with Cells

​Column Headers

​Performance Optimization

​TVirtualModeData: Event-Driven

​Real-World Example

​Custom Cell Rendering

​Cell Formatting

​Sub-Bands (Grouping Rows)

​Comparison: TStringsData vs TVirtualModeData

​Common Patterns

​Next Steps

DataSet Binding

Arrays and Lists

Custom Data

Rendering API

Build docs developers (and LLMs) love

Overview

TStringsData: String Array Storage

Creating and Resizing

Working with Cells

Column Headers

Performance Optimization

TVirtualModeData: Event-Driven

Real-World Example

Custom Cell Rendering

Cell Formatting

Sub-Bands (Grouping Rows)

Comparison: TStringsData vs TVirtualModeData

Common Patterns

Next Steps