Skip to content

DateInput

Usage

import toga

current_date = toga.DateInput()

Notes

  • This widget supports years from 1800 to 8999 inclusive.
  • Properties that return [datetime.date][] objects can also accept:
    • [datetime.datetime][]: The date portion will be extracted.
    • [str][]: Will be parsed as an ISO8601 format date string (e.g., "2023-12-25").
  • On iOS, style directives for changing the widget's color and background color will be ignored. Apple advises against customizing the look and feel of date pickers; as a result, they don't expose APIs to change the color of date widgets.

Reference

Bases: Widget

Source code in core/src/toga/widgets/dateinput.py 
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class DateInput(Widget):
    _MIN_WIDTH = 200

    def __init__(
        self,
        id: str | None = None,
        style: StyleT | None = None,
        value: datetime.date | None = None,
        min: datetime.date | None = None,
        max: datetime.date | None = None,
        on_change: toga.widgets.dateinput.OnChangeHandler | None = None,
        **kwargs,
    ):
        """Create a new DateInput widget.

        :param id: The ID for the widget.
        :param style: A style object. If no style is provided, a default style
            will be applied to the widget.
        :param value: The initial date to display. If not specified, the current date
            will be used.
        :param min: The earliest date (inclusive) that can be selected.
        :param max: The latest date (inclusive) that can be selected.
        :param on_change: A handler that will be invoked when the value changes.
        :param kwargs: Initial style properties.
        """
        super().__init__(id, style, **kwargs)

        self.on_change = None
        self.min = min
        self.max = max

        self.value = value
        self.on_change = on_change

    def _create(self) -> Any:
        return self.factory.DateInput(interface=self)

    @property
    def value(self) -> datetime.date:
        """The currently selected date. A value of `None` will be converted into
        today's date.

        If this property is set to a value outside the min/max range, it will be
        clipped.
        """
        return self._impl.get_value()

    @value.setter
    def value(self, value: object) -> None:
        value = self._convert_date(value, check_range=False)

        if value < self.min:
            value = self.min
        elif value > self.max:
            value = self.max

        self._impl.set_value(value)

    def _convert_date(self, value: object, *, check_range: bool) -> datetime.date:
        if value is None:
            value = datetime.date.today()
        elif isinstance(value, datetime.datetime):
            value = value.date()
        elif isinstance(value, datetime.date):
            pass
        elif isinstance(value, str):
            value = datetime.date.fromisoformat(value)
        else:
            raise TypeError("Not a valid date value")

        if check_range:
            if value < MIN_DATE:
                raise ValueError(f"The lowest supported date is {MIN_DATE.isoformat()}")
            if value > MAX_DATE:
                raise ValueError(
                    f"The highest supported date is {MAX_DATE.isoformat()}"
                )

        return value

    @property
    def min(self) -> datetime.date:
        """The minimum allowable date (inclusive). A value of `None` will be converted
        into the lowest supported date of 1800-01-01.

        When setting this property, the current [`value`][toga.DateInput.value] and
        [`max`][toga.DateInput.max] will be
        clipped against the new minimum value.

        :raises ValueError: If set to a date outside the supported range.
        """
        return self._impl.get_min_date()

    @min.setter
    def min(self, value: object) -> None:
        if value is None:
            min = MIN_DATE
        else:
            min = self._convert_date(value, check_range=True)

        if self.max < min:
            self._impl.set_max_date(min)
        self._impl.set_min_date(min)
        if self.value < min:
            self.value = min

    @property
    def max(self) -> datetime.date:
        """The maximum allowable date (inclusive). A value of `None` will be converted
        into the highest supported date of 8999-12-31.

        When setting this property, the current [`value`][toga.DateInput.value] and
        [`min`][toga.DateInput.min] will be
        clipped against the new maximum value.

        :raises ValueError: If set to a date outside the supported range.
        """
        return self._impl.get_max_date()

    @max.setter
    def max(self, value: object) -> None:
        if value is None:
            max = MAX_DATE
        else:
            max = self._convert_date(value, check_range=True)

        if self.min > max:
            self._impl.set_min_date(max)
        self._impl.set_max_date(max)
        if self.value > max:
            self.value = max

    @property
    def on_change(self) -> OnChangeHandler:
        """The handler to invoke when the date value changes."""
        return self._on_change

    @on_change.setter
    def on_change(self, handler: toga.widgets.dateinput.OnChangeHandler) -> None:
        self._on_change = wrapped_handler(self, handler)

max property writable

The maximum allowable date (inclusive). A value of None will be converted into the highest supported date of 8999-12-31.

When setting this property, the current value and min will be clipped against the new maximum value.

:raises ValueError: If set to a date outside the supported range.

min property writable

The minimum allowable date (inclusive). A value of None will be converted into the lowest supported date of 1800-01-01.

When setting this property, the current value and max will be clipped against the new minimum value.

:raises ValueError: If set to a date outside the supported range.

on_change property writable

The handler to invoke when the date value changes.

value property writable

The currently selected date. A value of None will be converted into today's date.

If this property is set to a value outside the min/max range, it will be clipped.

__init__(id=None, style=None, value=None, min=None, max=None, on_change=None, **kwargs)

Create a new DateInput widget.

:param id: The ID for the widget. :param style: A style object. If no style is provided, a default style will be applied to the widget. :param value: The initial date to display. If not specified, the current date will be used. :param min: The earliest date (inclusive) that can be selected. :param max: The latest date (inclusive) that can be selected. :param on_change: A handler that will be invoked when the value changes. :param kwargs: Initial style properties.

Source code in core/src/toga/widgets/dateinput.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def __init__(
    self,
    id: str | None = None,
    style: StyleT | None = None,
    value: datetime.date | None = None,
    min: datetime.date | None = None,
    max: datetime.date | None = None,
    on_change: toga.widgets.dateinput.OnChangeHandler | None = None,
    **kwargs,
):
    """Create a new DateInput widget.

    :param id: The ID for the widget.
    :param style: A style object. If no style is provided, a default style
        will be applied to the widget.
    :param value: The initial date to display. If not specified, the current date
        will be used.
    :param min: The earliest date (inclusive) that can be selected.
    :param max: The latest date (inclusive) that can be selected.
    :param on_change: A handler that will be invoked when the value changes.
    :param kwargs: Initial style properties.
    """
    super().__init__(id, style, **kwargs)

    self.on_change = None
    self.min = min
    self.max = max

    self.value = value
    self.on_change = on_change

Bases: Protocol

Source code in core/src/toga/widgets/dateinput.py 
19
20
21
22
23
24
25
class OnChangeHandler(Protocol):
    def __call__(self, widget: DateInput, **kwargs: Any) -> None:
        """A handler that will be invoked when a change occurs.

        :param widget: The DateInput that was changed.
        :param kwargs: Ensures compatibility with arguments added in future versions.
        """

__call__(widget, **kwargs)

A handler that will be invoked when a change occurs.

:param widget: The DateInput that was changed. :param kwargs: Ensures compatibility with arguments added in future versions.

Source code in core/src/toga/widgets/dateinput.py 
20
21
22
23
24
25
def __call__(self, widget: DateInput, **kwargs: Any) -> None:
    """A handler that will be invoked when a change occurs.

    :param widget: The DateInput that was changed.
    :param kwargs: Ensures compatibility with arguments added in future versions.
    """