restorablePushAndRemoveUntil<T extends Object?> method

  1. @optionalTypeArgs
String restorablePushAndRemoveUntil<T extends Object?>(
  1. RestorableRouteBuilder<T> newRouteBuilder,
  2. RoutePredicate predicate, {
  3. Object? arguments,
})

Push a new route onto the navigator, and then remove all the previous routes until the predicate returns true.

Unlike Routes pushed via pushAndRemoveUntil, Routes pushed with this method are restored during state restoration according to the rules outlined in the "State Restoration" section of Navigator.

The predicate may be applied to the same route more than once if Route.willHandlePopInternally is true.

To remove routes until a route with a certain name, use the RoutePredicate returned from ModalRoute.withName.

To remove all the routes below the pushed route, use a RoutePredicate that always returns false (e.g. (Route<dynamic> route) => false).

The removed routes are removed without being completed, so this method does not take a return value argument.

The newly pushed route and its preceding route are notified for Route.didPush. After removal, the new route and its new preceding route, (the route below the bottommost removed route) are notified through Route.didChangeNext). If the Navigator has any Navigator.observers, they will be notified as well (see NavigatorObserver.didPush and NavigatorObserver.didRemove). The removed routes are disposed of and notified, once the new route has finished animating. The futures that had been returned from pushing those routes will not complete.

Ongoing gestures within the current route are canceled when a new route is pushed.

The T type argument is the type of the return value of the new route.

The method takes a RestorableRouteBuilder as argument, which must be a static function annotated with @pragma('vm:entry-point'). It must instantiate and return a new Route object that will be added to the navigator. The provided arguments object is passed to the routeBuilder. The navigator calls the static routeBuilder function again during state restoration to re-create the route object.

Any object that is serializable via the StandardMessageCodec can be passed as arguments. Often, a Map is used to pass key-value pairs.

The method returns an opaque ID for the pushed route that can be used by the RestorableRouteFuture to gain access to the actual Route object added to the navigator and its return value. You can ignore the return value of this method, if you do not care about the route object or the route's return value.

Typical usage is as follows:
link

To create a local project with this code sample, run:
flutter create --sample=widgets.NavigatorState.restorablePushAndRemoveUntil.1 mysample

Implementation

@optionalTypeArgs
String restorablePushAndRemoveUntil<T extends Object?>(RestorableRouteBuilder<T> newRouteBuilder, RoutePredicate predicate, {Object? arguments}) {
  assert(_debugIsStaticCallback(newRouteBuilder), 'The provided routeBuilder must be a static function.');
  assert(debugIsSerializableForRestoration(arguments), 'The arguments object must be serializable via the StandardMessageCodec.');
  final _RouteEntry entry = _RestorationInformation.anonymous(
    routeBuilder: newRouteBuilder,
    arguments: arguments,
    restorationScopeId: _nextPagelessRestorationScopeId,
  ).toRouteEntry(this, initialState: _RouteLifecycle.push);
  _pushEntryAndRemoveUntil(entry, predicate);
  return entry.restorationId!;
}