TTeeGrid

Main grid component for displaying and editing tabular data

Overview

TTeeGrid is the main grid component available for both VCL and FireMonkey (FMX) frameworks. It provides a high-performance, feature-rich interface for displaying and editing tabular data with support for columns, rows, headers, footers, and cell editing.

TTeeGrid is implemented separately for VCL (VCLTee.Grid) and FMX (FMXTee.Grid), but both share the same core properties and methods through the base TCustomTeeGrid class.

Properties

Data and Display

Data · TVirtualData

The data source for the grid. Assign an instance of TVirtualData or its descendants (TDataSource, TArray<T>, TList<T>, etc.) to populate the grid with data.

Columns · TColumns

Collection of grid columns that define the structure and appearance of data columns. Each column can have custom formatting, width, alignment, and editor settings.

Rows · TRows

Configuration for grid rows including height, alternating colors, and row selection settings.

DataSource · TComponent

Direct link to a TDataSource component for database connectivity. Alternative to using the Data property.

Visual Elements

Back · TFormat

Background formatting for the grid including color, gradient, stroke, and shadow settings.

Cells · TTextRender

Formatting and rendering settings for grid cells including font, alignment, padding, and text appearance.

Header · TColumnHeaderBand

Configuration for the column header band including visibility, height, text formatting, and sorting indicators.

Headers · TGridBands

Collection of additional header bands that can be displayed above the grid.

Footer · TGridBands

Collection of footer bands that can be displayed below the grid for totals, summaries, or additional information.

Indicator · TIndicator

Settings for the row indicator column that shows the current row and editing state.

Behavior

ReadOnly · Boolean · default: "True"

When True, prevents editing of grid cells. Set to False to allow cell editing.

Editing · TGridEditing

Configuration for cell editing behavior including auto-edit mode, double-click editing, and Enter key behavior.

Selected · TGridSelection

The currently selected cell, row, or range in the grid. Use this to programmatically control or read the selection.

Scrolling · TGridScrolling

Settings for grid scrolling behavior including scroll mode and smooth scrolling options.

Painter · TPainter

The painter implementation used to render the grid. Can be GDI, GDI+, or other custom painters.

Events

Cell Events

OnCellEditing · TCellEditingEvent

Fired when a cell editor is about to be displayed. Use this event to customize the editor control.

Signature:

procedure(const Sender: TObject; const AEditor: TControl;
         const AColumn: TColumn; const ARow: Integer) of object;

OnCellEdited · TCellEditedEvent

Fired when cell editing is complete. Allows validation and modification of the new data before it’s saved.

Signature:

procedure(const Sender: TObject; const AEditor: TControl;
         const AColumn: TColumn; const ARow: Integer;
         var ChangeData: Boolean; var NewData: String) of object;

Selection Events

OnSelect · TNotifyEvent

Fired when the grid selection changes (cell or row selection).

Column Events

OnClickedHeader · TNotifyEvent

Fired when a column header is clicked, typically used for sorting.

OnColumnResized · TColumnEvent

Fired after a column has been resized by the user.

Signature:

procedure(Sender: TObject; const AColumn: TColumn) of object;

Detail Events

OnNewDetail · TNewDetailEvent

Fired when a detail (sub-grid) is about to be created for a master-detail relationship.

Signature:

procedure(Sender: TObject; const ARow: Integer;
         var Detail: TVirtualData) of object;

Drawing Events

OnAfterDraw · TNotifyEvent

Fired after the grid has been painted. Use for custom drawing operations.

Public Methods

Assign · procedure

Copies properties from another TPersistent object.

Signature:

procedure Assign(Source: TPersistent);

DoChanged · procedure

Triggers a repaint of the grid. Call this when you programmatically change grid properties.

Signature:

procedure DoChanged(Sender: TObject);

VCL Only

Changed · procedure

Triggers a repaint of the grid. Call this when you programmatically change grid properties.

Signature:

procedure Changed(Sender: TObject);

FMX Only

Example Usage

Basic Grid Setup

var
  Grid: TTeeGrid;
  Data: TVirtualDBData;
begin
  Grid := TTeeGrid.Create(Self);
  Grid.Parent := Self;
  Grid.Align := alClient;
  
  // Configure appearance
  Grid.ReadOnly := False;
  Grid.Header.Visible := True;
  Grid.Indicator.Visible := True;
  
  // Connect to data
  Data := TVirtualDBData.Create;
  Data.DataSource := DataSource1;
  Grid.Data := Data;
end;

Handling Cell Editing

procedure TForm1.TeeGrid1CellEdited(const Sender: TObject;
  const AEditor: TControl; const AColumn: TColumn; const ARow: Integer;
  var ChangeData: Boolean; var NewData: String);
begin
  // Validate the new data
  if (AColumn.Name = 'Age') and (StrToIntDef(NewData, 0) < 18) then
  begin
    ShowMessage('Age must be 18 or older');
    ChangeData := False; // Cancel the change
  end;
end;

Master-Detail Configuration

procedure TForm1.TeeGrid1NewDetail(Sender: TObject; const ARow: Integer;
  var Detail: TVirtualData);
var
  DetailData: TVirtualDBData;
begin
  DetailData := TVirtualDBData.Create;
  DetailData.DataSource := DetailDataSource;
  Detail := DetailData;
end;

Platform Differences

VCL

• Uses GDI/GDI+ for rendering
• Property: Canvas - Direct access to TControlCanvas
• Method: DoChanged - Trigger repaint
• Built-in scrollbar support via TScrollableControl

FireMonkey

• Cross-platform rendering
• Method: Changed - Trigger repaint
• Touch and gesture support
• Supports multiple platforms (Windows, macOS, iOS, Android)

See Also

TCustomTeeGrid

Base class with core grid architecture

TVirtualData

Abstract data interface for grid data sources