showCupertinoModalPopup<T> function

Future<T?> showCupertinoModalPopup<T>({
  1. required BuildContext context,
  2. required WidgetBuilder builder,
  3. ImageFilter? filter,
  4. Color barrierColor = kCupertinoModalBarrierColor,
  5. bool barrierDismissible = true,
  6. bool useRootNavigator = true,
  7. bool semanticsDismissible = false,
  8. RouteSettings? routeSettings,
  9. Offset? anchorPoint,
})

Shows a modal iOS-style popup that slides up from the bottom of the screen.

Such a popup is an alternative to a menu or a dialog and prevents the user from interacting with the rest of the app.

The context argument is used to look up the Navigator for the popup. It is only used when the method is called. Its corresponding widget can be safely removed from the tree before the popup is closed.

The barrierColor argument determines the Color of the barrier underneath the popup. When unspecified, the barrier color defaults to a light opacity black scrim based on iOS's dialog screens.

The barrierDismissible argument determines whether clicking outside the popup results in dismissal. It is true by default.

The useRootNavigator argument is used to determine whether to push the popup to the Navigator furthest from or nearest to the given context. It is true by default.

The semanticsDismissible argument is used to determine whether the semantics of the modal barrier are included in the semantics tree.

The routeSettings argument is used to provide RouteSettings to the created Route.

The builder argument typically builds a CupertinoActionSheet widget. Content below the widget is dimmed with a ModalBarrier. The widget built by the builder does not share a context with the location that showCupertinoModalPopup is originally called from. Use a StatefulBuilder or a custom StatefulWidget if the widget needs to update dynamically.

A DisplayFeature can split the screen into sub-screens. The closest one to anchorPoint is used to render the content.

If no anchorPoint is provided, then Directionality is used:

  • for TextDirection.ltr, anchorPoint is Offset.zero, which will cause the content to appear in the top-left sub-screen.
  • for TextDirection.rtl, anchorPoint is Offset(double.maxFinite, 0), which will cause the content to appear in the top-right sub-screen.

If no anchorPoint is provided, and there is no Directionality ancestor widget in the tree, then the widget asserts during build in debug mode.

Returns a Future that resolves to the value that was passed to Navigator.pop when the popup was closed.

State Restoration in Modals

Using this method will not enable state restoration for the modal. In order to enable state restoration for a modal, use Navigator.restorablePush or Navigator.restorablePushNamed with CupertinoModalPopupRoute.

For more information about state restoration, see RestorationManager.

This sample demonstrates how to create a restorable Cupertino modal route. This is accomplished by enabling state restoration by specifying CupertinoApp.restorationScopeId and using Navigator.restorablePush to push CupertinoModalPopupRoute when the CupertinoButton is tapped.

To test state restoration on Android:

  1. Turn on "Don't keep activities", which destroys the Android activity as soon as the user leaves it. This option should become available when Developer Options are turned on for the device.
  2. Run the code sample on an Android device.
  3. Create some in-memory state in the app on the phone, e.g. by navigating to a different screen.
  4. Background the Flutter app, then return to it. It will restart and restore its state.

To test state restoration on iOS:

  1. Open ios/Runner.xcworkspace/ in Xcode.
  2. (iOS 14+ only): Switch to build in profile or release mode, as launching an app from the home screen is not supported in debug mode.
  3. Press the Play button in Xcode to build and run the app.
  4. Create some in-memory state in the app on the phone, e.g. by navigating to a different screen.
  5. Background the app on the phone, e.g. by going back to the home screen.
  6. Press the Stop button in Xcode to terminate the app while running in the background.
  7. Open the app again on the phone (not via Xcode). It will restart and restore its state.
link

To create a local project with this code sample, run:
flutter create --sample=cupertino.showCupertinoModalPopup.1 mysample

See also:

Implementation

Future<T?> showCupertinoModalPopup<T>({
  required BuildContext context,
  required WidgetBuilder builder,
  ImageFilter? filter,
  Color barrierColor = kCupertinoModalBarrierColor,
  bool barrierDismissible = true,
  bool useRootNavigator = true,
  bool semanticsDismissible = false,
  RouteSettings? routeSettings,
  Offset? anchorPoint,
}) {
  return Navigator.of(context, rootNavigator: useRootNavigator).push(
    CupertinoModalPopupRoute<T>(
      builder: builder,
      filter: filter,
      barrierColor: CupertinoDynamicColor.resolve(barrierColor, context),
      barrierDismissible: barrierDismissible,
      semanticsDismissible: semanticsDismissible,
      settings: routeSettings,
      anchorPoint: anchorPoint,
    ),
  );
}