showTimeWithTimeZonePicker function

Future<TimeWithTimeZone?> showTimeWithTimeZonePicker({
  1. required BuildContext context,
  2. required TimeOfDay initialTime,
  3. TransitionBuilder? builder,
  4. bool barrierDismissible = true,
  5. Color? barrierColor,
  6. String? barrierLabel,
  7. bool useRootNavigator = true,
  8. TimePickerEntryMode initialEntryMode = TimePickerEntryMode.dial,
  9. String? cancelText,
  10. String? confirmText,
  11. String? helpText,
  12. String? errorInvalidText,
  13. String? hourLabelText,
  14. String? minuteLabelText,
  15. RouteSettings? routeSettings,
  16. EntryModeChangeCallback? onEntryModeChanged,
  17. Offset? anchorPoint,
  18. Orientation? orientation,
  19. bool enableTimeZone = true,
  20. TimeZoneShowType timeZoneShowType = TimeZoneShowType.nameAndOffset,
  21. TimeZoneType initTimeZoneType = TimeZoneType.fixedTime,
  22. TimeZoneData? initTimeZoneData,
  23. List<TimeZoneData>? customTimeZoneDataList,
  24. String? timeZoneTypeTitle,
  25. Icon? timeZoneHelpIcon,
  26. dynamic timeZoneHelpPressed()?,
  27. String? fixedTimeTitle,
  28. String? fixedTimeSubTitle,
  29. String? timeZoneTimeTitle,
  30. Icon? timeZoneSearchIcon,
  31. String? timeZoneSearchHint,
  32. String? removeFromHistoryTitle,
  33. String? removeFromHistoryContent,
  34. TextStyle? timeZoneSearchHintStyle,
})

Shows a dialog containing a Material Design time picker.

The returned Future resolves to the time selected by the user when the user closes the dialog. If the user cancels the dialog, null is returned.

{@tool snippet} Show a dialog with initialTime equal to the current time.

Future<TimeOfDay?> selectedTime = showTimePicker(
  initialTime: TimeOfDay.now(),
  context: context,
);

{@end-tool}

The context, barrierDismissible, barrierColor, barrierLabel, useRootNavigator and routeSettings arguments are passed to showDialog, the documentation for which discusses how it is used.

The builder parameter can be used to wrap the dialog widget to add inherited widgets like Localizations.override, Directionality, or MediaQuery.

The initialEntryMode parameter can be used to determine the initial time entry selection of the picker (either a clock dial or text input).

Optional strings for the helpText, cancelText, errorInvalidText, hourLabelText, minuteLabelText and confirmText can be provided to override the default values.

The optional orientation parameter sets the Orientation to use when displaying the dialog. By default, the orientation is derived from the MediaQueryData.size of the ambient MediaQuery: wide sizes use the landscape orientation, and tall sizes use the portrait orientation. Use this parameter to override the default and force the dialog to appear in either portrait or landscape mode.

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.

By default, the time picker gets its colors from the overall theme's ColorScheme. The time picker can be further customized by providing a TimePickerThemeData to the overall theme.

{@tool snippet} Show a dialog with the text direction overridden to be TextDirection.rtl.

Future<TimeOfDay?> selectedTimeRTL = showTimePicker(
  context: context,
  initialTime: TimeOfDay.now(),
  builder: (BuildContext context, Widget? child) {
    return Directionality(
      textDirection: TextDirection.rtl,
      child: child!,
    );
  },
);

{@end-tool}

{@tool snippet} Show a dialog with time unconditionally displayed in 24 hour format.

Future<TimeOfDay?> selectedTime24Hour = showTimePicker(
  context: context,
  initialTime: const TimeOfDay(hour: 10, minute: 47),
  builder: (BuildContext context, Widget? child) {
    return MediaQuery(
      data: MediaQuery.of(context).copyWith(alwaysUse24HourFormat: true),
      child: child!,
    );
  },
);

{@end-tool}

{@tool dartpad} This example illustrates how to open a time picker, and allows exploring some of the variations in the types of time pickers that may be shown.

** See code in examples/api/lib/material/time_picker/show_time_picker.0.dart ** {@end-tool}

See also:

Implementation

Future<TimeWithTimeZone?> showTimeWithTimeZonePicker({
  required BuildContext context,
  required TimeOfDay initialTime,
  TransitionBuilder? builder,
  bool barrierDismissible = true,
  Color? barrierColor,
  String? barrierLabel,
  bool useRootNavigator = true,
  TimePickerEntryMode initialEntryMode = TimePickerEntryMode.dial,
  String? cancelText,
  String? confirmText,
  String? helpText,
  String? errorInvalidText,
  String? hourLabelText,
  String? minuteLabelText,
  RouteSettings? routeSettings,
  EntryModeChangeCallback? onEntryModeChanged,
  Offset? anchorPoint,
  Orientation? orientation,
  bool enableTimeZone = true,
  TimeZoneShowType timeZoneShowType = TimeZoneShowType.nameAndOffset,
  TimeZoneType initTimeZoneType = TimeZoneType.fixedTime,
  TimeZoneData? initTimeZoneData,
  final List<TimeZoneData>? customTimeZoneDataList,
  String? timeZoneTypeTitle,
  Icon? timeZoneHelpIcon,
  Function()? timeZoneHelpPressed,
  String? fixedTimeTitle,
  String? fixedTimeSubTitle,
  String? timeZoneTimeTitle,
  Icon? timeZoneSearchIcon,
  String? timeZoneSearchHint,
  String? removeFromHistoryTitle,
  String? removeFromHistoryContent,
  TextStyle? timeZoneSearchHintStyle,
}) async {
  assert(debugCheckHasMaterialLocalizations(context));
  assert(initTimeZoneType == TimeZoneType.fixedTime || initTimeZoneData != null, "initTimeZoneType=timeZoneTime, initTimeZoneData must not be null");

  final Widget dialog = TimePickerDialog(
    initialTime: initialTime,
    initialEntryMode: initialEntryMode,
    cancelText: cancelText,
    confirmText: confirmText,
    helpText: helpText,
    enableTimeZone: enableTimeZone,
    timeZoneShowType: timeZoneShowType,
    initTimeZoneType: initTimeZoneType,
    initTimeZoneData: initTimeZoneData,
    customTimeZoneDataList: customTimeZoneDataList,
    timeZoneTypeTitle: timeZoneTypeTitle,
    timeZoneHelpIcon: timeZoneHelpIcon,
    timeZoneHelpPressed: timeZoneHelpPressed,
    fixedTimeTitle: fixedTimeTitle,
    fixedTimeSubTitle: fixedTimeSubTitle,
    timezoneTimeTitle: timeZoneTimeTitle,
    timeZoneSearchIcon: timeZoneSearchIcon,
    timeZoneSearchHint: timeZoneSearchHint,
    removeFromHistoryTitle: removeFromHistoryTitle,
    removeFromHistoryContent: removeFromHistoryContent,
    timeZoneSearchHintStyle: timeZoneSearchHintStyle,
    errorInvalidText: errorInvalidText,
    hourLabelText: hourLabelText,
    minuteLabelText: minuteLabelText,
    orientation: orientation,
    onEntryModeChanged: onEntryModeChanged,
  );
  return showDialog<TimeWithTimeZone>(
    context: context,
    barrierDismissible: barrierDismissible,
    barrierColor: barrierColor,
    barrierLabel: barrierLabel,
    useRootNavigator: useRootNavigator,
    builder: (BuildContext context) {
      return builder == null ? dialog : builder(context, dialog);
    },
    routeSettings: routeSettings,
    anchorPoint: anchorPoint,
  );
}