<commit_before>'''
List View
===========

.. versionadded:: 1.5

.. warning::

    This code is still experimental, and its API is subject to change in a
    future version.

The :class:`~kivy.uix.listview.ListView` implements an
:class:`~kivy.uix.abstractview.AbstractView` as
a vertical, scrollable,pannable list clipped to the scrollview's bounding box
and contains list item view instances.

The :class:`AbstractView` has one property: :class:`~kivy.adapters.adapter`.
The adapter can be one of the following: a
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`, a
:class:`~kivy.adapters.listadapter.ListAdapter` or a
:class:`~kivy.adapters.dictadapter.DictAdapter`. The :class:`Adapter` can make
use of :mod:`~kivy.adapters.args_converters` to prepare you data for passing
into the constructor for each item view instantiation.

For an overview of how all these components fit together, please see the
:mod:`~kivy.adapters` module documentation.

Introduction
------------

Lists are central parts of many software projects. Kivy's approach to lists
includes providing solutions for simple lists, along with a substantial
framework for building lists of moderate to advanced complexity. For a new
user, it can be difficult to ramp up from simple to advanced. For
this reason, Kivy provides an extensive set of examples (with the Kivy package)
that you may wish to run first, to get a taste of the range of functionality
offered. You can tell from the names of the examples that they illustrate the
"ramping up" from simple to advanced:


    * `kivy/examples/widgets/lists/list_simple.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_simple.py>`_
    * `kivy/examples/widgets/lists/list_simple_in_kv.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_simple_in_kv.py>`_
    * `kivy/examples/widgets/lists/list_simple_in_kv_2.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_simple_in_kv_2.py>`_
    * `kivy/examples/widgets/lists/list_master_detail.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_master_detail.py>`_
    * `kivy/examples/widgets/lists/list_two_up.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_two_up.py>`_
    * `kivy/examples/widgets/lists/list_kv.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_kv.py>`_
    * `kivy/examples/widgets/lists/list_composite.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_composite.py>`_
    * `kivy/examples/widgets/lists/list_cascade.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_cascade.py>`_
    * `kivy/examples/widgets/lists/list_cascade_dict.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_cascade_dict.py>`_
    * `kivy/examples/widgets/lists/list_cascade_images.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_cascade_images.py>`_
    * `kivy/examples/widgets/lists/list_ops.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_ops.py>`_

Many of the examples feature selection, some restricting selection to single
selection, where only one item at at time can be selected, and others allowing
multiple item selection. Many of the examples illustrate how selection in one
list can be connected to actions and selections in another view or another list.

Find your own way of reading the documentation here, examining the source code
for the example apps and running the examples. Some may prefer to read the
documentation through first, others may want to run the examples and view their
code. No matter what you do, going back and forth will likely be needed.

Basic Example
-------------

In its simplest form, we make a listview with 100 items::

    from kivy.uix.listview import ListView
    from kivy.base import runTouchApp


    class MainView(ListView):
        def __init__(self, **kwargs):
            super(MainView, self).__init__(
                item_strings=[str(index) for index in range(100)])

    if __name__ == '__main__':
        runTouchApp(MainView())

Or, we could declare the listview using the kv language::

    from kivy.uix.boxlayout import BoxLayout
    from kivy.lang import Builder
    from kivy.base import runTouchApp

    Builder.load_string("""
    <MyListView>:
        ListView:
            item_strings: [str(index) for index in range(100)]
    """)


    class MyListView(BoxLayout):
        pass

    if __name__ == '__main__':
        runTouchApp(MyListView())

Using an Adapter
-------------------

Behind the scenes, the basic example above uses the
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`. When the
constructor for the :class:`~kivy.uix.listview.ListView` sees that only a list
of
strings is provided as an argument (called item_strings), it creates an instance
of :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` using the
list of strings.

Simple in :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` means:
*without selection support*. It is a scrollable list of items that does not
respond to touch events.

To use a :class:`SimpleListAdaper` explicitly when creating a ListView instance,
do::

    simple_list_adapter = SimpleListAdapter(
            data=["Item #{0}".format(i) for i in range(100)],
            cls=Label)

    list_view = ListView(adapter=simple_list_adapter)

The instance of :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` has
a required data argument which contains data items to use for instantiating
Label views for the list view (note the cls=Label argument). The data items are
strings. Each item string is set by the
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` as the *text*
argument for each Label instantiation.

You can declare a ListView with an adapter in a kv file with special attention
given to the way longer python blocks are indented::

    from kivy.uix.modalview import ModalView
    from kivy.uix.listview import ListView
    from kivy.uix.gridlayout import GridLayout
    from kivy.lang import Builder
    from kivy.factory import Factory

    # Note the special nature of indentation in the adapter declaration, where
    # the adapter: is on one line, then the value side must be given at one
    # level of indentation.

    Builder.load_string("""
    #:import label kivy.uix.label
    #:import sla kivy.adapters.simplelistadapter

    <ListViewModal>:
        size_hint: None, None
        size: 400, 400<commit_msg>doc; revisions to uix/listview.py<commit_after>'''
List View
===========

.. versionadded:: 1.5

.. warning::

    This code is still experimental, and its API is subject to change in a
    future version.

The :class:`~kivy.uix.listview.ListView` implements an
:class:`~kivy.uix.abstractview.AbstractView` as
a vertical, scrollable,pannable list clipped to the scrollview's bounding box
and contains list item view instances.

The :class:`AbstractView` has one property: :class:`~kivy.adapters.adapter`.
The adapter can be one of the following: a
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`, a
:class:`~kivy.adapters.listadapter.ListAdapter` or a
:class:`~kivy.adapters.dictadapter.DictAdapter`. The :class:`Adapter` can make
use of :mod:`~kivy.adapters.args_converters` to prepare you data for passing
into the constructor for each item view instantiation.

For an overview of how all these components fit together, please see the
:mod:`~kivy.adapters` module documentation.

Introduction
------------

Lists are central parts of many software projects. Kivy's approach to lists
includes providing solutions for simple lists, along with a substantial
framework for building lists of moderate to advanced complexity. For a new
user, it can be difficult to ramp up from simple to advanced. For
this reason, Kivy provides an extensive set of examples (with the Kivy package)
that you may wish to run first, to get a taste of the range of functionality
offered. You can tell from the names of the examples that they illustrate the
"ramping up" from simple to advanced:


    * `kivy/examples/widgets/lists/list_simple.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_simple.py>`_
    * `kivy/examples/widgets/lists/list_simple_in_kv.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_simple_in_kv.py>`_
    * `kivy/examples/widgets/lists/list_simple_in_kv_2.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_simple_in_kv_2.py>`_
    * `kivy/examples/widgets/lists/list_master_detail.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_master_detail.py>`_
    * `kivy/examples/widgets/lists/list_two_up.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_two_up.py>`_
    * `kivy/examples/widgets/lists/list_kv.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_kv.py>`_
    * `kivy/examples/widgets/lists/list_composite.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_composite.py>`_
    * `kivy/examples/widgets/lists/list_cascade.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_cascade.py>`_
    * `kivy/examples/widgets/lists/list_cascade_dict.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_cascade_dict.py>`_
    * `kivy/examples/widgets/lists/list_cascade_images.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_cascade_images.py>`_
    * `kivy/examples/widgets/lists/list_ops.py <https://github.com/\
kivy/kivy/tree/master/examples/widgets/lists/list_ops.py>`_

Many of the examples feature selection, some restricting selection to single
selection, where only one item at at time can be selected, and others allowing
multiple item selection. Many of the examples illustrate how selection in one
list can be connected to actions and selections in another view or another list.

Find your own way of reading the documentation here, examining the source code
for the example apps and running the examples. Some may prefer to read the
documentation through first, others may want to run the examples and view their
code. No matter what you do, going back and forth will likely be needed.

Basic Example
-------------

In its simplest form, we make a listview with 100 items::

    from kivy.uix.listview import ListView
    from kivy.base import runTouchApp


    class MainView(ListView):
        def __init__(self, **kwargs):
            super(MainView, self).__init__(
                item_strings=[str(index) for index in range(100)])

    if __name__ == '__main__':
        runTouchApp(MainView())

Or, we could declare the listview using the kv language::

    from kivy.uix.boxlayout import BoxLayout
    from kivy.lang import Builder
    from kivy.base import runTouchApp

    Builder.load_string("""
    <MyListView>:
        ListView:
            item_strings: [str(index) for index in range(100)]
    """)


    class MyListView(BoxLayout):
        pass

    if __name__ == '__main__':
        runTouchApp(MyListView())

Using an Adapter
-------------------

Behind the scenes, the basic example above uses the
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`. When the
constructor for the :class:`~kivy.uix.listview.ListView` sees that only a list
of
strings is provided as an argument (called item_strings), it creates a
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` using the
list of strings.

"Simple" in :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` means
*without selection support*. It is a scrollable list of items that does not
respond to touch events.

To use a :class:`SimpleListAdaper` explicitly when creating a ListView instance,
do::

    simple_list_adapter = SimpleListAdapter(
            data=["Item #{0}".format(i) for i in range(100)],
            cls=Label)

    list_view = ListView(adapter=simple_list_adapter)

The instance of :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` has
a required data argument which contains data items to use for instantiating
:class:`~kivy.uix.label.Label` views for the list view (note the cls=Label
argument). The data items are strings. Each item string is set by the
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` as the *text*
argument for each Label instantiation.

You can declare a ListView with an adapter in a kv file with special attention
given to the way longer python blocks are indented::

    from kivy.uix.modalview import ModalView
    from kivy.uix.listview import ListView
    from kivy.uix.gridlayout import GridLayout
    from kivy.lang import Builder
    from kivy.factory import Factory

    # Note the special nature of indentation in the adapter declaration, where
    # the adapter: is on one line, then the value side must be given at one
    # level of indentation.

    Builder.load_string("""
    #:import label kivy.uix.label
    #:import sla kivy.adapters.simplelistadapter

    <ListViewModal>:
        size_hint: None, None
        size: 400, 400
{'fraction_non_alphanumeric': 0.09994667479241258, 'fraction_numerical': 0.0035042279271730024, 'mean_word_length': 4.031812955155232, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 29, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7207863', 'n_tokens_mistral': 4186, 'n_tokens_neox': 3931, 'n_words': 1268}