showCupertinoDialog<T> function
Null safety
- {required BuildContext context,
- required WidgetBuilder builder,
- String? barrierLabel,
- bool barrierDismissible = false,
- RouteSettings? routeSettings,
- Offset? anchorPoint}
Displays an iOS-style dialog above the current contents of the app, with iOS-style entrance and exit animations, modal barrier color, and modal barrier behavior (by default, the dialog is not dismissible with a tap on the barrier).
This function takes a builder
which typically builds a CupertinoAlertDialog
widget. Content below the dialog is dimmed with a ModalBarrier. The widget
returned by the builder
does not share a context with the location that
showCupertinoDialog
is originally called from. Use a StatefulBuilder or
a custom StatefulWidget if the dialog needs to update dynamically.
The context
argument is used to look up the Navigator for the dialog.
It is only used when the method is called. Its corresponding widget can
be safely removed from the tree before the dialog is closed.
The useRootNavigator
argument is used to determine whether to push the
dialog to the Navigator furthest from or nearest to the given context
.
By default, useRootNavigator
is true
and the dialog route created by
this method is pushed to the root navigator.
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.
If the application has multiple Navigator objects, it may be necessary to
call Navigator.of(context, rootNavigator: true).pop(result)
to close the
dialog rather than just Navigator.pop(context, result)
.
Returns a Future that resolves to the value (if any) that was passed to Navigator.pop when the dialog was closed.
State Restoration in Dialogs
Using this method will not enable state restoration for the dialog. In order to enable state restoration for a dialog, use Navigator.restorablePush or Navigator.restorablePushNamed with CupertinoDialogRoute.
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.showCupertinoDialog.1 mysample
See also:
- CupertinoAlertDialog, an iOS-style alert dialog.
- showDialog, which displays a Material-style dialog.
- showGeneralDialog, which allows for customization of the dialog popup.
- DisplayFeatureSubScreen, which documents the specifics of how DisplayFeatures can split the screen into sub-screens.
- developer.apple.com/ios/human-interface-guidelines/views/alerts/
Implementation
Future<T?> showCupertinoDialog<T>({
required BuildContext context,
required WidgetBuilder builder,
String? barrierLabel,
bool useRootNavigator = true,
bool barrierDismissible = false,
RouteSettings? routeSettings,
Offset? anchorPoint,
}) {
assert(builder != null);
assert(useRootNavigator != null);
return Navigator.of(context, rootNavigator: useRootNavigator).push<T>(CupertinoDialogRoute<T>(
builder: builder,
context: context,
barrierDismissible: barrierDismissible,
barrierLabel: barrierLabel,
barrierColor: CupertinoDynamicColor.resolve(kCupertinoModalBarrierColor, context),
settings: routeSettings,
anchorPoint: anchorPoint,
));
}