kivymd.list module

Lists

Material Design spec, Lists page

Material Design spec, Lists: Controls page

The class MDList in combination with a ListItem like OneLineListItem will create a list that expands as items are added to it, working nicely with Kivy’s ScrollView.

Simple examples

Kv Lang:

ScrollView:
    do_scroll_x: False  # Important for MD compliance
    MDList:
        OneLineListItem:
            text: "Single-line item"
        TwoLineListItem:
            text: "Two-line item"
            secondary_text: "Secondary text here"
        ThreeLineListItem:
            text: "Three-line item"
            secondary_text: "This is a multi-line label where you can fit more text than usual"

Python:

# Sets up ScrollView with MDList, as normally used in Android:
sv = ScrollView()
ml = MDList()
sv.add_widget(ml)

contacts = ["Paula", "John", "Kate", "Vlad"]
for c in contacts:
    ml.add_widget(
        OneLineListItem(
            text=c
        )
    )

Advanced usage

Due to the variety in sizes and controls in the MD spec, this module suffers from a certain level of complexity to keep the widgets compliant, flexible and performant.

For this KivyMD provides ListItems that try to cover the most common usecases, when those are insufficient, there’s a base class called ListItem which you can use to create your own ListItems. This documentation will only cover the provided ones, for custom implementations please refer to this module’s source code.

Text only ListItems

These are the simplest ones. The text attribute changes the text in the most prominent line, while secondary_text changes the second and third line.

If there are only two lines, secondary_text will shorten the text to fit in case it is too long; if a third line is available, it will instead wrap the text to make use of it.

ListItems with widget containers

  • OneLineAvatarListItem
  • TwoLineAvatarListItem
  • ThreeLineAvatarListItem
  • OneLineIconListItem
  • TwoLineIconListItem
  • ThreeLineIconListItem
  • OneLineAvatarIconListItem
  • TwoLineAvatarIconListItem
  • ThreeLineAvatarIconListItem

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.

Python example:

class ContactPhoto(ILeftBody, AsyncImage):
    pass

class MessageButton(IRightBodyTouch, MDIconButton):
    phone_number = StringProperty()

    def on_release(self):
        # sample code:
        Dialer.send_sms(phone_number, "Hey! What's up?")
        pass

# Sets up ScrollView with MDList, as normally used in Android:
sv = ScrollView()
ml = MDList()
sv.add_widget(ml)

contacts = [
    ["Annie", "555-24235", "http://myphotos.com/annie.png"],
    ["Bob", "555-15423", "http://myphotos.com/bob.png"],
    ["Claire", "555-66098", "http://myphotos.com/claire.png"]
]

for c in contacts:
    item = TwoLineAvatarIconListItem(
        text=c[0],
        secondary_text=c[1]
    )
    item.add_widget(ContactPhoto(source=c[2]))
    item.add_widget(MessageButton(phone_number=c[1])
    ml.add_widget(item)

API

class kivymd.list.MDList(**kwargs)

Bases: kivy.uix.gridlayout.GridLayout

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.

class kivymd.list.BaseListItem(**kwargs)

Bases: kivymd.theming.ThemableBehavior, kivymd.ripplebehavior.RectangularRippleBehavior, kivy.uix.behaviors.button.ButtonBehavior, kivy.uix.floatlayout.FloatLayout

Base class to all ListItems. Not supposed to be instantiated on its own.

text

Text shown in the first line.

text is a StringProperty and defaults to “”.

text_color

Text color used if theme_text_color is set to ‘Custom’

theme_text_color

Theme text color for primary text

secondary_text

Text shown in the second and potentially third line.

The text will wrap into the third line if the ListItem’s type is set to ‘one-line’. It can be forced into the third line by adding a n escape sequence.

secondary_text is a StringProperty and defaults to “”.

secondary_text_color

Text color used for secondary text if secondary_theme_text_color is set to ‘Custom’

secondary_theme_text_color

Theme text color for secondary primary text

class kivymd.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.list.ILeftBodyTouch

Same as ILeftBody, but allows the widget to receive touch events instead of triggering the ListItem’s ripple effect

class kivymd.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.list.IRightBodyTouch

Same as IRightBody, but allows the widget to receive touch events instead of triggering the ListItem’s ripple effect

class kivymd.list.ContainerSupport

Overrides add_widget in a ListItem to include support for I*Body widgets when the appropiate containers are present.

class kivymd.list.OneLineListItem(**kwargs)

Bases: kivymd.list.BaseListItem

A one line list item

class kivymd.list.TwoLineListItem(**kwargs)

Bases: kivymd.list.BaseListItem

A two line list item

class kivymd.list.ThreeLineListItem(**kwargs)

Bases: kivymd.list.BaseListItem

A three line list item