ListNavigator class

Manages list navigation state (selection + viewport scrolling) for terminal and TUI experiences.

What problems it solves

Tracks the selected index independently of rendering code
Keeps a scroll offset so the selection always stays visible
Provides helper views (ListViewport, ListWindow) for cheap rendering
Wraps around at the boundaries so keyboard navigation "just works"

Usage

final nav = ListNavigator(itemCount: items.length, maxVisible: 10);

nav.moveBy(-1);  // up
nav.moveBy(1);   // down
nav.jumpTo(5);   // absolute jump

final visible = nav.visibleWindow(items);
for (final (offset, item) in visible.items.indexed) {
  final absoluteIndex = visible.start + offset;
  final isFocused = nav.isSelected(absoluteIndex);
  // render row
}

Power tips

Pair with SelectionController to support multi-select lists
Feed maxVisible with your terminal height to keep scroll math accurate
Use ListNavigator.viewport when you want to keep the original items list intact and only need index ranges for rendering

These docs surface every public API so downstream consumers on pub.dev can copy/paste examples without reading the source.

Constructors

ListNavigator({required int itemCount, required int maxVisible, int initialIndex = 0}): Creates a new list navigation state.

Properties

hashCode → int: The hash code for this object.
no setterinherited
hasOverflowAbove → bool: Whether there are items above the current viewport.
no setter
hasOverflowBelow → bool: Whether there are items below the current viewport.
no setter
isEmpty → bool: Whether the list is empty.
no setter
isNotEmpty → bool: Whether the list is not empty.
no setter
itemCount ↔ int: Total number of items.
getter/setter pair
maxVisible ↔ int: Maximum visible items (viewport size).
getter/setter pair
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scrollOffset → int: Current scroll offset (first visible item index).
no setter
selectedIndex → int: Current selected index.
no setter
viewport → ListViewport: Returns viewport information for rendering.
no setter

Methods

isSelected(int absoluteIndex) → bool: Checks if the given absolute index is currently selected.
jumpTo(int index) → void: Jumps to a specific index (clamped to valid range).
jumpToFirst() → void: Jumps to the first item.
jumpToLast() → void: Jumps to the last item.
moveBy(int delta) → void: Moves selection by delta positions with wrapping.
moveDown() → void: Moves selection down by one (with wrapping).
moveUp() → void: Moves selection up by one (with wrapping).
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
pageDown() → void: Moves viewport down by one page.
pageUp() → void: Moves viewport up by one page.
reset({int initialIndex = 0}) → void: Resets navigation to initial state (first item, no scroll).
toString() → String: A string representation of this object.
inherited
visibleWindow<T>(List<T> items) → ListWindow<T>: Returns a window of items from the given list based on current viewport.

Operators

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