Pivot Timelines and Slicer data states

On offer 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 together with its required package identities; failure returns nil before any staged state is committed

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

TXLSXTimelineCache.Name names the cache, SourceName names its source field and IsNonOlapPivot picks out the validated supported binding; imported unsupported caches keep their original XML

TXLSXTimelineCache.ConnectPivotTable(ATable: TXLSPivotTable): Integer connects a further owned view of the same PivotCache with a compatible date field; it returns 1 for success, an existing connection included, 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 running from 1 January 1900 through 31 December 9999 in ascending order

The supported workbook uses the 1900 date system; Date1904 authoring and fractional selection endpoints are refused, whilst source date values may hold a time-of-day and records throughout the selected end day stay eligible

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

Selections intersect other Slicers, manual or page filters and caller predicates; these operations neither refresh source caches nor recalculate formulas, and they rewrite no 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 the UI whilst keeping its shared cache and selection

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

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

TXLSXTimeline.SetBounds alters the one-based rectangle exposed by FromRow, FromCol, ToRow and ToCol; invalid geometry, unsupported bindings or grouped drawing geometry raise without any mutation taking place

TXLSXDrawingObject.Timeline gives back the associated view for drawing kind xlsxDrawingTimeline; direct unsupported drawing transformations stay guarded

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

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

xlsxSlicerClearSelection takes out the selection; xlsxSlicerPreserveCurrentSelection keeps an active selection as a whole-day date comparison only where the date field already sits on a row or column axis in every connected view

An unused or page-only date field refuses selection-preserving removal atomically; use explicit selection-clearing removal where that behaviour is what you want

Imported filters normalise only once every connection, inherited namespace and exact owned-filter provenance has validated; opaque same-field attributes or children, foreign namespaces, external bindings and unsupported multiple-UI graphs keep their XML and refuse mutation

Native materialisation stages the current Timeline selection alongside 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 is refused, ODS conversion reports the Timeline loss and the XLSB values-and-styles subset refuses 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 whole native no-data vector, then commits it under a workbook write guard; on success it returns 1, rejection returns -1 without touching serialised item flags or selections

It ignores this Slicer's own selection whilst 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 pick up the native no-data flag whilst keeping their selection; stable cache IDs, original item wire order and unrelated XML stay intact

The default cumulative step limit is 1000000; zero means unbounded steps, a negative value is refused 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 are refused before flags are committed; independent common-model changes made by caller callbacks stay the caller's changes and trigger refresh rejection

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

ItemHasData stays a read-only query; saving neither calls the evaluator nor updates no-data flags implicitly, so call RefreshItemDataStates explicitly before saving whenever native UI state must be refreshed

Advanced date-filter semantics

TXLSPivotFilter.UseWholeDay asks for whole-day date comparisons on supported date filters; Timeline-generated preserved selections use it whilst ordinary date filters keep their previous time-sensitive behaviour

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