Kivy RecycleView as an alternative to ListView? How does it work?

Question

I should preface that I'm still a newbie to Kivy. I tried looking for similar questions, but they were either outdated or unclear.

I was looking for something to display a list of elements among which a used could select one to interact with other widgets (buttons and so on). I stumbled upon the documentation page on ListView, but it clearly states that ListView is deprecated and RecycleView must be used instead.

Now the problem is that the documentation doesn't seem very clear (at least to me) about how to use RecycleView. It's definitely more complicated than other widgets and I can't seem to figure it out.

To break this down into more digestible questions: 1. How do I define a RecycleView that acts as a list of items? 2. How do I provide the items for it? 3. How do I interact with it, specifically about making only one item selectable at a time, detecting when something is selected and automatically making something selected on event?

Oh by the way, I prefer using kv language whenever possible.

I would much appreciate some help with finding or understanding documentation resources that would allow me to understand this more generally for future usage. I really wish there was a tutorial for these complicated features somewhere but if it exists, it's damn hard to find it.

Solution 1

The example below illustrates how to use Recycleview to display a list of buttons and when each button is selected, it display a popup window.

Example

main.py

from kivy.app import App
from kivy.uix.recycleview import RecycleView
from kivy.uix.recycleview.views import RecycleDataViewBehavior
from kivy.uix.button import Button
from kivy.uix.recycleboxlayout import RecycleBoxLayout
from kivy.uix.behaviors import FocusBehavior
from kivy.uix.recycleview.layout import LayoutSelectionBehavior
from kivy.uix.popup import Popup
from kivy.properties import ListProperty, StringProperty, ObjectProperty


class MessageBox(Popup):

    def popup_dismiss(self):
        self.dismiss()


class SelectableRecycleBoxLayout(FocusBehavior, LayoutSelectionBehavior, RecycleBoxLayout):
    """ Adds selection and focus behaviour to the view. """
    selected_value = StringProperty('')
    btn_info = ListProperty(['Button 0 Text', 'Button 1 Text', 'Button 2 Text'])


class SelectableButton(RecycleDataViewBehavior, Button):
    """ Add selection support to the Label """
    index = None

    def refresh_view_attrs(self, rv, index, data):
        """ Catch and handle the view changes """
        self.index = index
        return super(SelectableButton, self).refresh_view_attrs(rv, index, data)

    def on_press(self):
        self.parent.selected_value = 'Selected: {}'.format(self.parent.btn_info[int(self.id)])

    def on_release(self):
        MessageBox().open()


class RV(RecycleView):
    rv_layout = ObjectProperty(None)

    def __init__(self, **kwargs):
        super(RV, self).__init__(**kwargs)
        self.data = [{'text': "Button " + str(x), 'id': str(x)} for x in range(3)]


class TestApp(App):
    title = "RecycleView Button Popup Demo"

    def build(self):
        return RV()


if __name__ == "__main__":
    TestApp().run()

test.kv

#:kivy 1.10.0

<MessageBox>:
    title: 'Popup Message Box'
    size_hint: None, None
    size: 400, 400

    BoxLayout:
        orientation: 'vertical'
        Label:
            text: app.root.rv_layout.selected_value
        Button:
            size_hint: 1, 0.2
            text: 'OK'
            on_press:
                root.dismiss()

<SelectableButton>:
    # Draw a background to indicate selection
    canvas.before:
        Color:
            rgba: (0.0, 0.9, 0.1, 0.3)
        Rectangle:
            pos: self.pos
            size: self.size

<RV>:
    rv_layout: layout
    viewclass: 'SelectableButton'
    SelectableRecycleBoxLayout:
        id: layout
        default_size: None, dp(56)
        default_size_hint: 0.1, None
        size_hint_y: None
        height: self.minimum_height
        orientation: "vertical"

Output

Solution 2

I did a simpler example. In my example is possible to change the layout of each line including Widgets in the class RecycleViewRow in kv language. I already put a Label and a Button in each line as an example. I hope this helps more.

from kivy.app import App
from kivy.lang import Builder
from kivy.properties import StringProperty
from kivy.uix.boxlayout import BoxLayout
from kivy.uix.recycleview import RecycleView
from kivy.uix.popup import Popup

Builder.load_string('''
#:kivy 1.10.0
#: import Popup kivy.uix.popup

<MessageBox>:
    title: 'Popup Message Box'
    size_hint: None, None
    size: 400, 400

    BoxLayout:
        orientation: 'vertical'
        Label:
            text: root.message
        Button:
            size_hint: 1, 0.2
            text: 'OK'
            on_press: root.dismiss()

<RecycleViewRow>:
    orientation: 'horizontal'
    Label:
        text: root.text
    Button:
        text: 'Show'
        on_press: app.root.message_box(root.text)

<MainScreen>:
    viewclass: 'RecycleViewRow'
    RecycleBoxLayout:
        default_size: None, dp(56)
        default_size_hint: 1, None
        size_hint_y: None
        height: self.minimum_height
        orientation: 'vertical'                    
                    ''')

class MessageBox(Popup):
    message = StringProperty()

class RecycleViewRow(BoxLayout):
    text = StringProperty()   

class MainScreen(RecycleView):    
    def __init__(self, **kwargs):
        super(MainScreen, self).__init__(**kwargs)
        self.data = [{'text': "Button " + str(x), 'id': str(x)} for x in range(3)]

    def message_box(self, message):
        p = MessageBox()
        p.message = message
        p.open() 
        print('test press: ', message)

class TestApp(App):
    title = "RecycleView Direct Test"

    def build(self):
        return MainScreen()

if __name__ == "__main__":
    TestApp().run()

Comments

[theberzi]

I appreciate your answer. I evidently still lack understanding of some basic concepts to fully grasp every part of your code, but I'll study it thoroughly. Thanks.

[shamilpython]

Where do you define the RecycleBoxLayout?

[Randolfo]

@shamilpython You don't need to define it, it's defined in module kivy.uix.recycleboxlayout, but the widgets used are defined in the class RecycleViewRow.