showDateRangePicker function

Future<DateTimeRange> showDateRangePicker (
  1. {@required BuildContext context,
  2. DateTimeRange initialDateRange,
  3. @required DateTime firstDate,
  4. @required DateTime lastDate,
  5. DateTime currentDate,
  6. DatePickerEntryMode initialEntryMode: DatePickerEntryMode.calendar,
  7. String helpText,
  8. String cancelText,
  9. String confirmText,
  10. String saveText,
  11. String errorFormatText,
  12. String errorInvalidText,
  13. String errorInvalidRangeText,
  14. String fieldStartHintText,
  15. String fieldEndHintText,
  16. String fieldStartLabelText,
  17. String fieldEndLabelText,
  18. Locale locale,
  19. bool useRootNavigator: true,
  20. RouteSettings routeSettings,
  21. TextDirection textDirection,
  22. TransitionBuilder builder}
)

Shows a full screen modal dialog containing a Material Design date range picker.

The returned Future resolves to the DateTimeRange selected by the user when the user saves their selection. If the user cancels the dialog, null is returned.

If initialDateRange is non-null, then it will be used as the initially selected date range. If it is provided, initialDateRange.start must be before or on initialDateRange.end.

The firstDate is the earliest allowable date. The lastDate is the latest allowable date. Both must be non-null.

If an initial date range is provided, initialDateRange.start and initialDateRange.end must both fall between or on firstDate and lastDate. For all of these DateTime values, only their dates are considered. Their time fields are ignored.

The currentDate represents the current day (i.e. today). This date will be highlighted in the day grid. If null, the date of DateTime.now() will be used.

An optional initialEntryMode argument can be used to display the date picker in the DatePickerEntryMode.calendar (a scrollable calendar month grid) or DatePickerEntryMode.input (two text input fields) mode. It defaults to DatePickerEntryMode.calendar and must be non-null.

The following optional string parameters allow you to override the default text used for various parts of the dialog:

  • helpText, the label displayed at the top of the dialog.
  • cancelText, the label on the cancel button for the text input mode.
  • confirmText,the label on the ok button for the text input mode.
  • saveText, the label on the save button for the fullscreen calendar mode.
  • errorFormatText, the message used when an input text isn't in a proper date format.
  • errorInvalidText, the message used when an input text isn't a selectable date.
  • errorInvalidRangeText, the message used when the date range is invalid (e.g. start date is after end date).
  • fieldStartHintText, the text used to prompt the user when no text has been entered in the start field.
  • fieldEndHintText, the text used to prompt the user when no text has been entered in the end field.
  • fieldStartLabelText, the label for the start date text input field.
  • fieldEndLabelText, the label for the end date text input field.

An optional locale argument can be used to set the locale for the date picker. It defaults to the ambient locale provided by Localizations.

An optional textDirection argument can be used to set the text direction (TextDirection.ltr or TextDirection.rtl) for the date picker. It defaults to the ambient text direction provided by Directionality. If both locale and textDirection are non-null, textDirection overrides the direction chosen for the locale.

The context, useRootNavigator and routeSettings arguments are passed to showDialog, the documentation for which discusses how it is used. context and useRootNavigator must be non-null.

The builder parameter can be used to wrap the dialog widget to add inherited widgets like Theme.

See also:

  • showDatePicker, which shows a material design date picker used to select a single date.
  • DateTimeRange, which is used to describe a date range.

Implementation

Future<DateTimeRange> showDateRangePicker({
  @required BuildContext context,
  DateTimeRange initialDateRange,
  @required DateTime firstDate,
  @required DateTime lastDate,
  DateTime currentDate,
  DatePickerEntryMode initialEntryMode = DatePickerEntryMode.calendar,
  String helpText,
  String cancelText,
  String confirmText,
  String saveText,
  String errorFormatText,
  String errorInvalidText,
  String errorInvalidRangeText,
  String fieldStartHintText,
  String fieldEndHintText,
  String fieldStartLabelText,
  String fieldEndLabelText,
  Locale locale,
  bool useRootNavigator = true,
  RouteSettings routeSettings,
  TextDirection textDirection,
  TransitionBuilder builder,
}) async {
    assert(context != null);
    assert(
      initialDateRange == null || (initialDateRange.start != null && initialDateRange.end != null),
      'initialDateRange must be null or have non-null start and end dates.'
    );
    assert(
      initialDateRange == null || !initialDateRange.start.isAfter(initialDateRange.end),
      'initialDateRange\'s start date must not be after it\'s end date.'
    );
    initialDateRange = initialDateRange == null ? null : utils.datesOnly(initialDateRange);
    assert(firstDate != null);
    firstDate = utils.dateOnly(firstDate);
    assert(lastDate != null);
    lastDate = utils.dateOnly(lastDate);
    assert(
      !lastDate.isBefore(firstDate),
      'lastDate $lastDate must be on or after firstDate $firstDate.'
    );
    assert(
      initialDateRange == null || !initialDateRange.start.isBefore(firstDate),
      'initialDateRange\'s start date must be on or after firstDate $firstDate.'
    );
    assert(
      initialDateRange == null || !initialDateRange.end.isBefore(firstDate),
      'initialDateRange\'s end date must be on or after firstDate $firstDate.'
    );
    assert(
      initialDateRange == null || !initialDateRange.start.isAfter(lastDate),
      'initialDateRange\'s start date must be on or before lastDate $lastDate.'
    );
    assert(
      initialDateRange == null || !initialDateRange.end.isAfter(lastDate),
      'initialDateRange\'s end date must be on or before lastDate $lastDate.'
    );
    currentDate = utils.dateOnly(currentDate ?? DateTime.now());
    assert(initialEntryMode != null);
    assert(useRootNavigator != null);
    assert(debugCheckHasMaterialLocalizations(context));

  Widget dialog = _DateRangePickerDialog(
    initialDateRange: initialDateRange,
    firstDate: firstDate,
    lastDate: lastDate,
    currentDate: currentDate,
    initialEntryMode: initialEntryMode,
    helpText: helpText,
    cancelText: cancelText,
    confirmText: confirmText,
    saveText: saveText,
    errorFormatText: errorFormatText,
    errorInvalidText: errorInvalidText,
    errorInvalidRangeText: errorInvalidRangeText,
    fieldStartHintText: fieldStartHintText,
    fieldEndHintText: fieldEndHintText,
    fieldStartLabelText: fieldStartLabelText,
    fieldEndLabelText: fieldEndLabelText,
  );

  if (textDirection != null) {
    dialog = Directionality(
      textDirection: textDirection,
      child: dialog,
    );
  }

  if (locale != null) {
    dialog = Localizations.override(
      context: context,
      locale: locale,
      child: dialog,
    );
  }

  return showDialog<DateTimeRange>(
    context: context,
    useRootNavigator: useRootNavigator,
    routeSettings: routeSettings,
    useSafeArea: false,
    builder: (BuildContext context) {
      return builder == null ? dialog : builder(context, dialog);
    },
  );
}