TimePicker

See also

Material Design spec, Date picker

Time pickers help users select and set a specific time.

• 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

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

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.

Declarative KV styleDeclarative Python style

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()

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.

def show_time_picker(self):
    MDTimePickerDialHorizontal().open()

Note

You must control the orientation of the time picker yourself.

Declarative KV styleDeclarative Python style

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()

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.

def show_time_picker(self):
    MDTimePickerInput().open()

Events

on_edit event

Declarative KV styleDeclarative Python style

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()

on_hour_select event

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

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

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

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

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

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

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

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

time_picker_dialog = MDTimePicker()
time_picker_dialog.open()

2.0.0 version

# time_picker_dialog = MDTimePickerDialVertical()
# time_picker_dialog = MDTimePickerDialHorizontal()

time_picker_dialog = MDTimePickerInput()
time_picker_dialog.open()

API - kivymd.uix.pickers.timepicker.timepicker

class kivymd.uix.pickers.timepicker.timepicker.MDBaseTimePicker(**kwargs)

Implements the base class of the time picker.

Added in version 2.0.0.

For more information, see in the ThemableBehavior and MotionTimePickerBehavior and BoxLayout and classes documentation.

Events:

on_cancel

Fired when the ‘Cancel’ button is pressed.

on_ok

Fired when the ‘Ok’ button is pressed.

on_dismiss

Fired when a date picker closes.

on_edit

Fired when you click on the date editing icon.

on_hour_select

Fired when the hour input field container is clicked.

on_minute_select

Fired when the minute input field container is clicked.

on_am_pm

Fired when the AP/PM switching elements are pressed.

on_selector_hour

Fired when switching the hour value in the clock face container.

on_selector_minute

Fired when switching the minute value in the clock face container.

hour

Current hour.

hour is an StringProperty and defaults to ‘12’.

minute

Current minute.

minute is an StringProperty and defaults to 0.

am_pm

Current AM/PM mode.

am_pm is an OptionProperty and defaults to ‘am’.

animation_duration

Duration of the animations.

animation_duration is an NumericProperty and defaults to 0.2.

animation_transition

Transition type of the animations.

animation_transition is an StringProperty and defaults to ‘out_quad’.

time

Returns the current time object.

time is an ObjectProperty and defaults to None.

headline_text

Headline text.

headline_text is an StringProperty and defaults to ‘Select time’.

text_button_ok

The text of the confirmation button.

text_button_ok is a StringProperty and defaults to ‘Ok’.

text_button_cancel

The text of the cancel button.

text_button_cancel is a StringProperty and defaults to ‘Cancel’.

radius

Container radius.

radius is an VariableListProperty and defaults to [dp(16), dp(16), dp(16), dp(16)].

is_open

Is the date picker dialog open.

is_open is a BooleanProperty and defaults to False.

scrim_color

Color for scrim in (r, g, b, a) or string format.

scrim_color is a ColorProperty and defaults to [0, 0, 0, 0.5].

set_time(time_obj: datetime.time) → None

Manually set time dialog with the specified time.

open() → None

Show the dialog time picker.

on_touch_down(touch)

Receive a touch down event.

Parameters:

touch: MotionEvent class

Touch received. The touch is in parent coordinates. See 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.

dismiss(*args) → None

Dismiss the dialog time picker.

on_dismiss(*args) → None

Fired when a time picker closes.

on_cancel(*args) → None

Fired when the ‘Cancel’ button is pressed.

on_ok(*args) → None

Fired when the ‘Ok’ button is pressed.

on_hour_select(*args) → None

Fired when the hour input field container is clicked.

on_minute_select(*args) → None

Fired when the minute input field container is clicked.

on_am_pm(*args) → None

Fired when the AP/PM switching elements are pressed.

on_edit(*args) → None

Fired when you click on the time editing icon.

on_selector_hour(*args) → None

Fired when switching the hour value in the clock face container.

on_selector_minute(*args) → None

Fired when switching the minute value in the clock face container.

on_time_input(*args) → None

Fired when switching the minute value in the clock face container.

class kivymd.uix.pickers.timepicker.timepicker.MDTimePickerInput(**kwargs)

Implements input time picker.

Added in version 2.0.0.

For more information, see in the CommonElevationBehavior and MDBaseTimePicker classes documentation.

class kivymd.uix.pickers.timepicker.timepicker.MDTimePickerDialVertical(**kwargs)

Implements vertical time picker.

Added in version 2.0.0.

For more information, see in the CommonElevationBehavior and MDBaseTimePicker classes documentation.

class kivymd.uix.pickers.timepicker.timepicker.MDTimePickerDialHorizontal(**kwargs)

Implements horizontal time picker.

Added in version 2.0.0.

For more information, see in the CommonElevationBehavior and MDBaseTimePicker classes documentation.