CreateLoadedCellCursor method
Creates a pull cursor over stored cells in a loaded XLSX workbook, with an option to include independently styled blanks
Syntax
function CreateLoadedCellCursor: IXLSLoadedCellCursor; overload; function CreateLoadedCellCursor( AIncludeStoredBlanks: Boolean): IXLSLoadedCellCursor; overload;
Traversal order and cost
The cursor visits worksheets in collection order, then cells by ascending row and column
SheetIndex, Row, and Col are one-based public coordinates
Materialized worksheets are read directly from their allocated 256-row sparse blocks without building a sorted cell list
Packed worksheets are read directly through the packed-storage iterator and remain packed after traversal
Cursor state is constant in workbook size and does not allocate arrays sized to the XLSX row or column limits
The parameterless overload skips style-only blanks, stored Empty placeholders, and stored Null placeholders
Pass True to include independently styled blank coordinates from materialized or packed storage without materializing packed cells
Unstyled Empty and Null placeholders remain excluded in both modes
Snapshot fields
| Field | Meaning |
|---|---|
SheetIndex / SheetName | Owning worksheet identity at the time of capture |
Row / Col | One-based cell coordinates |
StyleIndex | XLSX cell format index captured from materialized or packed storage |
Kind | xlckText, xlckNumber, xlckDateTime, xlckBoolean, xlckFormula, xlckError, or xlckBlank |
Value | Owned Variant value captured for the current cell |
Formula | Formula text for formula cells, otherwise an empty string |
Strings and Variants in TXLSLoadedCellSnapshot are owned values and do not expose internal cell or packed-storage pointers
For XLSX formula cells, Value is the currently stored cached value and traversal does not recalculate the formula
For xlckBlank, Value is Unassigned, Formula is empty, and StyleIndex identifies the stored cell format
State, invalidation, and lifetime
State is xlccBeforeFirst until the first successful MoveNext, xlccActive while Current is available, and xlccEof after traversal completes
Reading Current before the first cell or after EOF raises EXLSLoadedCellCursorState
Creating or deleting stored cells, packed-storage materialization, explicit index rebuilds, or adding, deleting, moving, or clearing worksheets invalidates the cursor
The next MoveNext or Current call then raises EXLSLoadedCellCursorInvalidated
Changing an existing cell value, formula, or format does not invalidate the cursor, and an already captured snapshot remains unchanged
Releasing the workbook before the cursor also raises EXLSLoadedCellCursorInvalidated instead of leaving the cursor with a dangling workbook pointer
Generation validation is fail-fast detection and does not make concurrent mutation and traversal thread-safe
Example
Cursor := Workbook.CreateLoadedCellCursor;
while Cursor.MoveNext do
begin
Cell := Cursor.Current;
Memo1.Lines.Add(Format('%s!R%dC%d = %s',
[Cell.SheetName, Cell.Row, Cell.Col, VarToStr(Cell.Value)]));
end;