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
-
- Object
- ChangeNotifier
- ValueNotifier<
PageableView< PageKey, Item> > - PageableController
- 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< pages, required PageableCallback<PageKey, Item> >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
nullif no pages are loaded.no setter - currentPageKey → PageKey?
-
Key of the last loaded page, or
nullif 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
markDisposedhas 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, andtoString.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
Itemtype argument, used in diagnostics. -
getPageKeyType(
) → Type -
The
PageKeytype 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
itemsas 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
operationas the latest controller activity.inherited -
triggerPageableDispose(
) → void -
Runs
onPageableDisposeunless it already ran.inherited -
triggerPageableInit(
) → void -
Runs
onPageableInitunless it already ran.inherited -
triggerPageableReady(
) → void -
Runs
onPageableReadyunless 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