kivy/kivy — pull request #765 by geojeff (2012-10-25 01:04:37+00:00)
Title: Uix listview

Work toward this pull request started with discussions with Mathieu Virbel (tito) about adding a list view, and about how selection could be introduced. tito's gist was a starting point:

https://gist.github.com/3010607

The idea of an adapter, working as a bridge between data and views such as list view, comes from Android programming.

In the process of introducing selection, systems that have controllers doing the work of bridging views to data were consulted.

The system of selection used in the adapters in this pull request was added, however, not by explicitly following some example, but by experimentation, with the goal to combine an optional auto-selection functionality with the Kivy bindings system. Although the terminology and philosophy related to the terms "adapter" and "controller" need more attention and discussion for clarification, code in this pull request demonstrates the desired functionality. The more advanced examples show multiple lists, whose content dynamically changes with selection.

In addition to the selection and bindings aspect described above, work for this pull request included implementing and expanding the kv template example in the gist linked above, and an additional way to build composite list views.

More exploration of user interface changes that happen with selection is needed. Presently, only the background color of list item views is changed. Discussion along the way suggested that more work is needed here. Also, animation effects could be introduced.

Principal code added in this pull request includes:

- a new adapters module, kivy/adapters: Adapter is the base class. SimpleListAdapter and ListAdapter are the primary subclasses of Adapter. DictAdapter extends ListAdapter. SimpleListAdapter does not have selection. ListAdapter and DictAdapter do have selection. In addition to the adapters, each in their own source file, the adapters module contains args_converters.py and models.py. A simple args_converter function is needed for SimpleListAdapter. The only model class, SelectableDataItem, is for optional use in selection.

- two source files were added to the uix module: abstractview.py and listview.py. AbstractView is the base class that has adapter as a property. ListView extends AbstractView. listview.py contains additional smaller classes: SelectableView, ListItemButton, ListItemLabel, and CompositeListItem.

[TODO] comments remain in the code.

Tests were added to cover 100% of the adapter code and most of the listview code (no tests yet of the actual scrolling method). Test files added are: test_adapters.py, test_uix_listview.py, and test_selection.py.

A set of examples was added to examples/widgets in a new directory, examples/widgets/lists. Much of the code in the examples was reused in the tests.

Although there are certainly other topics for discussion, at this time several come to mind.

In efforts to get selection and bindings working, data items were treated for some time as needing to possess text and is_selected properties. This is in keeping with some systems that have a formal Model or Record class that includes a minimum set of properties for a data record. With further work, the required involvement of data items in the selection machinery was reconsidered, so that selection could be restricted to the view system. To resolve this question, a boolean property called propagate_selection_to_data was added to ListAdapter (and DictAdapter), with default as False. Inline documentation has brief discussion of this issue.

Also, in the gist linked above, AbstractView contains the adapter property along with a list property and several methods related to keeping a cache of item views, as part of greater efficiency in servicing list view. In development work on selection, a reference was added between adapter and AbstractView(ListView) to tie into the caching system. This reference proved unwieldy. It seemed simpler to move the view caching methods down to the adapters, which work with views already.

Last, work on selection and discussion in irc assumed that the work on selection here, with the new system of adapters, could serve generally for Kivy's other widgets that have a list or collection view aspect. This has potential, but no explicit study has yet been done -- selection here was made to work in adapters, in close association with ListView, the only high-level widget involved (so far).