TCustomTeeGrid

Abstract base class for TeeGrid with core architecture and functionality

Overview

TCustomTeeGrid is the abstract base class for all TeeGrid implementations. It provides the core architecture, data management, and rendering framework that is shared between VCL and FireMonkey versions of TTeeGrid.

TCustomTeeGrid is an abstract class and cannot be instantiated directly. Use TTeeGrid (VCL or FMX) instead.

Architecture

TCustomTeeGrid serves as the foundation for the grid component hierarchy:

TCustomTeeControl (base control)
  └── TCustomTeeGrid (abstract grid)
      ├── TVCLTeeGrid (VCL implementation)
      │   └── TTeeGrid (VCL)
      └── TFMXTeeGrid (FMX implementation)
          └── TTeeGrid (FMX)

Core Properties

Data Management

Data · TVirtualData

The virtual data source providing content to the grid. This can be any descendant of TVirtualData including database sources, arrays, lists, or custom data providers.

DataSource · TComponent

Reference to a component that provides data, typically a TDataSource for database connectivity.

Root · TRowGroup

The main row group that contains all grid data. This is the top-level group in master-detail hierarchies.

Current · TRowGroup

The currently focused row group. In a simple grid, this is the same as Root. In master-detail grids, this represents the active detail level.

Visual Structure

Cells · TTextRender

Defines the rendering properties for grid cells including font, colors, alignment, and padding.

Columns · TColumns

The collection of columns defining the grid structure. Each column specifies how data is displayed and edited.

Rows · TRows

Row configuration including default height, alternating row colors, and row selection behavior.

Header · TColumnHeaderBand

The main column header band configuration.

Headers · TGridBands

Collection of additional header bands displayed above the grid.

Footer · TGridBands

Collection of footer bands displayed below the grid.

Indicator · TIndicator

Configuration for the row indicator column showing current row and edit state.

Margins · TMargins

Margins around the grid content area.

Editing

Editing · TGridEditing

Comprehensive editing configuration including:

• Active - Whether an editor is currently visible
• AlwaysVisible - Keep editor always visible
• AutoEdit - Start editing on keypress
• DoubleClick - Require double-click to edit
• EnterKey - Behavior when Enter is pressed (NextCell, NextRow, SameCell)
• EditorClass - Custom editor class

ReadOnly · Boolean · default: "False"

Global read-only flag. When True, all cells are non-editable regardless of column settings.

Selection

Selected · TGridSelection

Current selection in the grid including:

• Selected cell coordinates
• Selected rows
• Selected range

Public Methods

Display and Rendering

Paint · procedure

Renders the grid content. Override this method in derived classes to customize rendering.

Signature:

procedure Paint; override;

ClientWidth · function

Returns the available width for grid content, excluding scrollbars and margins.

Signature:

function ClientWidth: Single; override;

Returns: Available width in pixels

ClientHeight · function

Returns the available height for grid content, excluding scrollbars and margins.

Signature:

function ClientHeight: Single; override;

Returns: Available height in pixels

Data Operations

RefreshData · procedure

Refreshes the grid display from the data source. Call this when the underlying data has changed.

Signature:

procedure RefreshData;

CanExpand · function

Determines if a row can be expanded to show detail data.

Signature:

function CanExpand(const Sender: TRender; const ARow: Integer): Boolean;

Parameters:

• Sender - The render object requesting expansion
• ARow - Row index to check

Returns: True if the row has expandable detail data

Clipboard Operations

Copy · procedure

Copies the selected cells to the clipboard in tab-delimited format.

Signature:

procedure Copy(const ASelection: TGridSelection = nil); virtual; abstract;

Parameters:

• ASelection - Optional specific selection to copy (uses current selection if nil)

PasteSelected · procedure

Pastes clipboard content into the selected cells.

Signature:

procedure PasteSelected; virtual; abstract;

Utility Methods

Assign · procedure

Copies all properties from another grid instance.

Signature:

procedure Assign(Source: TPersistent); override;

Loaded · procedure

Called after the component is loaded from a stream (DFM/FMX file). Override to perform post-load initialization.

Signature:

procedure Loaded; override;

MouseLeave · procedure

Handles mouse leave events. Call when the mouse cursor leaves the grid area.

Signature:

procedure MouseLeave;

Protected Methods

These methods are available for descendant classes and advanced customization.

Editor Management

StartEditor · procedure

Initiates cell editing for the specified column and row.

Signature:

procedure StartEditor(const AColumn: TColumn; const ARow: Integer;
                     const AutoEdit: String = ''); overload; virtual; abstract;
procedure StartEditor(const AutoEdit: String = ''); overload;

Parameters:

• AColumn - Column to edit
• ARow - Row index to edit
• AutoEdit - Optional initial text for auto-edit mode

StopEditor · procedure

Stops cell editing and commits changes.

Signature:

procedure StopEditor; virtual;

CancelEditor · procedure

Cancels cell editing without committing changes.

Signature:

procedure CancelEditor; virtual;

Scrolling

HorizScrollChanged · procedure

Called when horizontal scroll position changes.

Signature:

procedure HorizScrollChanged(Sender: TObject); virtual; abstract;

VertScrollChanged · procedure

Called when vertical scroll position changes.

Signature:

procedure VertScrollChanged(Sender: TObject); virtual; abstract;

CheckScrollLimits · procedure

Validates and adjusts scroll positions to stay within valid bounds.

Signature:

procedure CheckScrollLimits(var X, Y: Single); virtual; abstract;

Data Events

DataChanged · procedure

Called when the data source changes or is refreshed.

Signature:

procedure DataChanged; virtual;

Input Handling

Key · procedure

Processes keyboard input.

Signature:

procedure Key(const AState: TKeyState);

Mouse · procedure

Processes mouse input.

Signature:

procedure Mouse(var AState: TMouseState);

Events

OnAfterDraw · TNotifyEvent

Fired after the grid is painted. Use for custom post-rendering operations.

OnSelect · TNotifyEvent

Fired when the selection changes.

Example: Custom Grid Implementation

type
  TMyCustomGrid = class(TCustomTeeGrid)
  protected
    // Override abstract methods
    procedure CheckScrollLimits(var X, Y: Single); override;
    function HorizScrollBarHeight: Single; override;
    procedure HorizScrollChanged(Sender: TObject); override;
    function VertScrollBarWidth: Single; override;
    procedure VertScrollChanged(Sender: TObject); override;
    
    procedure StartEditor(const AColumn: TColumn; const ARow: Integer;
                         const AutoEdit: String = ''); override;
  public
    procedure Copy(const ASelection: TGridSelection = nil); override;
    procedure PasteSelected; override;
    function Painter: TPainter; override;
    function Height: Single; override;
    function Width: Single; override;
  end;

See Also

TTeeGrid

Main grid component for VCL and FMX

TVirtualData

Abstract data interface