Skip to content

TimeInput

Usage

import toga

current_time = toga.TimeInput()

Notes

  • This widget supports hours, minutes and seconds. Microseconds will always be returned as zero.
    • On Android and iOS, seconds will also be returned as zero, and any second component of a minimum or maximum value will be ignored.
  • Properties that return [datetime.time][] objects can also accept:
    • [datetime.datetime][]: The time portion will be extracted.
    • [str][]: Will be parsed as an ISO8601 format time string (e.g., "06:12").

Reference

Bases: Widget

Source code in core/src/toga/widgets/timeinput.py 
 21
 22
 23
 24
 25
 26
 27
 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
class TimeInput(Widget):
    def __init__(
        self,
        id: str | None = None,
        style: StyleT | None = None,
        value: datetime.time | None = None,
        min: datetime.time | None = None,
        max: datetime.time | None = None,
        on_change: toga.widgets.timeinput.OnChangeHandler | None = None,
        **kwargs,
    ):
        """Create a new TimeInput 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 time to display. If not specified, the current time
            will be used.
        :param min: The earliest time (inclusive) that can be selected.
        :param max: The latest time (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.TimeInput(interface=self)

    @property
    def value(self) -> datetime.time:
        """The currently selected time. A value of `None` will be converted into the
        current time.

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

    @value.setter
    def value(self, value: object) -> None:
        value = self._convert_time(value)

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

        self._impl.set_value(value)

    def _convert_time(self, value: object) -> datetime.time:
        if value is None:
            value = datetime.datetime.now().time()
        elif isinstance(value, datetime.datetime):
            value = value.time()
        elif isinstance(value, datetime.time):
            pass
        elif isinstance(value, str):
            value = datetime.time.fromisoformat(value)
        else:
            raise TypeError("Not a valid time value")

        return value.replace(microsecond=0)

    @property
    def min(self) -> datetime.time:
        """The minimum allowable time (inclusive). A value of `None` will be converted
        into 00:00:00.

        When setting this property, the current [`value`][toga.TimeInput.value] and
        [`max`][toga.TimeInput.max] will be
        clipped against the new minimum value.
        """
        return self._impl.get_min_time()

    @min.setter
    def min(self, value: object) -> None:
        if value is None:
            min = datetime.time(0, 0, 0)
        else:
            min = self._convert_time(value)

        if self.max < min:
            self._impl.set_max_time(min)
        self._impl.set_min_time(min)
        if self.value < min:
            self.value = min

    @property
    def max(self) -> datetime.time:
        """The maximum allowable time (inclusive). A value of `None` will be converted
        into 23:59:59.

        When setting this property, the current [`value`][toga.TimeInput.value] and
        [`min`][toga.TimeInput.min] will be
        clipped against the new maximum value.
        """
        return self._impl.get_max_time()

    @max.setter
    def max(self, value: object) -> None:
        if value is None:
            max = datetime.time(23, 59, 59)
        else:
            max = self._convert_time(value)

        if self.min > max:
            self._impl.set_min_time(max)
        self._impl.set_max_time(max)
        if self.value > max:
            self.value = max

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

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

max property writable

The maximum allowable time (inclusive). A value of None will be converted into 23:59:59.

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

min property writable

The minimum allowable time (inclusive). A value of None will be converted into 00:00:00.

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

on_change property writable

The handler to invoke when the time value changes.

value property writable

The currently selected time. A value of None will be converted into the current time.

If this property is set to a value outside of 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 TimeInput 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 time to display. If not specified, the current time will be used. :param min: The earliest time (inclusive) that can be selected. :param max: The latest time (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/timeinput.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(
    self,
    id: str | None = None,
    style: StyleT | None = None,
    value: datetime.time | None = None,
    min: datetime.time | None = None,
    max: datetime.time | None = None,
    on_change: toga.widgets.timeinput.OnChangeHandler | None = None,
    **kwargs,
):
    """Create a new TimeInput 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 time to display. If not specified, the current time
        will be used.
    :param min: The earliest time (inclusive) that can be selected.
    :param max: The latest time (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/timeinput.py 
12
13
14
15
16
17
18
class OnChangeHandler(Protocol):
    def __call__(self, widget: TimeInput, **kwargs: Any) -> None:
        """A handler to invoke when the time input is changed.

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

__call__(widget, **kwargs)

A handler to invoke when the time input is changed.

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

Source code in core/src/toga/widgets/timeinput.py 
13
14
15
16
17
18
def __call__(self, widget: TimeInput, **kwargs: Any) -> None:
    """A handler to invoke when the time input is changed.

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