Safe Pivot worksheet materialisation

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

Materialise 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 sets them down at the view's FirstRow and FirstCol; it returns 1 on success or -1 for unsupported sources, unsafe destinations, evaluation failure or a refused workbook mutation

Refresh and worksheet recalculation stay explicit operations; successful materialisation invalidates calculation dependencies so that callers can recalculate downstream formulas where appropriate

The default overload takes blank destination cells and unchanged cells previously owned by the same view; occupied unowned cells anywhere within the complete output rectangle sink the operation, gaps the result writer does not fill included

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

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

Ownership, resizing and movement

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

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

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

Changing FirstRow or FirstCol shifts the next output whilst the previous ownership coordinates stay available for cleanup; an empty result clears the owned values and keeps an anchor-only location

Isolated preview

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

TXLSPivotTable.MakePreview works from independent copies of the cache and view, calculated-field placeholders included, and discards them once evaluation ends; ordinary Make keeps its existing live-cache behaviour

The writer is given 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 yields zero, and evaluation or writer exceptions are propagated

Caller record predicates and registered owner filters stay active in previews, workbook Slicer selections included; 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 must identify a connected view, reading the evaluated records from the callback's temporary Cache

Callback owners remain the caller's property; preview objects and their records must not be kept once the callback or preview call has ended

Safety boundaries

Materialisation needs a view and cache registered in the same workbook plus a supported local rectangular, defined-name or table source; source resolution follows current names and table extents, and unsupported or unresolved sources are refused before mutation

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

Validation and output staging run under a read lease, then come the normal workbook mutation guard and generation check; a frozen read-only workbook view sinks materialisation without replacing cells or changing geometry

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

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