Quick search

Drop-Down List

New in version 1.4.0.

A versatile drop-down list, that can be used with custom widget. It allow you to display a list of widgets under a displayed widget. Unlike others toolkits, the list of widgets is what you want, it can be simple button, or images etc.

The positioning of the drop-down list is fully automatic: we will always try to place the dropdown list in a way that the user can select an item in the list.

Basic example

A button with a dropdown list of 10 possibles values. All the button within the dropdown list will trigger the dropdown DropDown.select() method. And then, the main button text will display the selection of the dropdown.

from kivy.uix.dropdown import DropDown
from kivy.uix.button import Button

# create a dropdown with 10 button
dropdown = DropDown()
for index in xrange(10):
    btn = Button(text='Value %d' % index, size_hint_y=None, height=44)

    # for each button, attach a callback that will call the select() method
    # on the dropdown. We'll pass the text of the button as the data of the
    # selection.
    btn.bind(on_release=lambda btn: dropdown.select(btn.text))

    # then add the button inside the dropdown
    dropdown.add_widget(btn)

# create a big main button
mainbutton = Button(text='Hello', size_hint=(None, None))

# show the dropdown menu when the main button is released
# note: all the bind() always pass the instance of the caller (here, the
# mainbutton instance) as first argument of the callback (here,
# dropdown.open.).
mainbutton.bind(on_release=dropdown.open)

# one last thing, listen to the selection done in the dropdown list.
# Assign the data to the button text.
dropdown.bind(on_select=lambda instance, x: setattr(mainbutton, 'text', x))

Extending dropdown in Kv

You could create a dropdown directly from kv:

#:kivy 1.4.0
<CustomDropDown>:
    Button:
        text: 'My first Item'
        size_hint_y: None
        height: 44
        on_release: root.select('item1')
    Label:
        text: 'Unselectable item'
        size_hint_y: None
        height: 44
    Button:
        text: 'My second Item'
        size_hint_y: None
        height: 44
        on_release: root.select('item2')

And then, create the associated python class, and use it:

class CustomDropDown(DropDown):
    pass

dropdown = CustomDropDown()
mainbutton = Button(text='Hello', size_hint=(None, None))
mainbutton.bind(on_release=dropdown.open)
dropdown.bind(on_select=lambda instance, x: setattr(mainbutton, 'text', x))
class kivy.uix.dropdown.DropDown(**kwargs)

Bases: kivy.uix.scrollview.ScrollView

DropDown class. See module documentation for more information.

Events :
on_select: data

Fired when a selection is done, with the data of the selection as first argument. Data is what you pass in the select() method as first argument.

attach_to

(internal) Property that will be set to the widget on which the drop down list is attached to.

The method open() will automatically set that property, while dismiss() will set back to None.

auto_width

By default, the width of the dropdown will be the same as the width of the attached widget. Set to False if you want to provide your own width.

container

(internal) Property that will be set to the container of the dropdown list, which is a GridLayout by default.

dismiss(*largs)

Remove the dropdown widget from the iwndow, and detach itself from the attached widget.

dismiss_on_select

By default, the dropdown will be automatically dismissed when a selection have been done. Set to False to prevent the dismiss.

dismiss_on_select is a BooleanProperty, default to True.

max_height

Indicate the maximum height that the dropdown can take. If None, it will take the maximum height available, until the top or bottom of the screen will be reached.

max_height is a NumericProperty, default to None.

open(widget)

Open the dropdown list, and attach to a specific widget. Depending the position of the widget on the window and the height of the dropdown, the placement might be lower or higher off that widget.

select(data)

Call this method to trigger the on_select event, with the data selection. The data can be anything you want.