pushAndRemoveUntil<T extends Object> method

  1. @optionalTypeArgs
Future<T> pushAndRemoveUntil <T extends Object>(Route<T> newRoute, RoutePredicate predicate)
@optionalTypeArgs

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

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 NavigatorObservers.didPush and NavigatorObservers.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.

Returns a Future that completes to the result value passed to pop when the pushed route is popped off the navigator.

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

Typical usage is as follows:
void _resetAndOpenPage() {
  navigator.pushAndRemoveUntil(
    MaterialPageRoute(builder: (BuildContext context) => MyHomePage()),
    ModalRoute.withName('/'),
  );
}

Implementation

@optionalTypeArgs
Future<T> pushAndRemoveUntil<T extends Object>(Route<T> newRoute, RoutePredicate predicate) {
  assert(!_debugLocked);
  assert(() { _debugLocked = true; return true; }());

  // The route that is being pushed on top of
  final Route<dynamic> precedingRoute = _history.isNotEmpty ? _history.last : null;
  final OverlayEntry precedingRouteOverlay = _currentOverlayEntry;

  // Routes to remove
  final List<Route<dynamic>> removedRoutes = <Route<dynamic>>[];
  while (_history.isNotEmpty && !predicate(_history.last)) {
    final Route<dynamic> removedRoute = _history.removeLast();
    assert(removedRoute != null && removedRoute._navigator == this);
    assert(removedRoute.overlayEntries.isNotEmpty);
    removedRoutes.add(removedRoute);
  }

  // Push new route
  assert(newRoute._navigator == null);
  assert(newRoute.overlayEntries.isEmpty);
  final Route<dynamic> newPrecedingRoute = _history.isNotEmpty ? _history.last : null;
  newRoute._navigator = this;
  newRoute.install(precedingRouteOverlay);
  _history.add(newRoute);

  newRoute.didPush().whenCompleteOrCancel(() {
    if (mounted) {
      for (Route<dynamic> removedRoute in removedRoutes) {
        for (NavigatorObserver observer in widget.observers)
          observer.didRemove(removedRoute, newPrecedingRoute);
        removedRoute.dispose();
      }

      if (newPrecedingRoute != null)
        newPrecedingRoute.didChangeNext(newRoute);
    }
  });

  // Notify for newRoute
  newRoute.didChangeNext(null);
  for (NavigatorObserver observer in widget.observers)
    observer.didPush(newRoute, precedingRoute);

  assert(() { _debugLocked = false; return true; }());
  _afterNavigation(newRoute);
  return newRoute.popped;
}