SectionedListController<K extends Object, Section, Item> class

The imperative engine behind a SectionedSliverList.

Owns the imperative API (addItem, moveItem, setItems, expandSection, ...) and translates section/item-shaped operations into the underlying 2-level tree.

In the declarative SectionedSliverList, the widget creates and disposes one of these internally; a reference is surfaced to the header/item builders via SectionView.controller / ItemView.controller. There the sections / itemsOf props stay authoritative — imperative mutations are reverted by the next rebuild that re-runs the diff.

In SectionedSliverList.controlled, the caller constructs, owns and disposes the controller, and it is the sole source of truth: no diffing, nothing to revert against.

SectionedListController implements Listenable: addListener / removeListener forward to the underlying TreeController and fire on structural changes only (insert / remove / move / reorder / expand / collapse). Payload-only mutations (updateSection, updateItem) do NOT fire the structural channel — subscribe via addSectionPayloadListener / addItemPayloadListener instead.

Inside runBatch, structural notifications coalesce to a single fire at batch exit, and payload notifications are deferred and deduped by key.

Implemented types

• Listenable

Constructors

SectionedListController({required TickerProvider vsync, required K sectionKeyOf(Section section), required K itemKeyOf(Item item), Duration animationDuration = const Duration(milliseconds: 300), Curve animationCurve = Curves.easeInOut, double itemIndent = 0.0, bool preserveExpansion = true})

Properties

animationCurve ↔ Curve

getter/setter pair

animationDuration ↔ Duration

getter/setter pair

hashCode → int

The hash code for this object.

no setter, inherited

itemIndent ↔ double

Visual indent applied to items under section headers, in logical pixels. Forwards to TreeController.indentWidth.

getter/setter pair

itemKeyOf → K Function(Item item)

Extracts the item's stable key from its payload. Same role as sectionKeyOf.

final

preserveExpansion ↔ bool

getter/setter pair

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

sectionKeyOf → K Function(Section section)

Extracts the section's stable key from its payload. Captured at construction so all controller-side methods can convert user-supplied Section values into keys without callers having to pass the key explicitly.

final

treeController → TreeController<SecKey<K>, SecPayload<Section, Item>>

Underlying tree controller. Exposed for the widget's render layer (it must construct a SliverTree against this). Not part of the supported public API for end users — calling structural methods directly on the underlying tree bypasses the section/item type invariants this controller enforces.

no setter

Methods

addItem(Item item, {required K toSection, int? index, bool animate = true}) → void

Inserts item under toSection at index (or at the end).

addItemPayloadListener(void listener(K itemKey)) → void

Subscribes to item-payload changes. Fires after every successful updateItem call with the affected key. Inside runBatch, multiple updateItem(k, ...) calls for the same k produce a single callback at batch exit.

addListener(VoidCallback listener) → void

Subscribes to structural changes. Fires once per mutation (insert / remove / move / reorder / expand / collapse), or once per outermost runBatch regardless of how many structural mutations the body contained.

override

addSection(Section section, {int? index, Iterable<Item>? items, bool animate = true}) → void

Inserts section at index (or at the end when null). If items is non-empty they become the section's children — this initial child population is structural and does not animate per item; the section's own appearance respects animate.

addSectionPayloadListener(void listener(K sectionKey)) → void

Subscribes to section-payload changes. Fires after every successful updateSection call with the affected key. Inside runBatch, multiple updateSection(k, ...) calls for the same k produce a single callback at batch exit.

collapseAll({bool animate = true}) → void

collapseSection(K sectionKey, {bool animate = true}) → void

debugSnapshotCurrentChildren() → Map<K, List<K>>

Snapshots used by the widget's initial-expansion logic (mirrors the existing public hooks on TreeSyncController).

debugSnapshotRememberedSectionKeys() → Set<K>

dispose() → void

expandAll({bool animate = true}) → void

expandSection(K sectionKey, {bool animate = true}) → void

getItem(K itemKey) → Item?

getSection(K sectionKey) → Section?

hasItem(K itemKey) → bool

hasSection(K sectionKey) → bool

indexOfItem(K itemKey) → int

Position of itemKey among its section's children in live-list space (skipping pending-deletion siblings). Returns -1 when itemKey is not present, is itself pending-deletion, or is not an item.

isExpanded(K sectionKey) → bool

itemCount(K sectionKey) → int

Number of items currently belonging to sectionKey, regardless of expansion state. Returns 0 for unknown sections. Includes pending-deletion children — this is the count rendered by the header, since exit animations are still visible.

itemKeysOf(K sectionKey, {bool includeExiting = false}) → List<K>

Item keys under sectionKey in render order. Excludes pending-deletion items unless includeExiting is true.

itemsOf(K sectionKey, {bool includeExiting = false}) → List<Item>

Item payloads under sectionKey in render order. Excludes pending-deletion items unless includeExiting is true. Returns [] for unknown sections.

moveItem(K itemKey, {K? toSection, int? index}) → void

Repositions itemKey, either across sections or within its own.

moveSection(K sectionKey, int toIndex) → void

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

removeItem(K itemKey, {bool animate = true}) → void

removeItemPayloadListener(void listener(K itemKey)) → void

removeListener(VoidCallback listener) → void

Remove a previously registered closure from the list of closures that the object notifies.

override

removeSection(K sectionKey, {bool animate = true}) → void

removeSectionPayloadListener(void listener(K sectionKey)) → void

reorderItems(K sectionKey, List<K> orderedKeys) → void

reorderSections(List<K> orderedKeys) → void

runBatch<T>(T body()) → T

Coalesces structural notifications across the mutations performed inside body into a single post-batch refresh. Payload notifications are also coalesced and deduped by key. Delegates to the underlying TreeController.runBatch.

sectionKeys({bool includeExiting = false}) → List<K>

Section keys in render order. Excludes pending-deletion sections unless includeExiting is true.

sectionOf(K itemKey) → K?

sections({bool includeExiting = false}) → List<Section>

Section payloads in render order. Excludes sections currently mid-exit-animation unless includeExiting is true. The live form is the input shape reorderSections implicitly expects (via the keys returned by sectionKeys).

setItems(K sectionKey, Iterable<Item> items, {bool animate = true}) → void

Replaces all items under sectionKey. Diffs against current children and animates inserts/removes.

setSections(Iterable<Section> sections, {required Iterable<Item> itemsOf(Section section), bool animate = true}) → void

Replaces all sections. Diffs against current state and animates inserts, removes, and reparenting.

toggleSection(K sectionKey, {bool animate = true}) → void

toString() → String

A string representation of this object.

inherited

updateItem(K itemKey, Item item) → void

Updates itemKey's payload to item. Asserts that itemKey already exists. See updateSection for why the key is explicit.

updateSection(K sectionKey, Section section) → void

Updates sectionKey's payload to section without touching the section's items. Asserts that sectionKey already exists.

Operators

operator ==(Object other) → bool

The equality operator.

inherited