:github_url: https://github.com/kivymd/KivyMD/blob/master/kivymd/uix/pickers/timepicker/timepicker.py TimePicker ========== .. py:module:: kivymd.uix.pickers.timepicker.timepicker .. autoapi-nested-parse:: Components/TimePicker ===================== .. seealso:: `Material Design spec, Date picker `_ .. rubric:: Time pickers help users select and set a specific time. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker.png :align: center - Time pickers are modal and cover the main content - Two types: dial and input - Users can select hours, minutes, or periods of time - Make sure time can easily be selected by hand on a mobile device .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-types.png :align: center 1. Vertical dial time picker 2. Horizontal dial time picker 3. Time picker input KivyMD provides the following date pickers classes for use: - MDTimePickerDialVertical_ - MDTimePickerDialHorizontal_ - MDTimePickerInput_ .. _MDTimePickerDialVertical: MDTimePickerDialVertical ------------------------ Time pickers allow people to enter a specific time value. They’re displayed in dialogs and can be used to select hours, minutes, or periods of time. They can be used for a wide range of scenarios. Common use cases include: - Setting an alarm - Scheduling a meeting Time pickers are not ideal for nuanced or granular time selection, such as milliseconds for a stopwatch application. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/vertical-time-picker-preview.gif :align: center .. tabs:: .. tab:: Declarative KV style .. code-block:: python from kivy.lang import Builder from kivymd.app import MDApp from kivymd.uix.pickers import MDTimePickerDialVertical KV = ''' MDScreen: md_bg_color: self.theme_cls.backgroundColor MDButton: pos_hint: {'center_x': .5, 'center_y': .5} on_release: app.show_time_picker() MDButtonText: text: "Open time picker" ''' class Example(MDApp): def build(self): self.theme_cls.theme_style = "Dark" return Builder.load_string(KV) def show_time_picker(self): time_picker = MDTimePickerDialVertical() time_picker.open() Example().run() .. tab:: Declarative Python style .. code-block:: python from kivymd.app import MDApp from kivymd.uix.button import MDButton, MDButtonText from kivymd.uix.pickers import MDTimePickerDialVertical from kivymd.uix.screen import MDScreen class Example(MDApp): def build(self): self.theme_cls.theme_style = "Dark" return ( MDScreen( MDButton( MDButtonText( text="Open time picker", ), pos_hint={'center_x': .5, 'center_y': .5}, on_release=self.show_time_picker, ), md_bg_color=self.theme_cls.backgroundColor, ) ) def show_time_picker(self, *args): time_picker = MDTimePickerDialVertical() time_picker.open() Example().run() .. _MDTimePickerDialHorizontal: MDTimePickerDialHorizontal -------------------------- The clock dial interface adapts to a device’s orientation. In landscape mode, the stacked input and selection options are positioned side-by-side. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/horizontal-time-picker-preview.gif :align: center .. code-block:: python def show_time_picker(self): MDTimePickerDialHorizontal().open() .. note:: You must control the orientation of the time picker yourself. .. tabs:: .. tab:: Declarative KV style .. code-block:: python from typing import Literal from kivy.clock import Clock from kivy.lang import Builder from kivy.properties import ObjectProperty from kivymd.app import MDApp from kivymd.theming import ThemeManager from kivymd.uix.pickers import ( MDTimePickerDialHorizontal, MDTimePickerDialVertical, ) KV = ''' MDScreen: md_bg_color: self.theme_cls.backgroundColor MDButton: pos_hint: {'center_x': .5, 'center_y': .5} on_release: app.open_time_picker_horizontal("1", "10") if self.theme_cls.device_orientation == "landscape" else app.open_time_picker_vertical("1", "10") MDButtonText: text: "Open time picker" ''' class Example(MDApp): ORIENTATION = Literal["portrait", "landscape"] time_picker_horizontal: MDTimePickerDialHorizontal = ObjectProperty( allownone=True ) time_picker_vertical: MDTimePickerDialHorizontal = ObjectProperty( allownone=True ) def build(self): self.theme_cls.theme_style = "Dark" self.theme_cls.bind(device_orientation=self.check_orientation) return Builder.load_string(KV) def check_orientation( self, instance: ThemeManager, orientation: ORIENTATION ): if orientation == "portrait" and self.time_picker_horizontal: self.time_picker_horizontal.dismiss() hour = str(self.time_picker_horizontal.time.hour) minute = str(self.time_picker_horizontal.time.minute) Clock.schedule_once( lambda x: self.open_time_picker_vertical(hour, minute), 0.1, ) elif orientation == "landscape" and self.time_picker_vertical: self.time_picker_vertical.dismiss() hour = str(self.time_picker_vertical.time.hour) minute = str(self.time_picker_vertical.time.minute) Clock.schedule_once( lambda x: self.open_time_picker_horizontal(hour, minute), 0.1, ) def open_time_picker_horizontal(self, hour, minute): self.time_picker_vertical = None self.time_picker_horizontal = MDTimePickerDialHorizontal( hour=hour, minute=minute ) self.time_picker_horizontal.open() def open_time_picker_vertical(self, hour, minute): self.time_picker_horizontal = None self.time_picker_vertical = MDTimePickerDialVertical( hour=hour, minute=minute ) self.time_picker_vertical.open() Example().run() .. tab:: Declarative Python style .. code-block:: python from typing import Literal from kivy.clock import Clock from kivy.properties import ObjectProperty from kivymd.app import MDApp from kivymd.theming import ThemeManager from kivymd.uix.button import MDButton, MDButtonText from kivymd.uix.pickers import ( MDTimePickerDialHorizontal, MDTimePickerDialVertical, ) from kivymd.uix.screen import MDScreen class Example(MDApp): ORIENTATION = Literal["portrait", "landscape"] time_picker_horizontal: MDTimePickerDialHorizontal = ObjectProperty( allownone=True ) time_picker_vertical: MDTimePickerDialHorizontal = ObjectProperty( allownone=True ) def build(self): self.theme_cls.theme_style = "Dark" self.theme_cls.bind(device_orientation=self.check_orientation) return MDScreen( MDButton( MDButtonText( text="Open time picker", ), pos_hint={"center_x": 0.5, "center_y": 0.5}, on_release=self.show_time_picker, ), md_bg_color=self.theme_cls.backgroundColor, ) def show_time_picker(self, *args): ( self.open_time_picker_horizontal("1", "10") if self.theme_cls.device_orientation == "landscape" else self.open_time_picker_vertical("1", "10") ) def check_orientation( self, instance: ThemeManager, orientation: ORIENTATION ): if orientation == "portrait" and self.time_picker_horizontal: self.time_picker_horizontal.dismiss() hour = str(self.time_picker_horizontal.time.hour) minute = str(self.time_picker_horizontal.time.minute) Clock.schedule_once( lambda x: self.open_time_picker_vertical(hour, minute), 0.1, ) elif orientation == "landscape" and self.time_picker_vertical: self.time_picker_vertical.dismiss() hour = str(self.time_picker_vertical.time.hour) minute = str(self.time_picker_vertical.time.minute) Clock.schedule_once( lambda x: self.open_time_picker_horizontal(hour, minute), 0.1, ) def open_time_picker_horizontal(self, hour, minute): self.time_picker_vertical = None self.time_picker_horizontal = MDTimePickerDialHorizontal( hour=hour, minute=minute ) self.time_picker_horizontal.open() def open_time_picker_vertical(self, hour, minute): self.time_picker_horizontal = None self.time_picker_vertical = MDTimePickerDialVertical( hour=hour, minute=minute ) self.time_picker_vertical.open() Example().run() .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-control-orientation.gif :align: center .. _MDTimePickerInput: MDTimePickerInput ----------------- Time input pickers allow people to specify a time using keyboard numbers. This input option should be accessible from any other mobile time picker interface by tapping the keyboard icon. .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/input-time-picker-preview.gif :align: center .. code-block:: python def show_time_picker(self): MDTimePickerInput().open() Events ====== **on_edit** event ----------------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-edit.gif :align: center .. tabs:: .. tab:: Declarative KV style .. code-block:: python from kivy.clock import Clock from kivy.lang import Builder from kivymd.app import MDApp from kivymd.uix.pickers import MDTimePickerDialVertical, MDTimePickerInput KV = ''' MDScreen: md_bg_color: self.theme_cls.backgroundColor MDButton: pos_hint: {'center_x': .5, 'center_y': .5} on_release: app.show_time_picker_vertical() MDButtonText: text: "Open time picker" ''' class Example(MDApp): def build(self): self.theme_cls.theme_style = "Dark" return Builder.load_string(KV) def on_edit_time_picker_input(self, time_picker_input): time_picker_input.dismiss() Clock.schedule_once(self.show_time_picker_vertical, 0.2) def show_time_picker_input(self, *args): time_picker_input = MDTimePickerInput() time_picker_input.bind(on_edit=self.on_edit_time_picker_input) time_picker_input.open() def on_edit_time_picker_vertical(self, time_picker_vertical): time_picker_vertical.dismiss() Clock.schedule_once(self.show_time_picker_input, 0.2) def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_edit=self.on_edit_time_picker_vertical) time_picker_vertical.open() Example().run() .. tab:: Declarative Python style .. code-block:: python from kivy.clock import Clock from kivymd.app import MDApp from kivymd.uix.button import MDButton, MDButtonText from kivymd.uix.pickers import ( MDTimePickerDialVertical, MDTimePickerInput, ) from kivymd.uix.screen import MDScreen class Example(MDApp): def build(self): self.theme_cls.theme_style = "Dark" return MDScreen( MDButton( MDButtonText( text="Open time picker", ), pos_hint={"center_x": 0.5, "center_y": 0.5}, on_release=self.show_time_picker_vertical, ), md_bg_color=self.theme_cls.backgroundColor, ) def on_edit_time_picker_input(self, time_picker_input): time_picker_input.dismiss() Clock.schedule_once(self.show_time_picker_vertical, 0.2) def show_time_picker_input(self, *args): time_picker_input = MDTimePickerInput() time_picker_input.bind(on_edit=self.on_edit_time_picker_input) time_picker_input.open() def on_edit_time_picker_vertical(self, time_picker_vertical): time_picker_vertical.dismiss() Clock.schedule_once(self.show_time_picker_input, 0.2) def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_edit=self.on_edit_time_picker_vertical) time_picker_vertical.open() Example().run() **on_hour_select** event ------------------------ .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-hour-select.gif :align: center .. code-block:: python def on_hour_select( self, time_picker_vertical: MDTimePickerDialVertical, mode: str ): MDSnackbar( MDSnackbarSupportingText( text=f"On '{mode}' select", ), y=dp(24), orientation="horizontal", pos_hint={"center_x": 0.5}, size_hint_x=0.5, ).open() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_hour_select=self.on_hour_select) time_picker_vertical.open() **on_minute_select** event -------------------------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-minute-select.gif :align: center .. code-block:: python def on_minute_select( self, time_picker_vertical: MDTimePickerDialVertical, mode: str ): MDSnackbar( MDSnackbarSupportingText( text=f"On '{mode}' select", ), y=dp(24), orientation="horizontal", pos_hint={"center_x": 0.5}, size_hint_x=0.5, ).open() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_minute_select=self.on_minute_select) time_picker_vertical.open() **on_am_pm** event ------------------ .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-am-pm.gif :align: center .. code-block:: python def on_am_pm( self, time_picker_vertical: MDTimePickerDialVertical, am_pm: str ): MDSnackbar( MDSnackbarSupportingText( text=f"'{am_pm.upper()}' select", ), y=dp(24), orientation="horizontal", pos_hint={"center_x": 0.5}, size_hint_x=0.5, ).open() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_am_pm=self.on_am_pm) time_picker_vertical.open() **on_selector_hour** event -------------------------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-selector-hour.gif :align: center .. code-block:: python def on_selector_hour( self, time_picker_vertical: MDTimePickerDialVertical, hour: str ): MDSnackbar( MDSnackbarSupportingText( text=f"The value of the hour is `{hour}` select", ), y=dp(24), orientation="horizontal", pos_hint={"center_x": 0.5}, size_hint_x=0.5, ).open() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_selector_hour=self.on_selector_hour) time_picker_vertical.open() **on_selector_minute** event ---------------------------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-selector-minute.gif :align: center .. code-block:: python def on_selector_minute( self, time_picker_vertical: MDTimePickerDialVertical, minute: str ): MDSnackbar( MDSnackbarSupportingText( text=f"The value of the hour is `{minute}` select", ), y=dp(24), orientation="horizontal", pos_hint={"center_x": 0.5}, size_hint_x=0.5, ).open() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_selector_minute=self.on_selector_minute) time_picker_vertical.open() **on_cancel** event ------------------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-cancel.gif :align: center .. code-block:: python def on_cancel( self, time_picker_vertical: MDTimePickerDialVertical ): time_picker_vertical.dismiss() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_cancel=self.on_cancel) time_picker_vertical.open() **on_ok** event --------------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-vertical-event-on-ok.gif :align: center .. code-block:: python def on_ok( self, time_picker_vertical: MDTimePickerDialVertical ): MDSnackbar( MDSnackbarSupportingText( text=f"Time is `{time_picker_vertical.time}`", ), y=dp(24), orientation="horizontal", pos_hint={"center_x": 0.5}, size_hint_x=0.5, ).open() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerDialVertical() time_picker_vertical.bind(on_ok=self.on_ok) time_picker_vertical.open() **on_time_input** event ----------------------- .. image:: https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/time-picker-input-event-on-time-input.gif :align: center .. code-block:: python def on_time_input( self, time_picker_vertical: MDTimePickerInput, type_time: str, value: str, ): MDSnackbar( MDSnackbarSupportingText( text=f"The {type_time} value is set to {value}", ), y=dp(24), orientation="horizontal", pos_hint={"center_x": 0.5}, size_hint_x=0.5, ).open() def show_time_picker_vertical(self, *args): time_picker_vertical = MDTimePickerInput() time_picker_vertical.bind(on_time_input=self.on_time_input) time_picker_vertical.open() API break ========= 1.2.0 version ------------- .. code-block:: python time_picker_dialog = MDTimePicker() time_picker_dialog.open() 2.0.0 version ------------- .. code-block:: python # time_picker_dialog = MDTimePickerDialVertical() # time_picker_dialog = MDTimePickerDialHorizontal() time_picker_dialog = MDTimePickerInput() time_picker_dialog.open() API - :mod:`kivymd.uix.pickers.timepicker.timepicker` ----------------------------------------------------- .. py:class:: MDBaseTimePicker(**kwargs) Implements the base class of the time picker. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.theming.ThemableBehavior` and :class:`~kivymd.uix.behaviors.motion_behavior.MotionTimePickerBehavior` and :class:`~kivy.uix.boxlayout.BoxLayout` and classes documentation. :Events: :attr:`on_cancel` Fired when the 'Cancel' button is pressed. :attr:`on_ok` Fired when the 'Ok' button is pressed. :attr:`on_dismiss` Fired when a date picker closes. :attr:`on_edit` Fired when you click on the date editing icon. :attr:`on_hour_select` Fired when the hour input field container is clicked. :attr:`on_minute_select` Fired when the minute input field container is clicked. :attr:`on_am_pm` Fired when the AP/PM switching elements are pressed. :attr:`on_selector_hour` Fired when switching the hour value in the clock face container. :attr:`on_selector_minute` Fired when switching the minute value in the clock face container. .. py:attribute:: hour Current hour. :attr:`hour` is an :class:`~kivy.properties.StringProperty` and defaults to `'12'`. .. py:attribute:: minute Current minute. :attr:`minute` is an :class:`~kivy.properties.StringProperty` and defaults to `0`. .. py:attribute:: am_pm Current AM/PM mode. :attr:`am_pm` is an :class:`~kivy.properties.OptionProperty` and defaults to `'am'`. .. py:attribute:: animation_duration Duration of the animations. :attr:`animation_duration` is an :class:`~kivy.properties.NumericProperty` and defaults to `0.2`. .. py:attribute:: animation_transition Transition type of the animations. :attr:`animation_transition` is an :class:`~kivy.properties.StringProperty` and defaults to `'out_quad'`. .. py:attribute:: time Returns the current time object. :attr:`time` is an :class:`~kivy.properties.ObjectProperty` and defaults to `None`. .. py:attribute:: headline_text Headline text. :attr:`headline_text` is an :class:`~kivy.properties.StringProperty` and defaults to `'Select time'`. .. py:attribute:: text_button_ok The text of the confirmation button. :attr:`text_button_ok` is a :class:`~kivy.properties.StringProperty` and defaults to `'Ok'`. .. py:attribute:: text_button_cancel The text of the cancel button. :attr:`text_button_cancel` is a :class:`~kivy.properties.StringProperty` and defaults to `'Cancel'`. .. py:attribute:: radius Container radius. :attr:`radius` is an :class:`~kivy.properties.VariableListProperty` and defaults to `[dp(16), dp(16), dp(16), dp(16)]`. .. py:attribute:: is_open Is the date picker dialog open. :attr:`is_open` is a :class:`~kivy.properties.BooleanProperty` and defaults to `False`. .. py:attribute:: scrim_color Color for scrim in (r, g, b, a) or string format. :attr:`scrim_color` is a :class:`~kivy.properties.ColorProperty` and defaults to `[0, 0, 0, 0.5]`. .. py:method:: set_time(time_obj: datetime.time) -> None Manually set time dialog with the specified time. .. py:method:: open() -> None Show the dialog time picker. .. py:method:: on_touch_down(touch) Receive a touch down event. :Parameters: `touch`: :class:`~kivy.input.motionevent.MotionEvent` class Touch received. The touch is in parent coordinates. See :mod:`~kivy.uix.relativelayout` for a discussion on coordinate systems. :Returns: bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree. .. py:method:: dismiss(*args) -> None Dismiss the dialog time picker. .. py:method:: on_dismiss(*args) -> None Fired when a time picker closes. .. py:method:: on_cancel(*args) -> None Fired when the 'Cancel' button is pressed. .. py:method:: on_ok(*args) -> None Fired when the 'Ok' button is pressed. .. py:method:: on_hour_select(*args) -> None Fired when the hour input field container is clicked. .. py:method:: on_minute_select(*args) -> None Fired when the minute input field container is clicked. .. py:method:: on_am_pm(*args) -> None Fired when the AP/PM switching elements are pressed. .. py:method:: on_edit(*args) -> None Fired when you click on the time editing icon. .. py:method:: on_selector_hour(*args) -> None Fired when switching the hour value in the clock face container. .. py:method:: on_selector_minute(*args) -> None Fired when switching the minute value in the clock face container. .. py:method:: on_time_input(*args) -> None Fired when switching the minute value in the clock face container. .. py:class:: MDTimePickerInput(**kwargs) Implements input time picker. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.behaviors.elevation.CommonElevationBehavior` and :class:`~MDBaseTimePicker` classes documentation. .. py:class:: MDTimePickerDialVertical(**kwargs) Implements vertical time picker. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.behaviors.elevation.CommonElevationBehavior` and :class:`~MDBaseTimePicker` classes documentation. .. py:class:: MDTimePickerDialHorizontal(**kwargs) Implements horizontal time picker. .. versionadded:: 2.0.0 For more information, see in the :class:`~kivymd.uix.behaviors.elevation.CommonElevationBehavior` and :class:`~MDBaseTimePicker` classes documentation.