TTMSFNCDataGridData Class
Headless data engine of the data grid: cell storage, sorting, grouping, filtering, find and replace, calculations, merging, tree nodes, AutoFill, and import/export.
API unit family: TMSFNCDataGridData
Inherits from: TTMSFNCDataGridCore
Implements: ITMSFNCDataBinderGrid, ITMSFNCCustomReadWriteIO, ITMSFNCDataObject
Syntax
TTMSFNCDataGridData = class(TTMSFNCDataGridCore, ITMSFNCDataBinderGrid, ITMSFNCCustomReadWriteIO, ITMSFNCDataObject)
class PASCALIMPLEMENTATION TTMSFNCDataGridData : public TTMSFNCDataGridCore
Remarks
The class has no visual output of its own. The grid renderer descends from it, and the visible grid exposes most of its members; use the grid's Root property for data operations the grid does not surface directly.
Values are stored per row in DataDictionary; rows without data occupy no memory. Wrap bulk changes in BeginUpdate/EndUpdate to avoid repeated recalculation and repainting.
A TTMSFNCDataGridDataAdapter can connect an external data source; when one is attached, sorting, grouping and filtering may be handled or restricted by the adapter.
Properties
| Name | Description |
|---|---|
| Adapter | The active data adapter (database binding). Set to a TTMSFNCDataGridDataAdapter subclass to bind an external data source. |
| Booleans | Typed read/write access to a cell as Boolean. |
| CellData | Returns the full TTMSFNCDataGridCellItem for a cell (type, layout, state, value). |
| CellDataExtended | Returns TTMSFNCDataGridCellItemExtended with additional runtime state for a cell. |
| Cells | Raw read/write access to cell values as TTMSFNCDataGridCellValue (accepts string, integer, float, or Boolean). |
| ColumnCalculations | Read/write the stored calculation array for a column; AName namespaces the calculation so multiple calculations can coexist on one column. |
| Controls | Gets or sets the embedded control reference for a cell (button, checkbox, progress bar, etc.). |
| DataDictionary | Internal serialised dictionary of all stored cell data (row items). Persisted in the DFM; do not modify directly at runtime. |
| Filter | The collection of active filter rules. Add items and call ApplyFilter to filter the grid. See TTMSFNCDataGridDataFilter. |
| FilterActions | The collection of filter actions triggered when a row matches a filter rule (hide row, apply appearance, execute action). |
| FilterBuilder | The filter builder used to compose and evaluate filter expressions for the grid data. Use it to construct filter rules programmatically. |
| FilterFormatType | The filter expression syntax used throughout the grid: by the filter row and filter dialog, and by conditional formatting expression rules. Default is fftUniversalFilterExpressions. A database adapter in afmAdapter filter mode overrides this with the DataSet syntax, because the expression is handed to the dataset itself. |
| Floats | Typed read/write access to a cell as Double. |
| GroupDictionary | Internal dictionary of current group buckets produced by the last Group() call. Read-only; rebuilt whenever grouping is applied. |
| GroupInfo | The TTMSFNCDataGridDataGroupInfo record describing the current grouping state. |
| HasColumnCalculations | Returns True when a stored calculation with AName exists for AColumn. |
| HasFilter | Returns True when at least one filter rule is active. |
| HasRowCalculations | Returns True when a stored calculation with AName exists for ARow. |
| Ints | Typed read/write access to a cell as Int64. |
| ManagedObjects | Associates a TObject with a cell and takes ownership (freed with the cell). |
| Objects | Associates a TObject with a cell without taking ownership. |
| Options | All data-layer options: sorting, grouping, filtering, calculations, I/O, Find, and URL detection. See TTMSFNCDataGridDataOptions. |
| RowCalculations | Read/write the stored calculation array for a row; AName namespaces the calculation so multiple calculations can coexist on one row. |
| RowNodeChildCount | Number of direct child rows under a node row. |
| RowNodeLevel | Nesting depth of a node row (0 = top level). |
| RowNodeState | Collapsed or expanded state of a node row. |
| RowText | The display text of a group node header row. |
| RowTypes | The TTMSFNCDataGridRowType classification of a row (default, summary, node, filter). |
| SortIndexList | The list of active sort levels (column + direction pairs) representing the current multi-column sort state. |
| StoredCells | Returns the raw (unformatted) cell value as stored in the data dictionary, bypassing adapter and OnGetCellData overrides. |
| Strings | Gets or sets the cell value as a plain string. Reading returns the formatted display value; writing stores the string directly. |
| StrippedCells | Returns the cell display text with all HTML tags stripped, useful for plain-text export or search. |
Methods
| Name | Description |
|---|---|
| AddColumn | Appends one empty column at the right of the grid. |
| AddNodeRow | Converts the row at ARow into a collapsible tree node header with AChildCount child data rows. ALevel sets the nesting depth (0 = top level). AMerge merges the header cell across all columns. |
| AddRow | Appends one empty data row at the bottom of the grid. |
| ApplyFilter | Evaluates the rules in the Filter collection against every data row and hides rows that do not match. Fires OnBeforeApplyFilter and OnAfterApplyFilter. |
| AutoFill | Extends the pattern from the source range into the target range (Excel fill-handle behaviour). Direction is auto-detected from geometry when gafdAuto is passed. |
| AutoFillCustomListRemove | Removes the custom AutoFill list registered under AKey. |
| AutoFillCustomListSet | Registers a custom cyclic fill sequence under AKey (e.g. key='months', values=['Jan','Feb',...]). |
| AutoFillCustomListTryGet | Retrieves the custom AutoFill list for AKey; returns True if found. |
| AutoFillCustomListsClear | Removes all registered custom AutoFill cyclic lists. |
| AutoFillCustomListsCount | Returns the number of registered custom AutoFill lists. |
| AutoNumberColumn | Fills a column with sequential integers starting at AStartValue from AStartRow downward. |
| AutoNumberRow | Fills a row with sequential integers starting at AStartValue from AStartColumn rightward. |
| BaseCell | Returns the base (top-left) cell of the merged range that contains a cell. |
| CanDeleteColumn | Checks whether a column can be deleted. |
| CanDeleteRow | Checks whether a row can be deleted. |
| CanInsertColumn | Checks whether a column can be inserted at a position. |
| CanInsertRow | Checks whether a row can be inserted at a position. |
| CanMergeCells | Checks whether a rectangular block of cells can be merged. |
| CanMoveColumn | Checks whether a column can be moved to another position. |
| CanMoveRow | Checks whether a row can be moved to another position. |
| CanSwapColumn | Checks whether two columns can be swapped. |
| CanSwapRow | Checks whether two rows can be swapped. |
| ClearCells | Clears data in a specific rectangular cell range. |
| ClearData | Removes all cell data while preserving structure (row/column count, widths, heights). |
| ClearDataForColumn | Clears data in a column; pass AllRowTypes to include summary and node rows. |
| ClearDataForRow | Clears data in a row; pass AllRowTypes to include summary and node rows. |
| ClearFilter | Deactivates all filter rules and makes all rows visible. |
| ClearFind | Resets the stateful find position used by FindNext. |
| ClearNodeRow | Clears child data but preserves the node header structure. |
| CollapseAllNodes | Collapses all node rows at once, hiding their children. |
| CollapseNode | Collapses an expanded node row, hiding its children. |
| ColumnAverage | Computes the average of a column over a row range. |
| ColumnCalculation | Runs an aggregate over AColumn and stores the result in the named summary cells. The result persists and is re-evaluated by UpdateCalculations. |
| ColumnCounting | Counts the participating cells of a column over a row range. |
| ColumnCustomCalculation | Computes a custom aggregate of a column over a row range and returns it. |
| ColumnDistinct | Counts the distinct text values of a column over a row range. |
| ColumnMax | Returns the largest value of a column over a row range. |
| ColumnMin | Returns the smallest value of a column over a row range. |
| ColumnSpan | Returns the number of columns this cell spans; 1 for a non-merged cell. |
| ColumnStandardDeviation | Returns the standard deviation of numeric values in AColumn over the specified row range. |
| ColumnSum | Returns the sum of numeric values in AColumn over the specified row range. |
| CopyColumnTo | Copies a column's data to another TTMSFNCDataGridData instance; AIndex specifies the target column (-1 to append). |
| DeleteColumn | Removes the specified column, shifting subsequent columns left. |
| DeleteColumns | Removes ACount columns starting at AColumn, shifting subsequent columns left. |
| DeleteRow | Removes the specified row, shifting subsequent rows up. |
| DeleteRows | Removes ACount rows starting at ARow, shifting subsequent rows up. |
| EffectiveFilterFormatType | Returns the filter expression syntax that is actually in effect, which is the configured syntax unless a database adapter in adapter filter mode overrides it. |
| EndUpdate | Ends an update block started with BeginUpdate; when the outermost block ends, pending automatic calculation updates are flushed and the grid is refreshed. |
| ExpandAllNodes | Expands all node rows at once, making their children visible. |
| ExpandNode | Expands a collapsed node row, making its children visible. |
| Find | Searches all data cells for AText using default parameters (contains, case-insensitive); returns the first matching cell coordinate, or an invalid cell if not found. |
| FindAll | Finds all matching cells; sets AResults to the total count; returns the first match. |
| FindFirst | Starts a stateful search session; use FindNext to advance to subsequent matches. |
| FindNext | Advances to the next match in the direction specified by ADown (True = downward/rightward). |
| GetCellKind | Returns the kind of the cell (normal, button, checkbox, bitmap, progress bar, etc.). |
| GetCellMergeType | Classifies the cell's merge zone (normal data area, fixed header zone, freeze zone, etc.). |
| GetCellSize | Returns the rendered pixel size of the cell accounting for any column/row span. |
| GetMaxLevel | Returns the deepest nesting level across all node rows. |
| GetParentRow | Returns the row index of the immediate parent node, or -1 if ARow is a top-level row. |
| GetRootRow | Returns the row index of the topmost ancestor node. |
| GoToCell | Scrolls the grid to make ACell visible; optionally selects it. |
| Group | Groups data rows by the distinct values in AColumn; inserts a header row for each unique value. |
| GroupAverage | Adds or updates a group average aggregate in the group header row for AColumn. |
| GroupCalculation | Generic group aggregate with an explicit method enum; adds or updates the summary in the group header row for AColumn. |
| GroupCount | Adds or updates a group count aggregate in the group header row for AColumn. |
| GroupCustomCalculation | Group aggregate using a user-supplied callback; adds or updates the summary in the group header row for AColumn. |
| GroupDistinct | Adds or updates a group distinct count aggregate in the group header row for AColumn. |
| GroupMax | Adds or updates a group maximum aggregate in the group header row for AColumn. |
| GroupMin | Adds or updates a group minimum aggregate in the group header row for AColumn. |
| GroupSort | Sorts group header rows by their key or aggregate value in the specified direction. |
| GroupSortIndexed | Re-applies the last group sort using the existing sort index. |
| GroupStandardDeviation | Adds or updates a group standard deviation aggregate in the group header row for AColumn. |
| GroupSum | Adds or updates a group sum aggregate in the group header row for AColumn. |
| HasRowData | Returns True when the row has at least one non-empty cell value. |
| InsertColumn | Inserts one empty column before AColumn, shifting existing columns right. |
| InsertColumns | Inserts ACount empty columns before AColumn, shifting existing columns right. |
| InsertRow | Inserts one empty row before ARow, shifting existing rows down. |
| InsertRows | Inserts ACount empty rows before ARow, shifting existing rows down. |
| IsCellBase | Returns True when the cell is the top-left anchor of a merge. |
| IsCellDisplayed | Returns True when the cell is currently rendered (not hidden and within the visible range). |
| IsCellHidden | Returns True when the cell's column or row is hidden. |
| IsCellMerged | Returns True when the cell is part of a merge (either anchor or extension). |
| IsColumnDisplayed | Returns True when the column is part of the current displayed data view. |
| IsGrouped | Returns True when grouping is currently applied. |
| IsRowDisplayed | Returns True when the row is visible (not hidden, not filtered out). |
| IsRowFilter | Returns True when the row is a filter bar row (shows filter controls in fixed row cells). |
| IsRowFilteredDisplay | Returns True when the row is excluded by the active filter. |
| IsRowNode | Returns True when the row is a collapsible tree node row. |
| IsRowNormal | Returns True when the row is a plain data row (not a summary, node, or filter row). |
| IsRowSummary | Returns True when the row is a group summary/total row. |
| LinearFill | Fills all data cells with sequential integers; set ADoFixed to True to include fixed rows. |
| LoadFromCSVData | Loads data from a CSV file using the delimiter and options from Options.IO. |
| LoadFromCSVStreamData | Loads data from a CSV stream using Options.IO settings. |
| LoadFromFileData | Loads cell data from the native grid binary format file using the default encoding. |
| LoadFromFileStreamData | Loads cell data from the native grid binary format from a stream using the default encoding. |
| LoadFromJSONData | Loads data from a JSON file with encoding; ARowDataName/AColumnDataName map JSON keys to grid rows and columns; AColumnNames maps JSON property names to specific column indices. |
| LoadFromJSONStreamData | Loads JSON from a stream with encoding; ARowDataName/AColumnDataName map JSON keys to grid rows and columns. |
| LoadFromJSONTextData | Loads JSON from an in-memory string; ARowDataName/AColumnDataName map JSON keys to grid rows and columns. |
| LoadFromXMLData | Loads data from an XML file. |
| LoadFromXMLStreamData | Loads XML from a stream. |
| LoadSampleData | Fills the grid with built-in demo data; useful for design-time preview. |
| MatchFilter | Returns True when the row's cell values satisfy all currently active filter rules. |
| MergeCells | Merges a rectangular block into a single display cell; the top-left cell becomes the anchor. |
| MergeColumn | Merges all data cells in a column vertically into one display cell. |
| MergeColumns | Vertically merges a range of columns. |
| MergeRange | Merges all cells within the given coordinate range. |
| MergeRow | Merges all data cells in a row horizontally into one display cell. |
| MergeRows | Horizontally merges a range of rows. |
| MoveColumn | Shifts a column to a new index, renumbering intervening columns. |
| MoveRow | Shifts a row to a new index, renumbering intervening rows. |
| RandomFill | Fills all data cells with random integers in [0, ARandomNumber]; set ADoFixed to True to include fixed rows. |
| RefreshData | Refreshes display for a specific cell, optionally triggering a full update. |
| RemoveFilter | Removes all filter rules and makes all rows visible again. |
| RemoveNodeRow | Removes the node structure from a row, converting it back to a plain data row. |
| Replace | Replaces all occurrences of AOriginalValue with ANewValue; returns the number of replacements made. |
| RowAverage | Computes the average of all numeric cells in ARow over the specified column range; AFromColumn/AToColumn default to -1 meaning all data columns. |
| RowCalculation | Runs an aggregate over ARow and stores the result in the named summary cell. The result persists and is re-evaluated by UpdateCalculations. |
| RowCounting | Counts non-empty cells in ARow over the specified column range. |
| RowCustomCalculation | Runs a user-supplied callback over ARow and returns its result. |
| RowDistinct | Counts the distinct values in ARow over the specified column range. |
| RowMax | Returns the maximum numeric value in ARow over the specified column range. |
| RowMin | Returns the minimum numeric value in ARow over the specified column range. |
| RowSpan | Returns the number of rows this cell spans; 1 for a non-merged cell. |
| RowStandardDeviation | Returns the standard deviation of numeric values in ARow over the specified column range. |
| RowSum | Returns the sum of numeric values in ARow over the specified column range. |
| SaveToCSVData | Exports data to a CSV file using the delimiter and options from Options.IO. |
| SaveToCSVStreamData | Exports data to a CSV stream using Options.IO settings. |
| SaveToFileData | Saves cell data to the native grid binary format file using the default encoding. |
| SaveToFileStreamData | Saves cell data to the native grid binary format into a stream using the default encoding. |
| SetNodeRow | Same as AddNodeRow but replaces existing node state. |
| Sort | Sorts all data rows by the values in AColumn. |
| SortIndexed | Re-applies the sort described by the current SortIndexList without re-reading data. |
| SplitCell | Removes a merge, restoring each cell in the previously merged area to independence. |
| SwapCells | Swaps the data between two individual cells. |
| SwapColumn | Exchanges the position of two columns. |
| SwapRow | Exchanges the position of two rows. |
| ToggleNode | Expands if collapsed, collapses if expanded. |
| TypeOfValue | Returns the runtime type kind of a cell value, such as tkInteger, tkFloat, tkUString or tkEnumeration (Boolean). |
| Ungroup | Removes all grouping structure and returns the grid to a flat view. |
| UpdateCalculations | Re-runs all stored column and row calculations. |
| UpdateColumnCalculation | Re-runs one named column calculation. |
| UpdateColumnCalculations | Re-runs all column calculations. |
| UpdateRowCalculation | Re-runs one named row calculation. |
| UpdateRowCalculations | Re-runs all row calculations. |
| ValueIsBoolean | Returns True when the cell value is stored as a Boolean. |
| ValueIsDateTime | Returns True when the cell value is a stored date/time or text that parses as a date/time with the default format settings. |
| ValueIsDateTimeType | Returns True when the cell value is stored with a TDateTime, TDate or TTime type. |
| ValueIsEmpty | Returns True when the cell value holds no data. |
| ValueIsFloat | Returns True when the cell value is stored as a floating-point number, including date/time values. |
| ValueIsInteger | Returns True when the cell value is stored as a 32-bit or 64-bit integer. |
| ValueIsString | Returns True when the cell value is stored as text. |
| ValueToBoolean | Converts a cell value to a Boolean using the default format settings. |
| ValueToDateTime | Converts a cell value to a TDateTime using the default format settings. Never raises an exception. |
| ValueToFloat | Converts a cell value to a floating-point number using the default format settings. Never raises an exception. |
| ValueToInt64 | Converts a cell value to a 64-bit integer using the default format settings. Never raises an exception. |
| ValueToInteger | Converts a cell value to an integer using the default format settings. Never raises an exception. |
| ValueToString | Converts a cell value to text using the default format settings. |
Events
| Name | Description |
|---|---|
| OnAfterApplyAutoFill | Fired after an accepted AutoFill value is written to a target cell. |
| OnAfterSetColumnCalculation | Fired after writing a column calculation result to a cell. |
| OnAfterSetRowCalculation | Fired after writing a row calculation result to a cell. |
| OnAutoFillCalculateValue | Fired while AutoFill calculates a value, before the built-in pattern logic runs. |
| OnAutoFillGetCustomList | Fired to supply a custom fill sequence for a base value not found in the registered custom lists. |
| OnBeforeApplyAutoFill | Fired after an AutoFill value is calculated and before it is written to a target cell. |
| OnBeforeSetColumnCalculation | Fired before writing a column calculation result to a cell. |
| OnBeforeSetRowCalculation | Fired before writing a row calculation result to a cell. |
| OnCustomColumnCalculation | Fired when ColumnCalculation is called with gcmCustom; return the aggregate value. |
| OnCustomCompare | Fired during Sort to provide a custom row comparison. |
| OnCustomRowCalculation | Fired when RowCalculation is called with gcmCustom; return the aggregate value. |
| OnGetCellData | Fired in virtual/unbound mode to supply cell data on demand; set AData to return the value. |
| OnGetCellDataProperties | Fired to customise per-cell item properties (type, layout, state) dynamically. |
| OnGetCellDisplayValue | Fired to override the formatted display string shown in a cell. |
| OnGetCellFormatting | Fired to supply a custom format string and type for cell value formatting. |
| OnGetColumnCalculationOptions | Fired to supply per-column output formatting for each stored calculation. |
| OnGetCustomGroup | Fired to override the group key string for a cell during Group(). |
| OnGetGroupOptions | Fired to supply per-level grouping display options. |
| OnGetRowCalculationOptions | Fired to supply per-row output formatting for each stored calculation. |
| OnGetSortOptions | Fired to supply per-column sort options (case sensitivity, format type). |
| OnLoadCellData | Fired during file load to transform cell values during import. |
| OnRowCollapse | Fired after a node row is collapsed. |
| OnRowExpand | Fired after a node row is expanded. |
| OnSaveCellData | Fired during file save to transform cell values during export. |