List¶
See also
Lists are continuous, vertical indexes of text or images.
The class MDList
in combination with a BaseListItem
like
OneLineListItem
will create a list that expands as items are added to
it, working nicely with Kivy’s ScrollView
.
Due to the variety in sizes and controls in the Material Design spec, this module suffers from a certain level of complexity to keep the widgets compliant, flexible and performant.
For this KivyMD provides list items that try to cover the most common usecases,
when those are insufficient, there’s a base class called BaseListItem
which you can use to create your own list items. This documentation will only
cover the provided ones, for custom implementations please refer to this
module’s source code.
KivyMD provides the following list items classes for use:
Text only ListItems¶
ListItems with widget containers¶
These widgets will take other widgets that inherit from ILeftBody
,
ILeftBodyTouch
, IRightBody
or IRightBodyTouch
and
put them in their corresponding container.
As the name implies, ILeftBody
and IRightBody
will signal
that the widget goes into the left or right container, respectively.
ILeftBodyTouch
and IRightBodyTouch
do the same thing,
except these widgets will also receive touch events that occur within their
surfaces.
KivyMD provides base classes such as ImageLeftWidget
,
ImageRightWidget
, IconRightWidget
, IconLeftWidget
,
based on the above classes.
Allows the use of items with custom widgets on the left.
It allows the use of elements with custom widgets on the left and the right.
Usage¶
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.list import OneLineListItem
KV = '''
ScrollView:
MDList:
id: container
'''
class Test(MDApp):
def build(self):
return Builder.load_string(KV)
def on_start(self):
for i in range(20):
self.root.ids.container.add_widget(
OneLineListItem(text=f"Single-line item {i}")
)
Test().run()
Events of List¶
from kivy.lang import Builder
from kivymd.app import MDApp
KV = '''
ScrollView:
MDList:
OneLineAvatarIconListItem:
on_release: print("Click!")
IconLeftWidget:
icon: "github"
OneLineAvatarIconListItem:
on_release: print("Click 2!")
IconLeftWidget:
icon: "gitlab"
'''
class MainApp(MDApp):
def build(self):
return Builder.load_string(KV)
MainApp().run()
OneLineListItem¶
OneLineListItem:
text: "Single-line item"
TwoLineListItem¶
TwoLineListItem:
text: "Two-line item"
secondary_text: "Secondary text here"
ThreeLineListItem¶
ThreeLineListItem:
text: "Three-line item"
secondary_text: "This is a multi-line label where you can"
tertiary_text: "fit more text than usual"
OneLineAvatarListItem¶
OneLineAvatarListItem:
text: "Single-line item with avatar"
ImageLeftWidget:
source: "data/logo/kivy-icon-256.png"
TwoLineAvatarListItem¶
TwoLineAvatarListItem:
text: "Two-line item with avatar"
secondary_text: "Secondary text here"
ImageLeftWidget:
source: "data/logo/kivy-icon-256.png"
ThreeLineAvatarListItem¶
ThreeLineAvatarListItem:
text: "Three-line item with avatar"
secondary_text: "Secondary text here"
tertiary_text: "fit more text than usual"
ImageLeftWidget:
source: "data/logo/kivy-icon-256.png"
OneLineIconListItem¶
OneLineIconListItem:
text: "Single-line item with avatar"
IconLeftWidget:
icon: "language-python"
TwoLineIconListItem¶
TwoLineIconListItem:
text: "Two-line item with avatar"
secondary_text: "Secondary text here"
IconLeftWidget:
icon: "language-python"
ThreeLineIconListItem¶
ThreeLineIconListItem:
text: "Three-line item with avatar"
secondary_text: "Secondary text here"
tertiary_text: "fit more text than usual"
IconLeftWidget:
icon: "language-python"
OneLineAvatarIconListItem¶
OneLineAvatarIconListItem:
text: "One-line item with avatar"
IconLeftWidget:
icon: "plus"
IconRightWidget:
icon: "minus"
TwoLineAvatarIconListItem¶
TwoLineAvatarIconListItem:
text: "Two-line item with avatar"
secondary_text: "Secondary text here"
IconLeftWidget:
icon: "plus"
IconRightWidget:
icon: "minus"
ThreeLineAvatarIconListItem¶
ThreeLineAvatarIconListItem:
text: "Three-line item with avatar"
secondary_text: "Secondary text here"
tertiary_text: "fit more text than usual"
IconLeftWidget:
icon: "plus"
IconRightWidget:
icon: "minus"
Custom list item¶
from kivy.lang import Builder
from kivy.properties import StringProperty
from kivymd.app import MDApp
from kivymd.uix.list import IRightBodyTouch, OneLineAvatarIconListItem
from kivymd.uix.selectioncontrol import MDCheckbox
from kivymd.icon_definitions import md_icons
KV = '''
<ListItemWithCheckbox>:
IconLeftWidget:
icon: root.icon
RightCheckbox:
BoxLayout:
ScrollView:
MDList:
id: scroll
'''
class ListItemWithCheckbox(OneLineAvatarIconListItem):
'''Custom list item.'''
icon = StringProperty("android")
class RightCheckbox(IRightBodyTouch, MDCheckbox):
'''Custom right container.'''
class MainApp(MDApp):
def build(self):
return Builder.load_string(KV)
def on_start(self):
icons = list(md_icons.keys())
for i in range(30):
self.root.ids.scroll.add_widget(
ListItemWithCheckbox(text=f"Item {i}", icon=icons[i])
)
MainApp().run()
from kivy.lang import Builder
from kivymd.app import MDApp
from kivymd.uix.boxlayout import MDBoxLayout
from kivymd.uix.list import IRightBodyTouch
KV = '''
OneLineAvatarIconListItem:
text: "One-line item with avatar"
on_size:
self.ids._right_container.width = container.width
self.ids._right_container.x = container.width
IconLeftWidget:
icon: "cog"
Container:
id: container
MDIconButton:
icon: "minus"
MDIconButton:
icon: "plus"
'''
class Container(IRightBodyTouch, MDBoxLayout):
adaptive_width = True
class MainApp(MDApp):
def build(self):
return Builder.load_string(KV)
MainApp().run()
API - kivymd.uix.list
¶
- class kivymd.uix.list.MDList(**kwargs)¶
ListItem container. Best used in conjunction with a
kivy.uix.ScrollView
.When adding (or removing) a widget, it will resize itself to fit its children, plus top and bottom paddings as described by the MD spec.
- 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)
- remove_widget(self, widget)¶
Remove a widget from the children of this widget.
- Parameters
- widget:
Widget
Widget to remove from our children list.
- widget:
>>> from kivy.uix.button import Button >>> root = Widget() >>> button = Button() >>> root.add_widget(button) >>> root.remove_widget(button)
- class kivymd.uix.list.BaseListItem(**kwargs)¶
Base class to all ListItems. Not supposed to be instantiated on its own.
- text¶
Text shown in the first line.
text
is aStringProperty
and defaults to ‘’.
- text_color¶
Text color in
rgba
format used iftheme_text_color
is set to ‘Custom’.text_color
is aColorProperty
and defaults to None.
- font_style¶
Text font style. See
kivymd.font_definitions.py
.font_style
is aStringProperty
and defaults to ‘Subtitle1’.
- theme_text_color¶
Theme text color in
rgba
format for primary text.theme_text_color
is aStringProperty
and defaults to ‘Primary’.
- secondary_text¶
Text shown in the second line.
secondary_text
is aStringProperty
and defaults to ‘’.
- tertiary_text¶
The text is displayed on the third line.
tertiary_text
is aStringProperty
and defaults to ‘’.
- secondary_text_color¶
Text color in
rgba
format used for secondary text ifsecondary_theme_text_color
is set to ‘Custom’.secondary_text_color
is aColorProperty
and defaults to None.
- tertiary_text_color¶
Text color in
rgba
format used for tertiary text iftertiary_theme_text_color
is set to ‘Custom’.tertiary_text_color
is aColorProperty
and defaults to None.
- secondary_theme_text_color¶
Theme text color for secondary text.
secondary_theme_text_color
is aStringProperty
and defaults to ‘Secondary’.
- tertiary_theme_text_color¶
Theme text color for tertiary text.
tertiary_theme_text_color
is aStringProperty
and defaults to ‘Secondary’.
- secondary_font_style¶
Font style for secondary line. See
kivymd.font_definitions.py
.secondary_font_style
is aStringProperty
and defaults to ‘Body1’.
- tertiary_font_style¶
Font style for tertiary line. See
kivymd.font_definitions.py
.tertiary_font_style
is aStringProperty
and defaults to ‘Body1’.
- divider¶
Divider mode. Available options are: ‘Full’, ‘Inset’ and default to ‘Full’.
divider
is aOptionProperty
and defaults to ‘Full’.
- bg_color¶
Background color for menu item.
bg_color
is aColorProperty
and defaults to None.
- class kivymd.uix.list.ILeftBody¶
Pseudo-interface for widgets that go in the left container for ListItems that support it.
Implements nothing and requires no implementation, for annotation only.
- class kivymd.uix.list.ILeftBodyTouch¶
Same as
ILeftBody
, but allows the widget to receive touch events instead of triggering the ListItem’s ripple effect.
- class kivymd.uix.list.IRightBody¶
Pseudo-interface for widgets that go in the right container for ListItems that support it.
Implements nothing and requires no implementation, for annotation only.
- class kivymd.uix.list.IRightBodyTouch¶
Same as
IRightBody
, but allows the widget to receive touch events instead of triggering theListItem
’s ripple effect
- class kivymd.uix.list.ContainerSupport¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.- add_widget(self, widget, index=0)¶
- remove_widget(self, widget)¶
- on_touch_down(self, touch)¶
- on_touch_move(self, touch, *args)¶
- on_touch_up(self, touch)¶
- propagate_touch_to_touchable_widgets(self, touch, touch_event, *args)¶
- class kivymd.uix.list.OneLineListItem(**kwargs)¶
A one line list item.
- class kivymd.uix.list.TwoLineListItem(**kwargs)¶
A two line list item.
- class kivymd.uix.list.ThreeLineListItem(**kwargs)¶
A three line list item.
- class kivymd.uix.list.OneLineAvatarListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.TwoLineAvatarListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.ThreeLineAvatarListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.OneLineIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.TwoLineIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.ThreeLineIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.OneLineRightIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.TwoLineRightIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.ThreeLineRightIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.OneLineAvatarIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.TwoLineAvatarIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.ThreeLineAvatarIconListItem(**kwargs)¶
Overrides
add_widget
in aListItem
to include support forI*Body
widgets when the appropiate containers are present.
- class kivymd.uix.list.ImageLeftWidget(**kwargs)¶
Pseudo-interface for widgets that go in the left container for ListItems that support it.
Implements nothing and requires no implementation, for annotation only.
- class kivymd.uix.list.ImageRightWidget(**kwargs)¶
Same as
IRightBody
, but allows the widget to receive touch events instead of triggering theListItem
’s ripple effect
- class kivymd.uix.list.IconRightWidget(**kwargs)¶
Same as
IRightBody
, but allows the widget to receive touch events instead of triggering theListItem
’s ripple effect