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, public ITMSFNCDataBinderGrid, public ITMSFNCCustomReadWriteIO, public ITMSFNCDataObject
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. |