PageableController<PageKey, Item> class

Controller that manages pagination state and data fetching logic.

Handles automatic calculation of pagination boundaries, manages fetch operations for first and subsequent pages, debounces rapid requests, and provides utilities to refresh, retry, and clear paged data.

Uses PageKey to identify pages and Item as the data type for items.

Extends ValueNotifier to notify listeners on pagination state changes.

Example usage:

final controller = PageableController<int, String>(
  fetchPage: (pageKey) async {
    // fetch items for pageKey from API or DB
  },
  getFirstPageKey: () => 1,
  getNextPageKey: (currentKey, items, totalLoaded) => currentKey + 1,
);
Inheritance
Mixed-in types
Implementers

Constructors

PageableController({required PageableCallback<PageKey, Item> fetchPage, required PageKey getFirstPageKey, NextPageKeyGenerator<PageKey, Item>? getNextPageKey, PreviousPageKeyGenerator<PageKey, Item>? getPreviousPageKey, required int pageSize, bool enabled = true, Object? reloadKey, bool resetOnReloadKeyChange = false, Duration? pollInterval, bool pausePollingWhenHidden = false, String? cacheKey, PageableCache<PageKey, Item>? cache, bool useSafeMode = true, int maxRetries = 0, Duration retryDelay = Duration.zero, PageableRetryIf? retryIf, PageableRetryDelayBuilder? retryDelayBuilder, PageableRetryCallback? onRetryAttempt, VoidCallback? onPageableInitCallback, VoidCallback? onPageableReadyCallback, VoidCallback? onPageableDisposeCallback, bool showLog = true, PageableLogger? logger})
Creates a PageableController with the given fetchers and configuration.
PageableController.fromPages({required List<PageResult<PageKey, Item>> pages, required PageableCallback<PageKey, Item> fetchPage, required PageKey getFirstPageKey, NextPageKeyGenerator<PageKey, Item>? getNextPageKey, PreviousPageKeyGenerator<PageKey, Item>? getPreviousPageKey, PageKey? nextPageKey, PageKey? prevPageKey, required int pageSize, bool enabled = true, Object? reloadKey, bool resetOnReloadKeyChange = false, Duration? pollInterval, bool pausePollingWhenHidden = false, String? cacheKey, PageableCache<PageKey, Item>? cache, bool useSafeMode = true, int maxRetries = 0, Duration retryDelay = Duration.zero, PageableRetryIf? retryIf, PageableRetryDelayBuilder? retryDelayBuilder, PageableRetryCallback? onRetryAttempt, VoidCallback? onPageableInitCallback, VoidCallback? onPageableReadyCallback, VoidCallback? onPageableDisposeCallback, bool showLog = false, PageableLogger? logger})
Creates a controller from an existing list of page results.

Properties

cache → PageableCache<PageKey, Item>?
Storage used with cacheKey for snapshot hydration and persistence.
final
cacheKey → String?
Cache key used to hydrate and persist pageable snapshots.
final
canFetchNextPage → bool
Whether the controller can fetch the next page.
no setter
canLoadPrevious → bool
Whether earlier pages can be fetched via fetchPreviousPage.
no setter
currentFirstPageKey → PageKey?
Key of the first loaded page, or null if no pages are loaded.
no setter
currentPageKey → PageKey?
Key of the last loaded page, or null if no pages are loaded.
no setter
debugLifecycleSummary → String
One-line summary of the controller lifecycle for logs and error reports.
no setterinherited
enabled → bool
Whether the controller is allowed to load automatically.
no setter
error → dynamic
Current error (if any) encountered during fetching.
no setter
hasData → bool
Whether any items have been loaded.
no setter
hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
isDisposed → bool
Whether markDisposed has run.
no setterinherited
isFetching → bool
Whether a fetch operation is currently in progress.
no setter
isLoading → bool
Whether any loading operation is currently reported in status.
no setter
itemList → List<Item>
Flattened list of all items loaded so far.
no setter
items → List<Item>
Flattened list of all items loaded so far (alias of itemList).
no setter
maxRetries → int
Maximum number of retry attempts for a single page fetch.
final
mounted → bool
Whether the controller is still usable (not disposed).
no setterinherited
onPageableDisposeCallback → VoidCallback?
Lifecycle callback invoked once during disposal.
final
onPageableInitCallback → VoidCallback?
Lifecycle callback invoked once after controller initialization.
final
onPageableReadyCallback → VoidCallback?
Lifecycle callback invoked once when controller is ready.
final
onRetryAttempt → PageableRetryCallback?
Optional callback invoked whenever a retry is scheduled.
final
pageable → PageableView<PageKey, Item>
Current pageable data, including all loaded pages and status.
no setter
pageSize → int
Expected number of items per page.
no setter
pausePollingWhenHidden → bool
Whether polling pauses while the app is in the background.
final
pollInterval → Duration?
Interval for automatically refreshing the first page.
final
reloadKey → Object?
The current external reload token (see setReloadKey).
no setter
resetOnReloadKeyChange → bool
Whether setReloadKey wipes visible state before reloading.
final
retryDelay → Duration
Fallback delay used between retry attempts when retryDelayBuilder is null.
final
retryDelayBuilder → PageableRetryDelayBuilder?
Optional callback to compute retry delay per attempt.
final
retryIf → PageableRetryIf?
Optional callback to control whether a specific error should be retried.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
status → PageableStatus
Current loading/error status.
no setter
uniqueId → Uuid
Unique identifier generated for this controller instance.
final
useSafeMode → bool
Enables mounted/disposed guards after async awaits.
final
value ↔ PageableView<PageKey, Item>
The current value stored in this notifier.
getter/setter pairinherited

Methods

addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
clear() → void
Clears all data and resets to initial state
debugAssertNotDisposed() → bool
Throws when the controller is used after disposal (debug builds only).
inherited
didChangeAccessibilityFeatures() → void
Called when the system changes the set of currently active accessibility features.
inherited
didChangeAppLifecycleState(AppLifecycleState state) → void
Called when the system puts the app in the background or returns the app to the foreground.
override
didChangeLocales(List<Locale>? locales) → void
Called when the system tells the app that the user's locale has changed. For example, if the user changes the system language settings.
inherited
didChangeMetrics() → void
Called when the application's dimensions change. For example, when a phone is rotated.
inherited
didChangePlatformBrightness() → void
Called when the platform brightness changes.
inherited
didChangeTextScaleFactor() → void
Called when the platform's text scale factor changes.
inherited
didChangeViewFocus(ViewFocusEvent event) → void
Called whenever the PlatformDispatcher receives a notification that the focus state on a view has changed.
inherited
didHaveMemoryPressure() → void
Called when the system is running low on memory.
inherited
didPopRoute() → Future<bool>
Called when the system tells the app to pop the current route, such as after a system back button press or back gesture.
inherited
didPushRoute(String route) → Future<bool>
Called when the host tells the application to push a new route onto the navigator.
inherited
didPushRouteInformation(RouteInformation routeInformation) → Future<bool>
Called when the host tells the application to push a new RouteInformation and a restoration state onto the router.
inherited
didRequestAppExit() → Future<AppExitResponse>
Called when a request is received from the system to exit the application.
inherited
dispose() → void
Discards any resources used by the object.
override
equalizedProperties() → List<Object?>
Mixin-style contract for value-based equality, hashCode, and toString.
override
fetchFirstPage() → Future<void>
Fetches the first page of data.
fetchNextPage() → Future<void>
Fetches the next page of data if available and not currently fetching.
fetchPreviousPage() → Future<void>
Fetches the page before the first loaded page, prepending its items.
getItemType() → Type
The Item type argument, used in diagnostics.
getPageKeyType() → Type
The PageKey type argument, used in diagnostics.
handleCancelBackGesture() → void
Called when a predictive back gesture is canceled, indicating that no navigation should occur.
inherited
handleCommitBackGesture() → void
Called when a predictive back gesture is finished successfully, indicating that the current route should be popped.
inherited
handleStartBackGesture(PredictiveBackEvent backEvent) → bool
Called at the start of a predictive back gesture.
inherited
handleStatusBarTap() → void
Called when the user taps the status bar on iOS, to scroll a scroll view to the top.
inherited
handleUpdateBackGestureProgress(PredictiveBackEvent backEvent) → void
Called when a predictive back gesture moves.
inherited
markDisposed() → void
Marks the controller as disposed, capturing when and where.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyItemListChanged() → void
Forces listeners to rebuild after in-place item mutations.
notifyListeners() → void
Call all the registered listeners.
inherited
onPageableDispose() → void
Invoked once when the controller is disposed.
onPageableInit() → void
Invoked once after the controller is constructed.
onPageableReady() → void
Invoked once when the controller is ready to load.
onPageableRetry(int attempt, Object error, StackTrace stackTrace, Duration delay) → void
Invoked every time a fetch retry is scheduled.
persistCacheSnapshot() → void
Persists the current snapshot to cache for subclasses.
refresh() → Future<void>
Refreshes the data by reloading it from a clean first-page state.
refreshSilently() → Future<void>
Refreshes the first page while keeping the currently visible items.
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
replaceSnapshot({required List<Item> items, PageKey? pageKey, PageKey? nextPageKey, PageKey? prevPageKey, PageableStatus? status, bool? showLog, int? pageSize}) → Future<void>
Replaces the entire pageable state with items as a single page.
retry() → Future<void>
Retries the last failed fetch operation.
setEnabled(bool enabled) → Future<void>
Enables or disables automatic loading.
setReloadKey(Object? key, {bool? reset}) → Future<void>
Updates the external reload token, retriggering the first-page load.
startPolling() → void
Starts automatic refreshSilently polling on pollInterval.
stopPolling() → void
Stops automatic refreshSilently polling started by startPolling.
toString() → String
A string representation of this object.
inherited
trackOperation(String operation) → void
Records operation as the latest controller activity.
inherited
triggerPageableDispose() → void
Runs onPageableDispose unless it already ran.
inherited
triggerPageableInit() → void
Runs onPageableInit unless it already ran.
inherited
triggerPageableReady() → void
Runs onPageableReady unless it already ran.
inherited
triggerPageableRetry(int attempt, Object error, StackTrace stackTrace, Duration delay) → void
Forwards a scheduled retry to onPageableRetry.
inherited

Operators

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