handlePopRoute method

  1. @protected
  2. @visibleForTesting
Future<bool> handlePopRoute()

Called when the system pops the current route.

This first notifies the binding observers (using WidgetsBindingObserver.didPopRoute), in registration order, until one returns true, meaning that it was able to handle the request (e.g. by closing a dialog box). If none return true, then the application is shut down by calling SystemNavigator.pop.

WidgetsApp uses this in conjunction with a Navigator to cause the back button to close dialog boxes, return from modal pages, and so forth.

This method exposes the popRoute notification from SystemChannels.navigation.

Handling backs ahead of time

Not all system backs will result in a call to this method. Some are handled entirely by the system without informing the Flutter framework.

Android API 33+ introduced a feature called predictive back, which allows the user to peek behind the current app or route during a back gesture and then decide to cancel or commit the back. Flutter enables or disables this feature ahead of time, before a back gesture occurs, and back gestures that trigger predictive back are handled entirely by the system and do not trigger this method here in the framework.

By default, the framework communicates when it would like to handle system back gestures using SystemNavigator.setFrameworkHandlesBack in WidgetsApp. This is done automatically based on the status of the Navigator stack and the state of any PopScope widgets present. Developers can manually set this by calling the method directly or by using NavigationNotification.

Implementation

@protected
@visibleForTesting
Future<bool> handlePopRoute() async {
  for (final WidgetsBindingObserver observer in List<WidgetsBindingObserver>.of(_observers)) {
    if (await observer.didPopRoute()) {
      return true;
    }
  }
  SystemNavigator.pop();
  return false;
}