show<T> static method
- required BuildContext context,
- required List<
CNAlertAction< actions,T> > - String? title,
- String? message,
- List<
CNAlertTextField> textFields = const <CNAlertTextField>[], - bool throwOnFailure = false,
- String? fontFamily,
- CNDialogTextStyle? titleStyle,
- CNDialogTextStyle? messageStyle,
- CNDialogTextStyle? actionStyle,
- TextDirection? textDirection,
Presents the alert and resolves to what the user answered.
Resolves to null when no answer was produced: the plugin is not registered, the native presentation failed (on macOS: no window to attach the sheet to), the fallback route was popped without a button press, or — on iOS and macOS — a second CNAlert.show superseded this one, taking its alert down and resolving this call to null. The Flutter fallback stacks instead: the earlier dialog stays up and resolves on its own button press. A pressed button — including a cancel button — always resolves to a CNAlertResult.
title and message are the alert's header. textFields adds one input
row each, in order, and their contents come back in
CNAlertResult.textFields.
Apple's Human Interface Guidelines recommend at most two buttons for an alert; more work, but stack vertically.
Asserts in debug, and returns null without presenting anything in release,
when actions is empty or every action is disabled — a .alert cannot be
dismissed by tapping outside, so every way out of it runs an action
handler. An alert with no button, or none that accepts a tap, can never be
dismissed and the returned future would never complete.
Also asserts against configurations UIKit cannot render: two actions with
CNAlertAction.isCancel (a hard NSInternalInconsistencyException), two
with CNAlertAction.isDefault, and a single action that is both cancel
and destructive.
An alert that can't be presented returns null by default, as a
dismissal does. With throwOnFailure, show throws the
PlatformException instead (code refused when UIKit didn't present
it, or no_presenter, presenter_busy, no_window), so the caller
can fall back to another UI (#135).
fontFamily draws the title, the message and the buttons in that
family, at the sizes and weights the system gives them; titleStyle,
messageStyle and actionStyle override one part (#144). The font
stays on through a press and while the dialog closes.
textDirection lays the dialog out right to left or left to right:
the title and message align to the matching edge and the buttons are
mirrored. Null takes the ambient Directionality, so an app that picks
Arabic in Dart gets a right-to-left native dialog (#144). On macOS the
buttons keep the system font: AppKit draws an alert's buttons itself.
Implementation
static Future<CNAlertResult<T>?> show<T>({
required BuildContext context,
required List<CNAlertAction<T>> actions,
String? title,
String? message,
List<CNAlertTextField> textFields = const <CNAlertTextField>[],
bool throwOnFailure = false,
String? fontFamily,
CNDialogTextStyle? titleStyle,
CNDialogTextStyle? messageStyle,
CNDialogTextStyle? actionStyle,
TextDirection? textDirection,
}) {
assert(
actions.isNotEmpty,
'CNAlert.show needs at least one action: an alert cannot be dismissed by '
'tapping outside, so one with no buttons never resolves.',
);
assert(
actions.any((a) => a.enabled),
'CNAlert.show needs at least one enabled action: an alert cannot be '
'dismissed by tapping outside, so one whose buttons all refuse taps '
'never resolves.',
);
assert(
actions.where((a) => a.isCancel).length <= 1,
'CNAlert.show accepts at most one action with isCancel: UIKit raises '
'NSInternalInconsistencyException on a second .cancel action.',
);
assert(
actions.where((a) => a.isDefault).length <= 1,
'CNAlert.show accepts at most one action with isDefault: '
'UIAlertController.preferredAction holds a single action.',
);
assert(
!actions.any((a) => a.isCancel && a.isDestructive),
'A CNAlertAction cannot be both isCancel and isDestructive: '
'UIAlertAction.Style is one value, so one of the two would be dropped.',
);
// `actions` is often built from a collection that can come out empty, and
// `enabled` is often computed per action from one flag that can be false for
// all of them. The native alert would then have no button that answers a
// tap and no dismissal path, so nothing could complete the call and the
// caller's await would hang for the life of the process. Answer it here
// instead of presenting a modal there is no way out of.
if (!actions.any((a) => a.enabled)) {
return Future<CNAlertResult<T>?>.value(null);
}
if (defaultTargetPlatform != TargetPlatform.iOS &&
defaultTargetPlatform != TargetPlatform.macOS) {
return _showFallback<T>(
context: context,
actions: actions,
title: title,
message: message,
textFields: textFields,
fontFamily: fontFamily,
titleStyle: titleStyle,
messageStyle: messageStyle,
actionStyle: actionStyle,
textDirection: textDirection,
);
}
return _showNative<T>(
textStyle: encodeDialogTextStyle(
context,
fontFamily: fontFamily,
title: titleStyle,
message: messageStyle,
action: actionStyle,
),
rtl: nativeRtl(context, textDirection),
actions: actions,
title: title,
message: message,
textFields: textFields,
// The app's theme, not the window's: a light app on a dark system gets
// a light alert, as CNActionSheet does. Null when the theme follows the
// system, so the native alert does too (#118).
isDark: context.mounted ? ThemeHelper.themeIsDark(context) : null,
throwOnFailure: throwOnFailure,
);
}