Safe Pivot worksheet materialization

Version 2.384.90 adds isolated Pivot evaluation and guarded worksheet result replacement; version 2.384.92 extends supported local sources to defined names and tables resolved at each call

Materialize a view

if Workbook.RefreshPivotCache(Pivot.CacheId) <> 1 then
  raise Exception.Create('Pivot cache refresh failed');
if Workbook.MaterializePivotTable(Pivot) <> 1 then
  raise Exception.Create('Pivot output cannot be replaced safely');

TXLSXWorkbook.MaterializePivotTable(ATable: TXLSPivotTable): Integer computes results from the current cache and places them at the view's FirstRow and FirstCol; it returns 1 on success or -1 for unsupported sources, unsafe destinations, evaluation failure, or a rejected workbook mutation

Refresh and worksheet recalculation remain explicit operations; successful materialization invalidates calculation dependencies so callers can recalculate downstream formulas when appropriate

The default overload accepts blank destination cells and unchanged cells previously owned by the same view; occupied unowned cells anywhere inside the complete output rectangle reject the operation, including gaps that the result writer does not fill

if Workbook.MaterializePivotTable(Pivot, True) <> 1 then
  raise Exception.Create('Existing Pivot values cannot be adopted safely');

TXLSXWorkbook.MaterializePivotTable(ATable: TXLSPivotTable; AAdoptExisting: Boolean): Integer can explicitly adopt existing scalar cells inside the view's declared previous rectangle on its first materialization; it does not authorize replacing formulas, array members, rich text, metadata-bearing cells, or content outside that rectangle

Ownership, resizing, and movement

The view retains exact coordinates and typed value snapshots for written cells; XLSX saving preserves this ownership in the Pivot definition, so later updates can validate it after reopening

Changed typed content or a removed nonblank owned cell rejects the entire update; number subtypes share a canonical numeric representation, while text, Boolean values, and errors retain distinct identities

Shrinking or moving a result clears only unchanged owned values that are no longer produced; existing cell objects, formatting, and comments remain available, and unrelated cells remain outside the ownership set

Changing FirstRow or FirstCol moves the next output while the previous ownership coordinates remain available for cleanup; an empty result clears owned values and retains an anchor-only location

Isolated preview

function TXLSPivotTable.MakePreview(AWriter: TlxPivotResultWriter): Integer;
property TXLSPivotTable.EvaluationSourceTable: TXLSPivotTable;

TXLSPivotTable.MakePreview uses independent copies of the cache and view, including calculated-field placeholders, and discards them after evaluation; ordinary Make retains its existing live-cache behavior

The writer receives zero-based row and column offsets and typed values; the return value follows Make's aggregate-cell count, which is separate from the number of writer calls; a missing cache or writer returns zero, and evaluation or writer exceptions propagate

Caller record predicates and registered owner filters remain active in previews, including workbook Slicer selections; callbacks receive the temporary evaluated view and its temporary cache

TXLSPivotTable.EvaluationSourceTable returns the live view for an ordinary evaluation and the original live view for a preview; use it when a callback needs to identify a connected view, while reading evaluated records from the callback's temporary Cache

Callback owners remain caller-owned; preview objects and their records must not be retained after the callback or preview call ends

Safety boundaries

Materialization requires a view and cache registered in the same workbook and a supported local rectangular, defined-name, or table source; source resolution follows current names and table extents, and unsupported or unresolved sources reject before mutation

Current source geometry, other Pivot locations, structured tables, query result ranges, merged cells, and fixed or dynamic arrays cannot intersect the new output or old owned cells that need clearing; table totals remain protected even though they are excluded from cache records

Validation and output staging run under a read lease, followed by the normal workbook mutation guard and generation check; a frozen read-only workbook view rejects materialization without replacing cells or changing geometry

Filters must be read-only and follow the workbook's ordinary single-writer contract; isolation prevents normal preview calculations from changing the live cache, but arbitrary callback writes through separately captured live objects cannot be rolled back

This operation materializes the library's calculated result layout; complete native Pivot layout authoring, Slicer UI creation, and cross-filter no-data display evaluation remain separate capabilities