TDashboardGrid

Free-form dashboard grid container using absolute positioning with snap-to-grid behavior. Cards can be placed at any grid intersection and span multiple cells. Supports drag-to-reposition, resize handles, and responsive breakpoint layouts.

DashboardResponsiveDrag & DropResizable

Overview

TDashboardGrid provides a grid-based dashboard layout where TDashboardGridCard components can be placed at specific grid positions and span multiple cells. The grid supports responsive layouts via TResponsiveLayoutCollection, automatically switching between desktop grid and mobile stacked layouts based on viewport width.

Component Hierarchy

TCoreDiv
  └── TDashboardGrid (container with responsive layout support)
        └── TDashboardGridCard (inherits from TCoreHeaderCard)
              └── TCoreHeaderCard (header with buttons)
                    └── TCoreCard (base card with footer/traffic light)

Key Published Properties - TDashboardGrid

Property	Type	Default	Description
Columns	`Integer`	3	Number of grid columns. Set to 0 for unlimited.
Rows	`Integer`	0	Number of grid rows. 0 = unlimited (auto-grow). When > 0, cells dynamically size to fill container height.
CellWidth	`Integer`	250	Base cell width in pixels. Actual width may differ based on container size.
CellHeight	`Integer`	200	Base cell height in pixels. When Rows > 0, actual height is calculated dynamically.
CellGap	`Integer`	10	Gap between cells in pixels.
ScrollMode	`TGridScrollMode`	gsmVertical	Overflow handling: gsmNone, gsmVertical, gsmHorizontal, gsmBoth.
ShowGridLines	`Boolean`	False	Show CSS grid lines for debugging layout.
Layout	`TResponsiveLayoutCollection`	-	Collection of responsive breakpoint layouts.

Key Published Properties - TDashboardGridCard

Property	Type	Default	Description
GridCol	`Integer`	1	Starting column position (1-based).
GridRow	`Integer`	1	Starting row position (1-based).
ColSpan	`Integer`	1	Number of columns the card spans.
RowSpan	`Integer`	1	Number of rows the card spans.

Responsive Layouts

TDashboardGrid uses TResponsiveLayoutCollection for responsive breakpoints. Default layouts created at design time:

Breakpoint	Width	Style	Behavior
Mobile	≤576px	`1fr`	Stacked layout - cards stack vertically in single column
Tablet	≤768px	`1fr 1fr`	2-column grid
Desktop	>768px	`1fr 1fr 1fr`	3-column grid (or as configured)

Stacked Layout: When viewport triggers a 1fr layout, cards automatically stack vertically. Cards are sorted by original column first, then row, preserving left-to-right, top-to-bottom reading order.

Dynamic Cell Height

When Rows > 0, the grid calculates cell heights dynamically to fill the container:

/// GetEffectiveCellHeight calculation:
/// 1. In stacked layout: returns fixed CellHeight (grid scrolls)
/// 2. When Rows > 0: (ContainerHeight - TotalGaps) / Rows
/// 3. Otherwise: returns fixed CellHeight

IMMUTABLE Code: The following functions contain immutable code that must not be modified:

GetEffectiveCellHeight - enables cards to fill container height
GridToPixelY - must use GetEffectiveCellHeight
SpanToHeight - must use GetEffectiveCellHeight
ApplyContainerStyles - stacked layout check for min-height
HandleWindowResize - must call ApplyContainerStyles before card updates

Drag & Resize Operations

TDashboardGridCard provides grid-aware drag and resize behavior:

Drag Handle: 6-dot pattern in header. Dragging shows a semi-transparent ghost at target position.
Resize Handle: Bottom-right corner. Resizing snaps to grid cell boundaries.
Grid Snapping: All movements convert pixel deltas to grid cell deltas.
Validation: OnValidatePosition event allows preventing invalid moves/resizes.

Event Handler Architecture

/// TDashboardGridCard overrides base class handlers:
DragHandleMouseDownHandler   := @HandleGridDragMouseDown;
DocumentMouseMoveHandler     := @HandleGridDragMouseMove;
DocumentMouseUpHandler       := @HandleGridDragMouseUp;
ResizeHandleMouseDownHandler := @HandleGridResizeMouseDown;
ResizeMouseMoveHandler       := @HandleGridResizeMouseMove;
ResizeMouseUpHandler         := @HandleGridResizeMouseUp;

Public Methods - TDashboardGrid

FUNCTION AddCard(Col, Row, ColSpan, RowSpan: Integer; CONST Title: STRING = ''): TDashboardGridCard;

Creates and adds a new card at the specified grid position.

PROCEDURE RemoveCard(Card: TDashboardGridCard);

Removes and frees a card from the grid.

FUNCTION MoveCard(Card: TDashboardGridCard; NewCol, NewRow: Integer): Boolean;

Moves a card to a new position. Returns True if successful.

FUNCTION ResizeCard(Card: TDashboardGridCard; NewColSpan, NewRowSpan: Integer): Boolean;

Resizes a card. Returns True if successful.

FUNCTION IsPositionFree(Col, Row, ColSpan, RowSpan: Integer; ExcludeCard: TDashboardGridCard = NIL): Boolean;

Returns True if the specified grid rectangle is not occupied.

PROCEDURE ShowDragGhost(Col, Row, ColSpan, RowSpan: Integer);

Shows the semi-transparent drag ghost at the specified position.

Events

Event	Type	Description
OnCardPositionChanged	`TCardPositionChangeEvent`	Fired after a card is moved or resized.
OnValidatePosition	`TValidatePositionEvent`	Fired before a move/resize to allow validation. Set Allow := False to prevent.

Theme Integration

Both TDashboardGrid and TDashboardGridCard implement IThemeSubscriber. The grid applies background color from the 'grid' style definition.

Usage Example

/// Create grid programmatically
Grid := TDashboardGrid.Create(Self);
Grid.Parent := Self;
Grid.Columns := 3;
Grid.Rows := 2;  /// Fixed 2 rows, cells fill container height
Grid.CellGap := 12;

/// Add cards
Card1 := Grid.AddCard(1, 1, 1, 1, 'Card 1');
Card2 := Grid.AddCard(2, 1, 2, 1, 'Wide Card');  /// Spans 2 columns