WheelPicker

Added in version 2.0.1.

See also

Human Interface Guidelines, Pickers

A picker displays one or more scrollable lists of distinct values that people can choose from.

Anatomy

Base example

import calendar

from kivy.metrics import dp

from kivymd.uix.pickers import IOSWheelPickerLabel, IOSWheelPicker
from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen


class MainScreen(MDScreen):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        months = list(calendar.month_name)[1:]
        custom_cols = [
            (months, "August"),
        ]

        self.widgets = [
            IOSWheelPicker(
                IOSWheelPickerLabel(
                    bold=True,
                    selected_color="white",
                    normal_color=(1, 1, 1, .5),
                ),
                columns=custom_cols,
                visible_count=7,
                picker_width=dp(320),
                curve_factor=dp(35),
            )
        ]


class ExampleApp(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return MainScreen(
            md_bg_color=self.theme_cls.backgroundColor
        )


if __name__ == "__main__":
    ExampleApp().run()

Note

Do not create the WheelPicker widget in KV files or strings.

Creating wheels pickers

1. Automatic generation of a numeric range

2. One list + explicitly selected value

3. List of elements only

4. Several columns

5. Combining different types of columns

6. Unit label

Automatic generation of a numeric range

custom_cols = [
    (
        0,   # start
        24,  # end
        12,  # current set value
    ),
]
IOSWheelPicker(
    columns=custom_cols,
)

One list + explicitly selected value

months = list(calendar.month_name)[1:]
custom_cols = [
    (
        months,    # list items
        "August",  # current set value
    ),
]
IOSWheelPicker(
    columns=custom_cols,
)

List of elements only

months = list(calendar.month_name)[1:]
custom_cols = [
    (
        months,    # list items
    ),
]
IOSWheelPicker(
    columns=custom_cols,
)

Several columns

months = list(calendar.month_name)[1:]
custom_cols = [
    (
        (1900, 2026, 2026),
        (months, "August"),
    ),
]
IOSWheelPicker(
    columns=custom_cols,
)

Combining different types of columns

months = list(calendar.month_name)[1:]
    custom_cols = [
        (2020, 2030, 2026),
        (months, "August"),
        (1, 31, 15),
    ]
IOSWheelPicker(
    columns=custom_cols,
)

Unit label

months = list(calendar.month_name)[1:]
custom_cols = [
    (
        (1, 31, 20, "DAY"),
        (months, "August", "Month"),
    ),
]
IOSWheelPicker(
    IOSWheelPickerUnitLabel(
        bold=True,
    ),
    columns=custom_cols,
)

Events

IOSWheelPicker(
    on_select=self.on_picker_select,
)

def on_picker_select(self, instance, values) -> None:
    '''
    Called when the selection changes in any column of the picker.

    :param instance: The :class:`~kivymd.uix.pickers.weelpicker.weelpicker.IOSWheelPicker`
        instance that triggered the event.
    :type instance: IOSWheelPicker

    :param values: A list containing the current selected values from all
        columns (e.g., ``[11, 'August']``).
    :type values: list[str | int]
    '''

    # <kivymd.uix.pickers.weelpicker.weelpicker.IOSWheelPicker object at 0x11ba020b0>
    # [11, 'August']
    print(instance)
    print(values)

Additional configuration parameters

Visible number of elements

IOSWheelPicker(
    visible_count=5,  # 10
)

Intensity factor of the 3D cylindrical curvature transformation

IOSWheelPicker(
    curve_factor=dp(15),  # 55
)

Total layout width of the picker component

IOSWheelPicker(
    picker_width=dp(120),  # dp(320)
)

Pixel height of each row item

IOSWheelPicker(
    item_height=dp(24),  # dp(36)
)

Customization

import calendar

from kivy.metrics import dp
from kivy.uix.floatlayout import FloatLayout

from kivymd.app import MDApp
from kivymd.uix.screen import MDScreen
from kivymd.uix.behaviors import IOSGlassBehavior, DeclarativeBehavior
from kivymd.uix.fitimage import FitImage
from kivymd.uix.pickers import IOSWheelPickerLabel, IOSWheelPicker


class GlassContainer(DeclarativeBehavior, IOSGlassBehavior, FloatLayout):
    pass


class MainScreen(MDScreen):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        months = list(calendar.month_name)[1:]
        custom_cols = [
            (1, 31, 20),
            (months, "August"),
        ]

        bg_image = FitImage(source="bg.png")

        self.widgets = [
            bg_image,
            GlassContainer(
                IOSWheelPicker(
                    IOSWheelPickerLabel(
                        font_style="Title",
                        font_size="20sp",
                        bold=True,
                        selected_color="white",
                        normal_color=(1, 1, 1, .5),
                    ),
                    columns=custom_cols,
                    visible_count=7,
                    picker_width=dp(320),
                    curve_factor=dp(35),
                ),
                target_background=bg_image,
                border_radius=[dp(26), dp(26), dp(26), dp(26)],
                glass_color=[1.0, 1.0, 1.0, 0.18],
                blur_amount=10.0,
                size_hint=(None, None),
                size=(dp(320), dp(200)),
                pos_hint={"center_x": .5, "center_y": .5},
            )
        ]


class Example(MDApp):
    def build(self):
        self.theme_cls.theme_style = "Dark"
        return MainScreen()


if __name__ == "__main__":
    Example().run()

API - kivymd.uix.pickers.weelpicker.weelpicker

class kivymd.uix.pickers.weelpicker.weelpicker.IOSWheelPickerUnitLabel(**kwargs)

Text label widget used for column unit indicators.

For more information, see in the MDLabel class documentation.

normal_color

The text color the unit label.

normal_color is a ColorProperty and defaults to None.

class kivymd.uix.pickers.weelpicker.weelpicker.IOSWheelPickerLabel(**kwargs)

Text label widget supporting 3D scale and translation transformations relative to its center point.

For more information, see in the MDLabel class documentation.

selected_color

The text color when the label is currently selected (e.g., inside the picker selection zone).

selected_color is a ColorProperty and defaults to None.

normal_color

The text color when the label is in its unselected or idle state.

normal_color is a ColorProperty and defaults to None.

apply_3d_transform(scale_x, scale_y) → None

Applies horizontal and vertical scaling transforms relative to the label’s center origin.

Parameters:

• scale_x – The horizontal scale factor.

• scale_y – The vertical scale factor.

class kivymd.uix.pickers.weelpicker.weelpicker.IOSWheelPicker(*args, columns=None, selected_color=None, normal_color=None, visible_count=5, item_height=dp(36), curve_factor=dp(30), picker_width=dp(340), selection_bg_color=None, **kwargs)

Implements an iOS-style multi-column wheel picker with 3D cylindrical scrolling, customizable item stylingand selection highlighting.

For more information, see in the DeclarativeBehavior and RelativeLayout classes documentation.

Events:

on_select

Fired when an item selection changes in any of the picker columns.

selection_bg_color

Background color of the central active row selection glass bar in HEX/RGBA or string format.

selection_bg_color is a ColorProperty and defaults to [1, 1, 1, 0.18].

on_select(values)

Default handler for the on_select event.

get_values()

Retrieves current display values across all active picker columns.

add_widget(widget, *args, **kwargs)

Add a new widget as a child of this widget.

Parameters:

widget: Widget

Widget to add to our list of children.

index: int, defaults to 0

Index to insert the widget in the list. Notice that the default of 0 means the widget is inserted at the beginning of the list and will thus be drawn on top of other sibling widgets. For a full discussion of the index and widget hierarchy, please see the Widgets Programming Guide.

Added in version 1.0.5.

canvas: str, defaults to None

Canvas to add widget’s canvas to. Can be ‘before’, ‘after’ or None for the default canvas.

Added in version 1.9.0.

>>> from kivy.uix.button import Button
>>> from kivy.uix.slider import Slider
>>> root = Widget()
>>> root.add_widget(Button())
>>> slider = Slider()
>>> root.add_widget(slider)