Added new files associated with improved selection refactor.

kivy/adapters/models.py

@@ -0,0 +1,59 @@
+'''
+Data Models
+===========
+
+Kivy is open about the type of data used in applications built with
+the system. However, base classes are optionally needed to conform data to
+requirements of some parts of the system.
+
+:class:`SelectableDataItem` is a basic `Python data model`_ class that can be
+used as a mixin to build data objects that are compatible with Kivy's adapter
+and selection system, which works with views such as ListView. The boolean
+property is_selected is the requirement.
+
+The default operation of the selection system is to not propogate selection in
+views such as ListView to the underlying data -- selection is by default a
+view-only operation. However, in some cases, it is useful to propogate
+selection to the actual data items.
+
+You may, of course, build your own Python data model system as the backend for
+a Kivy application. For instance, to use the `Google App Engine datamodeling`_
+system with Kivy, this class could be redefined as:
+
+    from google.appengine.ext import db
+
+    class SelectableDataItem(db.Model):
+        ... other properties
+        is_selected = db.BooleanProperty()
+
+.. _Python data model: http://docs.python.org/reference/datamodel.html
+
+.. _Google App Engine datamodeling:
+https://developers.google.com/appengine/docs/python/datastore/datamodeling
+'''
+
+class SelectableDataItem(object):
+    '''
+    A mixin class containing requirements for selection operations.
+
+    This is the is_selected boolean.
+    '''
+
+    def __init__(self, **kwargs):
+        super(SelectableDataItem, self).__init__()
+
+        self._is_selected = kwargs.get('is_selected', False)
+
+    @property
+    def is_selected(self):
+        """Is the data item selected"""
+        return self._is_selected
+
+    @is_selected.setter
+    def is_selected(self, value):
+        self._is_selected = value
+
+    @is_selected.deleter
+    def is_selected(self):
+        self._is_selected = None
+

kivy/uix/selectableview.py

@@ -0,0 +1,35 @@
+from kivy.properties import NumericProperty, BooleanProperty
+
+
+class SelectableView(object):
+    '''The :class:`SelectableView` mixin is used in list item and other
+    classes that are to be instantiated in a list view, or another class
+    which uses a selection-enabled adapter such as ListAdapter.  select() and
+    deselect() are to be overridden with display code to mark items as
+    selected or not, if desired.
+    '''
+
+    index = NumericProperty(-1)
+    '''The index into the underlying data list or the data item this view
+    represents.
+    '''
+
+    is_selected = BooleanProperty(False)
+    '''A SelectableView instance carries this property, which should be kept
+    in sync with the equivalent property in the data item it represents.
+    '''
+
+    def __init__(self, **kwargs):
+        super(SelectableView, self).__init__(**kwargs)
+
+    def select(self, *args):
+        '''The list item is responsible for updating the display for
+        being selected, if desired.
+        '''
+        self.is_selected = True
+
+    def deselect(self, *args):
+        '''The list item is responsible for updating the display for
+        being unselected, if desired.
+        '''
+        self.is_selected = False