Selection¶
See also
Selection refers to how users indicate specific items they intend to take action on.
Entering selection mode¶
To select an item and enter selection mode, long press the item:
Exiting selection mode¶
To exit selection mode, tap each selected item until they’re all deselected:
Larger selections¶
Note
This feature is missing yet.
Events¶
def on_selected(self, instance_selection_list, instance_selection_item):
'''Called when a list item is selected.'''
def on_unselected(self, instance_selection_list, instance_selection_item):
'''Called when a list item is unselected.'''
Example with TwoLineAvatarListItem¶
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.utils import get_color_from_hex
from kivymd.app import MDApp
from kivymd.uix.list import TwoLineAvatarListItem
KV = '''
<MyItem>
text: "Two-line item with avatar"
secondary_text: "Secondary text here"
_no_ripple_effect: True
ImageLeftWidget:
source: "data/logo/kivy-icon-256.png"
MDBoxLayout:
orientation: "vertical"
MDToolbar:
id: toolbar
title: "Inbox"
left_action_items: [["menu"]]
right_action_items: [["magnify"], ["dots-vertical"]]
md_bg_color: 0, 0, 0, 1
MDBoxLayout:
padding: "24dp", "8dp", 0, "8dp"
adaptive_size: True
MDLabel:
text: "Today"
adaptive_size: True
ScrollView:
MDSelectionList:
id: selection_list
spacing: "12dp"
overlay_color: app.overlay_color[:-1] + [.2]
icon_bg_color: app.overlay_color
on_selected: app.on_selected(*args)
on_unselected: app.on_unselected(*args)
on_selected_mode: app.set_selection_mode(*args)
'''
class MyItem(TwoLineAvatarListItem):
pass
class Example(MDApp):
overlay_color = get_color_from_hex("#6042e4")
def build(self):
return Builder.load_string(KV)
def on_start(self):
for i in range(10):
self.root.ids.selection_list.add_widget(MyItem())
def set_selection_mode(self, instance_selection_list, mode):
if mode:
md_bg_color = self.overlay_color
left_action_items = [
[
"close",
lambda x: self.root.ids.selection_list.unselected_all(),
]
]
right_action_items = [["trash-can"], ["dots-vertical"]]
else:
md_bg_color = (0, 0, 0, 1)
left_action_items = [["menu"]]
right_action_items = [["magnify"], ["dots-vertical"]]
self.root.ids.toolbar.title = "Inbox"
Animation(md_bg_color=md_bg_color, d=0.2).start(self.root.ids.toolbar)
self.root.ids.toolbar.left_action_items = left_action_items
self.root.ids.toolbar.right_action_items = right_action_items
def on_selected(self, instance_selection_list, instance_selection_item):
self.root.ids.toolbar.title = str(
len(instance_selection_list.get_selected_list_items())
)
def on_unselected(self, instance_selection_list, instance_selection_item):
if instance_selection_list.get_selected_list_items():
self.root.ids.toolbar.title = str(
len(instance_selection_list.get_selected_list_items())
)
Example().run()
Example with FitImage¶
from kivy.animation import Animation
from kivy.lang import Builder
from kivy.utils import get_color_from_hex
from kivymd.app import MDApp
from kivymd.utils.fitimage import FitImage
KV = '''
MDBoxLayout:
orientation: "vertical"
md_bg_color: app.theme_cls.bg_light
MDToolbar:
id: toolbar
title: "Inbox"
left_action_items: [["menu"]]
right_action_items: [["magnify"], ["dots-vertical"]]
md_bg_color: app.theme_cls.bg_light
specific_text_color: 0, 0, 0, 1
MDBoxLayout:
padding: "24dp", "8dp", 0, "8dp"
adaptive_size: True
MDLabel:
text: "Today"
adaptive_size: True
ScrollView:
MDSelectionList:
id: selection_list
padding: "24dp", 0, "24dp", "24dp"
cols: 3
spacing: "12dp"
overlay_color: app.overlay_color[:-1] + [.2]
icon_bg_color: app.overlay_color
progress_round_color: app.progress_round_color
on_selected: app.on_selected(*args)
on_unselected: app.on_unselected(*args)
on_selected_mode: app.set_selection_mode(*args)
'''
class Example(MDApp):
overlay_color = get_color_from_hex("#6042e4")
progress_round_color = get_color_from_hex("#ef514b")
def build(self):
return Builder.load_string(KV)
def on_start(self):
for i in range(10):
self.root.ids.selection_list.add_widget(
FitImage(
source="image.png",
size_hint_y=None,
height="240dp",
)
)
def set_selection_mode(self, instance_selection_list, mode):
if mode:
md_bg_color = self.overlay_color
left_action_items = [
[
"close",
lambda x: self.root.ids.selection_list.unselected_all(),
]
]
right_action_items = [["trash-can"], ["dots-vertical"]]
else:
md_bg_color = (1, 1, 1, 1)
left_action_items = [["menu"]]
right_action_items = [["magnify"], ["dots-vertical"]]
self.root.ids.toolbar.title = "Inbox"
Animation(md_bg_color=md_bg_color, d=0.2).start(self.root.ids.toolbar)
self.root.ids.toolbar.left_action_items = left_action_items
self.root.ids.toolbar.right_action_items = right_action_items
def on_selected(self, instance_selection_list, instance_selection_item):
self.root.ids.toolbar.title = str(
len(instance_selection_list.get_selected_list_items())
)
def on_unselected(self, instance_selection_list, instance_selection_item):
if instance_selection_list.get_selected_list_items():
self.root.ids.toolbar.title = str(
len(instance_selection_list.get_selected_list_items())
)
Example().run()
API - kivymd.uix.selection
¶
- class kivymd.uix.selection.MDSelectionList(**kwargs)¶
- Events
- on_selected
Called when a list item is selected.
- on_unselected
Called when a list item is unselected.
- selected_mode¶
List item selection mode. If True when clicking on a list item, it will be selected.
selected_mode
is anBooleanProperty
and defaults to False.
- icon¶
Name of the icon with which the selected list item will be marked.
icon
is anStringProperty
and defaults to ‘check’.
- icon_pos¶
The position of the icon that will mark the selected list item.
icon_pos
is anListProperty
and defaults to [].
- icon_bg_color¶
Background color of the icon that will mark the selected list item.
icon_bg_color
is anColorProperty
and defaults to [1, 1, 1, 1].
- icon_check_color¶
Color of the icon that will mark the selected list item.
icon_check_color
is anColorProperty
and defaults to [1, 1, 1, 1].
- overlay_color¶
The overlay color of the selected list item..
overlay_color
is anColorProperty
and defaults to [0, 0, 0, 0.2]].
- progress_round_size¶
Size of the spinner for switching of selected_mode mode.
progress_round_size
is anNumericProperty
and defaults to dp(46).
- progress_round_color¶
Color of the spinner for switching of selected_mode mode.
progress_round_color
is anNumericProperty
and defaults to None.
- add_widget(self, widget, index=0, canvas=None)¶
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.
New 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.
New in version 1.9.0.
- widget:
>>> from kivy.uix.button import Button >>> from kivy.uix.slider import Slider >>> root = Widget() >>> root.add_widget(Button()) >>> slider = Slider() >>> root.add_widget(slider)
- get_selected(self)¶
- get_selected_list_items(self)¶
- unselected_all(self)¶
- selected_all(self)¶
- on_selected(self, *args)¶
Called when a list item is selected.
- on_unselected(self, *args)¶
Called when a list item is unselected.