List#

#

Lists are continuous, vertical indexes of text or images.

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/lists.png
  • Use lists to help users find a specific item and act on it;

  • Order list items in logical ways (like alphabetical or numerical);

  • Three sizes: one-line, two-line, and three-line;

  • Keep items short and easy to scan;

  • Show icons, text, and actions in a consistent format;

Usage#

MDListItem:

    MDListItemLeadingIcon:  # MDListItemLeadingAvatar

    MDListItemHeadlineText:

    MDListItemSupportingText:

    MDListItemTertiaryText:

    MDListItemTrailingIcon:  # MDListItemTrailingCheckbox

Anatomy#

https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/lists-anatomy.png

Example:#

One line list item#

from kivy.lang import Builder

from kivymd.app import MDApp

KV = '''
MDScreen:
    md_bg_color: self.theme_cls.backgroundColor

    MDListItem:
        pos_hint: {"center_x": .5, "center_y": .5}
        size_hint_x: .8

        MDListItemHeadlineText:
            text: "Headline"
'''


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


Example().run()
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-list.gif

Two line list item#

MDListItem:

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-list.png

Three line list item#

MDListItem:

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-list.png

List item with leading icon#

MDListItem:

    MDListItemLeadingIcon:
        icon: "account"

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-leading-icon-list.png

List item with trailing icon#

MDListItem:

    MDListItemLeadingIcon:
        icon: "account"

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"

    MDListItemTrailingIcon:
        icon: "trash-can-outline"
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-leading-trailing-icon-list.png

List item with trailing check#

MDListItem:

    MDListItemLeadingIcon:
        icon: "account"

    MDListItemHeadlineText:
        text: "Headline"

    MDListItemSupportingText:
        text: "Supporting text"

    MDListItemTertiaryText:
        text: "Tertiary text"

    MDListItemTrailingCheckbox:
https://github.com/HeaTTheatR/KivyMD-data/raw/master/gallery/kivymddoc/headline-supporting-tertiary-leading-trailing-check-list.png

API - kivymd.uix.list.list#

class kivymd.uix.list.list.MDList(*args, **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.

For more information, see in the MDGridLayout class documentation.

class kivymd.uix.list.list.BaseListItem(*args, **kwargs)#

Base class for list items.

For more information, see in the DeclarativeBehavior and BackgroundColorBehavior and RectangularRippleBehavior and ButtonBehavior and ThemableBehavior and StateLayerBehavior classes documentation.

divider#

Should I use divider for a list item.

divider is an BooleanProperty and defaults to False.

divider_color#

The divider color in (r, g, b, a) or string format.

divider_color is a ColorProperty and defaults to None.

md_bg_color_disabled#

The background color in (r, g, b, a) or string format of the list item when the list item is disabled.

md_bg_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.list.list.BaseListItemText(*args, **kwargs)#

Base class for text labels of a list item.

For more information, see in the MDLabel class documentation.

class kivymd.uix.list.list.BaseListItemIcon(*args, **kwargs)#

Base class for leading/trailing icon of list item.

For more information, see in the MDIcon class documentation.

icon_color#

Icon color in (r, g, b, a) or string format.

icon_color is a ColorProperty and defaults to None.

icon_color_disabled#

The icon color in (r, g, b, a) or string format of the list item when the list item is disabled.

icon_color_disabled is a ColorProperty and defaults to None.

class kivymd.uix.list.list.MDListItemHeadlineText(*args, **kwargs)#

Implements a class for headline text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemSupportingText(*args, **kwargs)#

Implements a class for secondary text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemTertiaryText(*args, **kwargs)#

Implements a class for tertiary text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemTrailingSupportingText(*args, **kwargs)#

Implements a class for trailing text of list item.

For more information, see in the BaseListItemText class documentation.

class kivymd.uix.list.list.MDListItemLeadingIcon(*args, **kwargs)#

Implements a class for leading icon class.

For more information, see in the BaseListItemIcon class documentation.

class kivymd.uix.list.list.MDListItemLeadingAvatar(**kwargs)#

Implements a class for leading avatar class.

For more information, see in the ThemableBehavior and CircularRippleBehavior and ButtonBehavior and FitImage classes documentation.

class kivymd.uix.list.list.MDListItemTrailingIcon(*args, **kwargs)#

Implements a class for trailing icon class.

For more information, see in the BaseListItemIcon class documentation.

class kivymd.uix.list.list.MDListItemTrailingCheckbox(**kwargs)#

Implements a class for trailing checkbox class.

For more information, see in the MDCheckbox class documentation.

class kivymd.uix.list.list.MDListItem(*args, **kwargs)#

Implements a list item.

For more information, see in the BaseListItem and BoxLayout classes documentation.

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)