Pivot Timelines and Slicer data states

Available since version 2.384.98 for supported local non-OLAP PivotTables through the XLSX workbook facade

Create and connect a Timeline

TimelineCache := Workbook.CreatePivotTimelineCache(Pivot, 'EventDate');
if TimelineCache = nil then
  raise Exception.Create('The Timeline cache was rejected');
TimelineView := ReportSheet.Timelines.Add(TimelineCache, 2, 7, 7, 12);
if TimelineView = nil then
  raise Exception.Create('The Timeline view was rejected');
if TimelineCache.SetDateRange(EncodeDate(2026, 1, 1),
    EncodeDate(2026, 1, 31)) < 0 then
  raise Exception.Create('The Timeline selection was rejected');

TXLSXWorkbook.CreatePivotTimelineCache(ATable: TXLSPivotTable; const AFieldName: WideString): TXLSXTimelineCache creates or reuses a validated date-field cache and its required package identities; failure returns nil before committing staged state

TXLSXWorkbook.TimelineCaches exposes TXLSXTimelineCaches, with Count, zero-based Items[Index] and case-insensitive FindByName; the workbook owns these caches

TXLSXTimelineCache.Name identifies the cache, SourceName identifies its source field and IsNonOlapPivot identifies the validated supported binding; imported unsupported caches retain their original XML

TXLSXTimelineCache.ConnectPivotTable(ATable: TXLSPivotTable): Integer connects another owned view of the same PivotCache with a compatible date field; it returns 1 for success, including an existing connection, or -1 for rejection

TXLSXTimelineCache.SetDateRange(AStartDate, AEndDate: TDateTime): Integer uses inclusive whole-day endpoints and returns 1 or -1; endpoints must be integral dates from January 1, 1900 through December 31, 9999 in ascending order

The supported workbook uses the 1900 date system; Date1904 authoring and fractional selection endpoints reject, while source date values may retain time-of-day and records throughout the selected end day remain eligible

TXLSXTimelineCache.SelectionActive, StartDate and EndDate expose the active bounds; ClearSelection: Integer clears them without changing other filters and returns 1 or -1

Selections intersect other Slicers, manual or page filters and caller predicates; these operations do not refresh source caches, recalculate formulas or rewrite existing worksheet report cells

Timeline views and removal

TXLSXWorksheet.Timelines exposes the worksheet-owned TXLSXTimelines collection, with Add, FindByName, zero-based Items[Index], Count, Delete(Index) and Clear; deletion removes UI while retaining its shared cache and selection

TXLSXTimelines.Add(ACache: TXLSXTimelineCache; ARow1, ACol1, ARow2, ACol2: Integer): TXLSXTimeline accepts an owned supported cache and an ordered one-based worksheet rectangle, returning an owned view or nil

TXLSXTimeline.Name is read-only, Cache identifies its shared cache, and Caption changes the display label; Level accepts 0 for years, 1 for quarters, 2 for months or 3 for days

TXLSXTimeline.SetBounds changes the one-based rectangle exposed by FromRow, FromCol, ToRow and ToCol; invalid geometry, unsupported bindings or grouped drawing geometry raise before mutation

TXLSXDrawingObject.Timeline returns the associated view for drawing kind xlsxDrawingTimeline; direct unsupported drawing transformations remain guarded

Status := Workbook.RemoveTimelineCache(TimelineCache,
  xlsxSlicerPreserveCurrentSelection);

TXLSXWorkbook.RemoveTimelineCache(ACache: TXLSXTimelineCache; AMode: TXLSXSlicerRemovalMode): Integer stages connected filters, UI, names and package cleanup together and returns 1 or -1

xlsxSlicerClearSelection removes the selection; xlsxSlicerPreserveCurrentSelection retains an active selection as a whole-day date comparison only when the date field is already on a row or column axis in every connected view

An unused or page-only date field rejects selection-preserving removal atomically; use explicit selection-clearing removal when that behavior is intended

Imported filters normalize only after every connection, inherited namespace and exact owned-filter provenance validates; opaque same-field attributes or children, foreign namespaces, external bindings and unsupported multiple-UI graphs retain their XML and reject mutation

Native materialization stages current Timeline selection with report metadata and cells, removing only the exact saved owned filter signature; arbitrary callback restrictions have no native XML representation and cannot be reproduced by Excel refresh

OOXML saving preserves native relationship types, original paths and unrelated extensions; Strict cache-only saving rejects, ODS conversion reports Timeline loss and the XLSB values-and-styles subset rejects Timelines

Explicit native Slicer data-state refresh

function TXLSXSlicerCache.RefreshItemDataStates: Integer; overload;
function TXLSXSlicerCache.RefreshItemDataStates(
  AMaxEvaluationSteps: Integer; ACancelFlag: PBoolean = nil): Integer; overload;

The operation evaluates and stages the complete native no-data vector, then commits under a workbook write guard; success returns 1, rejection returns -1 without changing serialized item flags or selections

It ignores this Slicer's own selection while intersecting other Slicer and Timeline selections, manual or page filters, supported aggregate filters and caller predicates; availability is the union across supported connected views

Selected historical members without eligible records receive the native no-data flag while retaining their selection; stable cache IDs, original item wire order and unrelated XML remain intact

The default cumulative step limit is 1000000; zero means unbounded steps, a negative value rejects and FormulaArrayMemoryLimit bounds metadata staging plus all connected-view previews cumulatively

Cancellation, callback exceptions or reentry, frozen views, unsupported bindings, exhausted budgets or changed evaluation state reject before committing flags; independent common-model changes made by caller callbacks remain the caller's changes and cause refresh rejection

TXLSXSlicerCache.CrossFilter reads and writes the native tabular cross-filter setting under the mutation guard; showItemsWithDataAtTop enables native data-first ordering without rewriting item wire order

ItemHasData remains a read-only query; saving does not call the evaluator or update no-data flags implicitly, so call RefreshItemDataStates explicitly before saving when native UI state must be refreshed

Advanced date-filter semantics

TXLSPivotFilter.UseWholeDay requests whole-day date comparisons for supported date filters; Timeline-generated preserved selections use it while ordinary date filters retain their previous time-sensitive behavior

See native Pivot output and read-only Slicer availability and local cache and Slicer lifecycle for the surrounding refresh and ownership contracts