SelectionControls#

Selection controls allow the user to select options.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/selection-controll.png

KivyMD provides the following selection controls classes for use:

MDCheckbox#

from kivy.lang import Builder

from kivymd.app import MDApp


KV = '''
MDFloatLayout:

    MDCheckbox:
        size_hint: None, None
        size: "48dp", "48dp"
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


class Test(MDApp):
    def build(self):
        return Builder.load_string(KV)


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox.gif

Note

Be sure to specify the size of the checkbox. By default, it is (dp(48), dp(48)), but the ripple effect takes up all the available space.

Control state#

MDCheckbox:
    on_active: app.on_checkbox_active(*args)
def on_checkbox_active(self, checkbox, value):
    if value:
        print('The checkbox', checkbox, 'is active', 'and', checkbox.state, 'state')
    else:
        print('The checkbox', checkbox, 'is inactive', 'and', checkbox.state, 'state')

MDCheckbox with group#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
<Check@MDCheckbox>:
    group: 'group'
    size_hint: None, None
    size: dp(48), dp(48)


MDFloatLayout:

    Check:
        active: True
        pos_hint: {'center_x': .4, 'center_y': .5}

    Check:
        pos_hint: {'center_x': .6, 'center_y': .5}
'''


class Test(MDApp):
    def build(self):
        return Builder.load_string(KV)


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-group.gif

MDSwitch#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDFloatLayout:

    MDSwitch:
        pos_hint: {'center_x': .5, 'center_y': .5}
'''


class Test(MDApp):
    def build(self):
        return Builder.load_string(KV)


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-switch.gif

Note

For MDSwitch size is not required. By default it is (dp(36), dp(48)), but you can increase the width if you want.

MDSwitch:
    width: dp(64)
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/md-switch_width.png

Note

Control state of MDSwitch same way as in MDCheckbox.

MDSwitch in M3 style#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:

    MDSwitch:
        pos_hint: {'center_x': .5, 'center_y': .5}
        active: True
'''


class Test(MDApp):
    def build(self):
        self.theme_cls.material_style = "M3"
        return Builder.load_string(KV)


Test().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-m3.gif

API - kivymd.uix.selectioncontrol.selectioncontrol#

class kivymd.uix.selectioncontrol.selectioncontrol.MDCheckbox(**kwargs)#

Class implements a circular ripple effect.

active#

Indicates if the checkbox is active or inactive.

active is a BooleanProperty and defaults to False.

checkbox_icon_normal#

Background icon of the checkbox used for the default graphical representation when the checkbox is not pressed.

checkbox_icon_normal is a StringProperty and defaults to ‘checkbox-blank-outline’.

checkbox_icon_down#

Background icon of the checkbox used for the default graphical representation when the checkbox is pressed.

checkbox_icon_down is a StringProperty and defaults to ‘checkbox-marked’.

radio_icon_normal#

Background icon (when using the group option) of the checkbox used for the default graphical representation when the checkbox is not pressed.

radio_icon_normal is a StringProperty and defaults to ‘checkbox-blank-circle-outline’.

radio_icon_down#

Background icon (when using the group option) of the checkbox used for the default graphical representation when the checkbox is pressed.

radio_icon_down is a StringProperty and defaults to ‘checkbox-marked-circle’.

color_active#

Color when the checkbox is in the active state.

New in version 1.0.0.

MDCheckbox:
    color_active: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-color-active.png

color_active is a ColorProperty and defaults to None.

color_inactive#

Color when the checkbox is in the inactive state.

New in version 1.0.0.

MDCheckbox:
    color_inactive: "blue"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-color-inactive.png

color_inactive is a ColorProperty and defaults to None.

disabled_color#

Color when the checkbox is in the disabled state.

MDCheckbox:
    disabled_color: "lightgrey"
    disabled: True
    active: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/checkbox-disabled-color.png

disabled_color is a ColorProperty and defaults to None.

selected_color#

Color when the checkbox is in the active state.

Deprecated since version 1.0.0: Use color_active instead.

selected_color is a ColorProperty and defaults to None.

unselected_color#

Color when the checkbox is in the inactive state.

Deprecated since version 1.0.0: Use color_inactive instead.

unselected_color is a ColorProperty and defaults to None.

update_primary_color(self, instance, value)#
update_icon(self, *args)#
update_color(self, *args)#
on_state(self, *args)#
on_active(self, *args)#
class kivymd.uix.selectioncontrol.selectioncontrol.MDSwitch(**kwargs)#

Float layout class. See module documentation for more information.

active#

Indicates if the switch is active or inactive.

active is a BooleanProperty and defaults to False.

icon_active#

Thumb icon when the switch is in the active state (only M3 style).

New in version 1.0.0.

MDSwitch:
    active: True
    icon_active: "check"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-active.png

icon_active is a StringProperty and defaults to ‘’.

icon_inactive#

Thumb icon when the switch is in an inactive state (only M3 style).

New in version 1.0.0.

MDSwitch:
    icon_inactive: "close"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-inactive.png

icon_inactive is a StringProperty and defaults to ‘’.

icon_active_color#

Thumb icon color when the switch is in the active state (only M3 style).

New in version 1.0.0.

MDSwitch:
    active: True
    icon_active: "check"
    icon_active_color: "white"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-active-color.png

icon_active_color is a ColorProperty and defaults to None.

icon_inactive_color#

Thumb icon color when the switch is in an inactive state (only M3 style).

New in version 1.0.0.

MDSwitch:
    icon_inactive: "close"
    icon_inactive_color: "grey"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-icon-inactive-color.png

icon_inactive_color is a ColorProperty and defaults to None.

thumb_color_active#

The color of the thumb when the switch is active.

New in version 1.0.0.

MDSwitch:
    active: True
    thumb_color_active: "brown"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-thumb-color-active.png

thumb_color_active is an ColorProperty and default to None.

thumb_color_inactive#

The color of the thumb when the switch is inactive.

New in version 1.0.0.

MDSwitch:
    thumb_color_inactive: "brown"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-thumb-color-inactive.png

thumb_color_inactive is an ColorProperty and default to None.

thumb_color_disabled#

The color of the thumb when the switch is in the disabled state.

MDSwitch:
    active: True
    thumb_color_disabled: "brown"
    disabled: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-thumb-color-disabled.png

thumb_color_disabled is an ColorProperty and default to None.

track_color_active#

The color of the track when the switch is active.

MDSwitch:
    active: True
    track_color_active: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-track-color-active.png

track_color_active is an ColorProperty and default to None.

track_color_inactive#

The color of the track when the switch is inactive.

New in version 1.0.0.

MDSwitch:
    track_color_inactive: "red"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-track-color-inactive.png

track_color_inactive is an ColorProperty and default to None.

track_color_disabled#

The color of the track when the switch is in the disabled state.

MDSwitch:
    track_color_disabled: "lightgrey"
    disabled: True
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/switch-track-color-disabled.png

track_color_disabled is an ColorProperty and default to None.

set_icon(self, instance_switch, icon_value: str)#
on_active(self, instance_switch, active_value: bool)#
on_thumb_down(self)#

Called at the on_touch_down event of the Thumb object. Indicates the state of the switch “on/off” by an animation of increasing the size of the thumb.