showCupertinoModalPopup<T> function
Null safety
- {required BuildContext context,
- required WidgetBuilder builder,
- ImageFilter? filter,
- Color barrierColor = kCupertinoModalBarrierColor,
- bool barrierDismissible = true,
- bool? semanticsDismissible,
- RouteSettings? routeSettings,
- 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 false
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
isOffset.zero
, which will cause the content to appear in the top-left sub-screen. - for TextDirection.rtl,
anchorPoint
isOffset(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.
To test state restoration on Android:
- 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.
- Run the code sample on an Android device.
- Create some in-memory state in the app on the phone, e.g. by navigating to a different screen.
- Background the Flutter app, then return to it. It will restart and restore its state.
To test state restoration on iOS:
- Open
ios/Runner.xcworkspace/
in Xcode. - (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.
- Press the Play button in Xcode to build and run the app.
- Create some in-memory state in the app on the phone, e.g. by navigating to a different screen.
- Background the app on the phone, e.g. by going back to the home screen.
- Press the Stop button in Xcode to terminate the app while running in the background.
- Open the app again on the phone (not via Xcode). It will restart and restore its state.
flutter create --sample=cupertino.showCupertinoModalPopup.1 mysample
See also:
- DisplayFeatureSubScreen, which documents the specifics of how DisplayFeatures can split the screen into sub-screens.
- CupertinoActionSheet, which is the widget usually returned by the
builder
argument to showCupertinoModalPopup. - developer.apple.com/design/human-interface-guidelines/ios/views/action-sheets/
Implementation
Future<T?> showCupertinoModalPopup<T>({
required BuildContext context,
required WidgetBuilder builder,
ImageFilter? filter,
Color barrierColor = kCupertinoModalBarrierColor,
bool barrierDismissible = true,
bool useRootNavigator = true,
bool? semanticsDismissible,
RouteSettings? routeSettings,
Offset? anchorPoint,
}) {
assert(useRootNavigator != null);
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,
),
);
}