ListController class

Navigation cursor and viewport state for a ListView.

Moving the cursor reveals its item. Scrolling leaves the cursor alone, and a rebuild preserves the viewport. Listeners receive changed viewport metrics after the frame, when visibleRange describes the rendered content.

Inheritance

Constructors

ListController({int? initialIndex = natural, bool followTail = false})
Starts with initialIndex as the current row and reveals it on mount. The index is clamped to the available items. natural, the default, starts on the first item, or on the last item when followTail is set; a following list's cursor then stays on the last item as items arrive, until something moves it. Null starts without a cursor. This does not select the row or take keyboard focus; use ListView.autofocus to request focus. An explicit viewport request or followTail takes precedence over reveal.

Properties

atEnd → bool
Whether the viewport shows the end of the content.
no setter
atStart → bool
Whether the viewport shows the start of the content.
no setter
currentIndex ↔ int?
The index of the current item (the list's cursor), or null when there is none. Setting it moves the cursor and scrolls that item into view without selecting it or taking focus. Values are clamped to the attached list.
getter/setter pair
followTail ↔ bool
Whether the list keeps its newest items in view as items are appended, like a log or chat feed. Scrolling away pauses following (isFollowing turns false) without turning this off, and returning to the end resumes it.
getter/setter pair
hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether at least one listener is registered.
no setterinherited
isFollowing → bool
Whether the list is following new items right now: true while followTail is on and the end of the list is in view. It is false while the user reads earlier items, even though followTail stays on.
no setter
itemCount → int
The number of items in the attached list.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scrollFraction → double
Approximate scrollbar position in 0..1. Unmeasured items count equally; partial visible items contribute their measured fraction. The endpoints always correspond to the start and end of the content.
no setter
unseenCount → int
How many items were appended since the end of the list was last in view, for a "new items" badge; zero while following. It resets when the end comes back into view or on jumpToEnd.
no setter
viewChanges → Listenable
Changes to the requested view: cursor, content refresh, or scroll requests.
no setter
visibleFraction → double
Fraction of the item collection visible, accounting for partially visible items. This is an estimate for variable-size items not yet measured.
no setter
visibleRange → ({int first, int last})?
Visible item indices, including partially visible items; null when empty or before layout. Items can span multiple cells along the scrolling axis.
no setter

Methods

addListener(VoidCallback listener) → void
Registers listener to be called when this object changes.
inherited
cursorFor({required int itemCount}) → int?
The cursor's index in the list of itemCount items: the one moveCursor placed for that count while the list has yet to show it, else currentIndex. An owner that rebuilds its items twice before a frame reads where the first rebuild put the cursor.
dispose() → void
Marks this notifier as disposed and drops its listeners. Nulls the slots in place (rather than replacing the backing list) so a dispose called from within a listener leaves any in-progress notify walk reading valid, now-empty slots. After disposal, addListener and notify throw; removeListener remains safe for cleanup.
override
jumpToEnd() → void
Scrolls to the end of the last item and clears unseenCount. With followTail on, following resumes and, as the End key does, the cursor moves back to the last item; otherwise the cursor stays where it is, and the list doesn't start following.
jumpToFraction(double fraction) → void
Scrolls to an approximate position given as a fraction of the whole list, as a scrollbar drag does: 0 is the start and 1 the end, exactly, even for a single oversized item. Values are clamped to 0..1, and a non-finite value throws an ArgumentError. Doesn't move the cursor, and pauses following.
jumpToIndex(int index) → void
Scrolls so the item at index starts the viewport, or as close as the end of the content allows. Doesn't move the cursor, and pauses following. The resulting position survives unrelated rebuilds.
listen(VoidCallback listener) → VoidCallback
Registers listener and returns an idempotent cancellation function.
inherited
moveCursor(int index, {required int itemCount}) → void
Sets currentIndex to index in a list about to show itemCount items.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notify() → void
Refreshes consumers after externally managed list content changes.
override
removeListener(VoidCallback listener) → void
Removes a previously-registered listener.
inherited
scrollBy(int delta) → void
Scrolls by delta cells along the list's axis (negative toward the start), including within an item taller than the viewport. Doesn't move the cursor, and pauses following.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

natural → const int
The default ListController.new initialIndex: the first item, or the last item for a list that follows its tail.