SelectionControls#
#
Selection controls allow the user to select options.
KivyMD provides the following selection controls classes for use:
MDCheckbox#
Usage#
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 Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Green"
self.theme_cls.theme_style = "Dark"
return Builder.load_string(KV)
Example().run()
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 Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Green"
self.theme_cls.theme_style = "Dark"
return Builder.load_string(KV)
Example().run()
Parent and child checkboxes#
Checkboxes can have a parent-child relationship with other checkboxes. When the parent checkbox is checked, all child checkboxes are checked. If a parent checkbox is unchecked, all child checkboxes are unchecked. If some, but not all, child checkboxes are checked, the parent checkbox becomes an indeterminate checkbox.
Usage#
MDCheckbox:
group: "root" # this is a required name for the parent checkbox group
MDCheckbox:
group: "child" # this is a required name for a group of child checkboxes
MDCheckbox:
group: "child" # this is a required name for a group of child checkboxes
Example#
from kivy.lang import Builder
from kivy.properties import StringProperty
from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
KV = '''
<CheckItem>
adaptive_height: True
MDCheckbox:
group: root.group
MDLabel:
text: root.text
adaptive_height: True
padding_x: "12dp"
pos_hint: {"center_y": .5}
MDBoxLayout:
orientation: "vertical"
md_bg_color: self.theme_cls.backgroundColor
MDBoxLayout:
orientation: "vertical"
adaptive_height: True
padding: "12dp", "36dp", 0, 0
spacing: "12dp"
CheckItem:
text: "Recieve emails"
group: "root"
MDBoxLayout:
orientation: "vertical"
adaptive_height: True
padding: "24dp", 0, 0, 0
spacing: "12dp"
CheckItem:
text: "Daily"
group: "child"
CheckItem:
text: "Weekly"
group: "child"
CheckItem:
text: "Monthly"
group: "child"
MDWidget:
'''
class CheckItem(MDBoxLayout):
text = StringProperty()
group = StringProperty()
class Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Teal"
return Builder.load_string(KV)
Example().run()
MDSwitch#
Usage#
from kivy.lang import Builder
from kivymd.app import MDApp
KV = '''
MDFloatLayout:
MDSwitch:
pos_hint: {'center_x': .5, 'center_y': .5}
'''
class Example(MDApp):
def build(self):
self.theme_cls.primary_palette = "Green"
self.theme_cls.theme_style = "Dark"
return Builder.load_string(KV)
Example().run()
Note
Control state of MDSwitch
same way as in
MDCheckbox
.
API - kivymd.uix.selectioncontrol.selectioncontrol
#
- class kivymd.uix.selectioncontrol.selectioncontrol.MDCheckbox(**kwargs)#
Checkbox class.
For more information, see in the
StateLayerBehavior
andCircularRippleBehavior
andScaleBehavior
andToggleButtonBehavior
andMDIcon
classes documentation.- active#
Indicates if the checkbox is active or inactive.
active
is aBooleanProperty
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 aStringProperty
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 aStringProperty
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 aStringProperty
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 aStringProperty
and defaults to ‘checkbox-marked-circle’.
- color_active#
Color in (r, g, b, a) or string format when the checkbox is in the active state.
New in version 1.0.0.
MDCheckbox: color_active: "red"
color_active
is aColorProperty
and defaults to None.
- color_inactive#
Color in (r, g, b, a) or string format when the checkbox is in the inactive state.
New in version 1.0.0.
MDCheckbox: color_inactive: "blue"
color_inactive
is aColorProperty
and defaults to None.
- color_disabled#
Color in (r, g, b, a) or string format when the checkbox is in the disabled state.
New in version 2.0.0: Use
color_disabled
instead.color_disabled
is aColorProperty
and defaults to None.
- disabled_color#
Color in (r, g, b, a) or string format when the checkbox is in the disabled state.
Deprecated since version 2.0.0: Use
color_disabled
instead.disabled_color
is aColorProperty
and defaults to None.
- selected_color#
Color in (r, g, b, a) or string format when the checkbox is in the active state.
Deprecated since version 1.0.0: Use
color_active
instead.selected_color
is aColorProperty
and defaults to None.
- unselected_color#
Color in (r, g, b, a) or string format when the checkbox is in the inactive state.
Deprecated since version 1.0.0: Use
color_inactive
instead.unselected_color
is aColorProperty
and defaults to None.
- update_icon(*args) None #
Fired when the values of
checkbox_icon_normal
andcheckbox_icon_down
andradio_icon_normal
andgroup
change.
- 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.
- touch:
- 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.
- class kivymd.uix.selectioncontrol.selectioncontrol.MDSwitch(**kwargs)#
Switch class.
For more information, see in the
StateLayerBehavior
andMDFloatLayout
classes documentation.- md_bg_color_disabled#
The background color in (r, g, b, a) or string format of the switch when the switch is disabled.
md_bg_color_disabled
is aColorProperty
and defaults to None.
- ripple_effect#
Allows or does not allow the ripple effect when activating/deactivating the switch.
New in version 2.0.0.
ripple_effect
is aBooleanProperty
and defaults to True.
- active#
Indicates if the switch is active or inactive.
active
is aBooleanProperty
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"
icon_active
is aStringProperty
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"
icon_inactive
is aStringProperty
and defaults to ‘’.
- icon_active_color#
Thumb icon color in (r, g, b, a) or string format 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"
icon_active_color
is aColorProperty
and defaults to None.
- icon_inactive_color#
Thumb icon color in (r, g, b, a) or string format 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"
icon_inactive_color
is aColorProperty
and defaults to None.
- thumb_color_active#
The color in (r, g, b, a) or string format of the thumb when the switch is active.
New in version 1.0.0.
MDSwitch: active: True thumb_color_active: "brown"
thumb_color_active
is anColorProperty
and default to None.
- thumb_color_inactive#
The color in (r, g, b, a) or string format of the thumb when the switch is inactive.
New in version 1.0.0.
MDSwitch: thumb_color_inactive: "brown"
thumb_color_inactive
is anColorProperty
and default to None.
- thumb_color_disabled#
The color in (r, g, b, a) or string format of the thumb when the switch is in the disabled state.
MDSwitch: active: True thumb_color_disabled: "brown" disabled: True
thumb_color_disabled
is anColorProperty
and default to None.
- track_color_active#
The color in (r, g, b, a) or string format of the track when the switch is active.
MDSwitch: active: True track_color_active: "red"
track_color_active
is anColorProperty
and default to None.
- track_color_inactive#
The color in (r, g, b, a) or string format of the track when the switch is inactive.
New in version 1.0.0.
MDSwitch: track_color_inactive: "red"
track_color_inactive
is anColorProperty
and default to None.
- track_color_disabled#
The color in (r, g, b, a) or string format of the track when the switch is in the disabled state.
MDSwitch: track_color_disabled: "lightgrey" disabled: True
track_color_disabled
is anColorProperty
and default to None.
- line_color_disabled#
The color of the outline in the disabled state
New in version 2.0.0.
line_color_disabled
is anColorProperty
and defaults to None.
- set_icon(instance_switch, icon_value: str) None #
Fired when the values of
icon_active
andicon_inactive
change.