Skip to main content

​
Overview

TeeGrid is built on a flexible, framework-agnostic architecture that separates the visual grid component from its data source. This design allows TeeGrid to work seamlessly across VCL, FireMonkey, and Lazarus frameworks.

​
Core Architecture

The TeeGrid architecture consists of three main layers:

​
TCustomTeeGrid: The Core Class

TCustomTeeGrid is the abstract base class that defines all grid functionality. It’s located in Tee.Grid.pas and serves as the foundation for framework-specific implementations.

​
Key Properties

​
Data
TVirtualData
The data source for the grid. This property connects your data to the grid through the virtual data abstraction layer.
​
Columns
TColumns
Collection of grid columns that define the structure and appearance of your data.
​
Rows
TRows
Controls row rendering, including height, spacing, alternating colors, and cell hover effects.
​
Root
TRowGroup
The main row group that manages the primary data display and potential hierarchical sub-groups.
​
Selected
TGridSelection
Manages cell selection state, including single cell and range selection.

​
Component Hierarchy

The grid is composed of several key components:
TRowGroup manages a set of rows with associated data and columns. It supports:
  • Main data display through the Root property
  • Hierarchical data with expandable sub-groups
  • Independent scrolling and selection within each group
TIndicator is a special column that appears on the left side:
  • Shows current row selection with a triangle symbol
  • Displays edit/insert state
  • Configurable width through Indicator.Width property

​
Framework-Specific Implementations

TeeGrid provides concrete implementations for different frameworks:

​
VCL: VCLTee.Grid

uses VCLTee.Grid;

var
  Grid: TTeeGrid;
begin
  Grid := TTeeGrid.Create(Self);
  Grid.Parent := Self;
  // VCL-specific properties and behavior
end;

​
FireMonkey: FMXTee.Grid

uses FMXTee.Grid;

var
  Grid: TTeeGrid;
begin
  Grid := TTeeGrid.Create(Self);
  Grid.Parent := Self;
  // FMX-specific properties and behavior
end;

​
Lazarus: LCLTee.Grid

uses LCLTee.Grid;

var
  Grid: TTeeGrid;
begin
  Grid := TTeeGrid.Create(Self);
  Grid.Parent := Self;
  // LCL-specific properties and behavior
end;

​
Rendering Pipeline

The grid uses an abstract painting system through the TPainter class, which provides framework-agnostic drawing operations:
1

Layout Calculation

The grid calculates column widths, row heights, and positions for all visible elements.
2

Band Rendering

Header and footer bands are rendered first, establishing the available space for rows.
3

Row Rendering

Visible rows are painted using the TRows component, which:
  • Applies alternating row colors if configured
  • Renders each cell using the column’s render settings
  • Highlights selected cells
  • Shows hover effects
4

Custom Painting

Custom renderers and event handlers can override default painting behavior at the column or cell level.

​
Data Flow

Understanding how data flows through TeeGrid is crucial:

​
Key Design Patterns

​
Abstract Data Pattern

TeeGrid uses the TVirtualData abstract class to decouple the grid from specific data sources. This enables:
  • Support for any data source through custom implementations
  • Lazy data loading for large datasets
  • Virtual mode with on-demand cell value retrieval

​
Component-Based Rendering

All visual elements inherit from TRender, providing:
  • Consistent formatting through TFormat (brush, stroke, font)
  • Custom painting via render classes
  • Reusable visual components across different grid parts

​
Event-Driven Updates

The grid uses event notifications to stay synchronized:
  • OnRefresh: Data source structure changed
  • OnRepaint: Visual update needed
  • OnChangeRow: Current row changed
  • OnEditing: Edit mode started/stopped

​
State Management

TeeGrid maintains several state properties:

Selection State

  • Current column and row
  • Selection range (if enabled)
  • Unfocused selection appearance

Editing State

  • Active editor control
  • Edit mode (insert/edit)
  • Modified cell values

Scroll State

  • Horizontal scroll position
  • Vertical scroll position
  • First visible row index

Layout State

  • Calculated column positions
  • Row heights (if custom)
  • Expanded/collapsed groups

​
Thread Safety and Updates

TeeGrid is not thread-safe. All grid operations must occur on the main UI thread. Use thread synchronization when updating grid data from background threads.
To refresh the grid after data changes: 
// Refresh the entire grid
TeeGrid1.RefreshData;

// Repaint without reloading data
TeeGrid1.Invalidate;

​
Memory Management

TeeGrid follows standard Delphi component ownership rules. The grid owns its columns, bands, and internal objects. When you assign a TVirtualData instance, set its ownership appropriately.
var
  MyData: TVirtualDBData;
begin
  MyData := TVirtualDBData.From(DataSource1);
  TeeGrid1.Data := MyData;
  // MyData is now owned by TeeGrid1
end;

​
Next Steps

Data Binding

Learn how to connect your data to TeeGrid

Column System

Understand the column hierarchy and configuration

Virtual Data

Deep dive into the data abstraction layer

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us