Kivy-examples 2.3.1.dev0__py3-none-any.whl

kivy/uix/recycleview/datamodel.py

@@ -0,0 +1,194 @@
+'''
+RecycleView Data Model
+======================
+
+.. versionadded:: 1.10.0
+
+The data model part of the RecycleView model-view-controller pattern.
+
+It defines the models (classes) that store the data associated with a
+:class:`~kivy.uix.recycleview.RecycleViewBehavior`. Each model (class)
+determines how the data is stored and emits requests to the controller
+(:class:`~kivy.uix.recycleview.RecycleViewBehavior`) when the data is
+modified.
+'''
+
+from kivy.properties import ListProperty, ObservableDict, ObjectProperty
+from kivy.event import EventDispatcher
+from functools import partial
+
+__all__ = ('RecycleDataModelBehavior', 'RecycleDataModel')
+
+
+def recondition_slice_assign(val, last_len, new_len):
+    if not isinstance(val, slice):
+        return slice(val, val + 1)
+
+    diff = new_len - last_len
+
+    start, stop, step = val.start, val.stop, val.step
+    if stop <= start:
+        return slice(0, 0)
+
+    if step is not None and step != 1:
+        assert last_len == new_len
+        if stop < 0:
+            stop = max(0, last_len + stop)
+        stop = min(last_len, stop)
+
+        if start < 0:
+            start = max(0, last_len + start)
+        start = min(last_len, start)
+
+        return slice(start, stop, step)
+
+    if start < 0:
+        start = last_len + start
+    if stop < 0:
+        stop = last_len + stop
+
+    # whatever, too complicated don't try to compute it
+    if (start < 0 or stop < 0 or start > last_len or stop > last_len or
+            new_len != last_len):
+        return None
+
+    return slice(start, stop)
+
+
+class RecycleDataModelBehavior(object):
+    """:class:`RecycleDataModelBehavior` is the base class for the models
+    that describes and provides the data for the
+    :class:`~kivy.uix.recycleview.RecycleViewBehavior`.
+
+    :Events:
+        `on_data_changed`:
+            Fired when the data changes. The event may dispatch
+            keyword arguments specific to each implementation of the data
+            model.
+            When dispatched, the event and keyword arguments are forwarded to
+            :meth:`~kivy.uix.recycleview.RecycleViewBehavior.\
+refresh_from_data`.
+    """
+
+    __events__ = ("on_data_changed", )
+
+    recycleview = ObjectProperty(None, allownone=True)
+    '''The
+    :class:`~kivy.uix.recycleview.RecycleViewBehavior` instance
+    associated with this data model.
+    '''
+
+    def attach_recycleview(self, rv):
+        '''Associates a
+        :class:`~kivy.uix.recycleview.RecycleViewBehavior` with
+        this data model.
+        '''
+        self.recycleview = rv
+        if rv:
+            self.fbind('on_data_changed', rv.refresh_from_data)
+
+    def detach_recycleview(self):
+        '''Removes the
+        :class:`~kivy.uix.recycleview.RecycleViewBehavior`
+        associated with this data model.
+        '''
+        rv = self.recycleview
+        if rv:
+            self.funbind('on_data_changed', rv.refresh_from_data)
+        self.recycleview = None
+
+    def on_data_changed(self, *largs, **kwargs):
+        pass
+
+
+class RecycleDataModel(RecycleDataModelBehavior, EventDispatcher):
+    '''An implementation of :class:`RecycleDataModelBehavior` that keeps the
+    data in a indexable list. See :attr:`data`.
+
+    When data changes this class currently dispatches `on_data_changed`  with
+    one of the following additional keyword arguments.
+
+    `none`: no keyword argument
+        With no additional argument it means a generic data change.
+    `removed`: a slice or integer
+        The value is a slice or integer indicating the indices removed.
+    `appended`: a slice
+        The slice in :attr:`data` indicating the first and last new items
+        (i.e. the slice pointing to the new items added at the end).
+    `inserted`: a integer
+        The index in :attr:`data` where a new data item was inserted.
+    `modified`: a slice
+        The slice with the indices where the data has been modified.
+        This currently does not allow changing of size etc.
+    '''
+
+    data = ListProperty([])
+    '''Stores the model's data using a list.
+
+    The data for a item at index `i` can also be accessed with
+    :class:`RecycleDataModel` `[i]`.
+    '''
+
+    _last_len = 0
+
+    def __init__(self, **kwargs):
+        self.fbind('data', self._on_data_callback)
+        super(RecycleDataModel, self).__init__(**kwargs)
+
+    def __getitem__(self, index):
+        return self.data[index]
+
+    @property
+    def observable_dict(self):
+        '''A dictionary instance, which when modified will trigger a `data` and
+        consequently an `on_data_changed` dispatch.
+        '''
+        return partial(ObservableDict, self.__class__.data, self)
+
+    def attach_recycleview(self, rv):
+        super(RecycleDataModel, self).attach_recycleview(rv)
+        if rv:
+            self.fbind('data', rv._dispatch_prop_on_source, 'data')
+
+    def detach_recycleview(self):
+        rv = self.recycleview
+        if rv:
+            self.funbind('data', rv._dispatch_prop_on_source, 'data')
+        super(RecycleDataModel, self).detach_recycleview()
+
+    def _on_data_callback(self, instance, value):
+        last_len = self._last_len
+        new_len = self._last_len = len(self.data)
+        op, val = value.last_op
+
+        if op == '__setitem__':
+            val = recondition_slice_assign(val, last_len, new_len)
+            if val is not None:
+                self.dispatch('on_data_changed', modified=val)
+            else:
+                self.dispatch('on_data_changed')
+        elif op == '__delitem__':
+            self.dispatch('on_data_changed', removed=val)
+        elif op == '__setslice__':
+            val = recondition_slice_assign(slice(*val), last_len, new_len)
+            if val is not None:
+                self.dispatch('on_data_changed', modified=val)
+            else:
+                self.dispatch('on_data_changed')
+        elif op == '__delslice__':
+            self.dispatch('on_data_changed', removed=slice(*val))
+        elif op == '__iadd__' or op == '__imul__':
+            self.dispatch('on_data_changed', appended=slice(last_len, new_len))
+        elif op == 'append':
+            self.dispatch('on_data_changed', appended=slice(last_len, new_len))
+        elif op == 'insert':
+            self.dispatch('on_data_changed', inserted=val)
+        elif op == 'pop':
+            if val:
+                self.dispatch('on_data_changed', removed=val[0])
+            else:
+                self.dispatch('on_data_changed', removed=last_len - 1)
+        elif op == 'extend':
+            self.dispatch('on_data_changed', appended=slice(last_len, new_len))
+        else:
+            self.dispatch('on_data_changed')

kivy/uix/recycleview/layout.py

@@ -0,0 +1,253 @@
+'''
+RecycleView Layouts
+===================
+
+.. versionadded:: 1.10.0
+
+The Layouts handle the presentation of views for the
+:class:`~kivy.uix.recycleview.RecycleView`.
+
+.. warning::
+    This module is highly experimental, its API may change in the future and
+    the documentation is not complete at this time.
+'''
+from kivy.compat import string_types
+from kivy.factory import Factory
+from kivy.properties import StringProperty, ObjectProperty
+from kivy.uix.behaviors import CompoundSelectionBehavior
+from kivy.uix.recycleview.views import RecycleDataViewBehavior, \
+    _view_base_cache
+
+
+class LayoutChangeException(Exception):
+    pass
+
+
+class LayoutSelectionBehavior(CompoundSelectionBehavior):
+    '''The :class:`LayoutSelectionBehavior` can be combined with
+    :class:`RecycleLayoutManagerBehavior` to allow its derived classes
+    selection behaviors similarly to how
+    :class:`~kivy.uix.behaviors.compoundselection.CompoundSelectionBehavior`
+    can be used to add selection behaviors to normal layout.
+
+    :class:`RecycleLayoutManagerBehavior` manages its children
+    differently than normal layouts or widgets so this class adapts
+    :class:`~kivy.uix.behaviors.compoundselection.CompoundSelectionBehavior`
+    based selection to work with :class:`RecycleLayoutManagerBehavior` as well.
+
+    Similarly to
+    :class:`~kivy.uix.behaviors.compoundselection.CompoundSelectionBehavior`,
+    one can select using the keyboard or touch, which calls :meth:`select_node`
+    or :meth:`deselect_node`, or one can call these methods directly. When a
+    item is selected or deselected :meth:`apply_selection` is called. See
+    :meth:`apply_selection`.
+
+
+    '''
+
+    key_selection = StringProperty(None, allownone=True)
+    '''The key used to check whether a view of a data item can be selected
+    with touch or the keyboard.
+
+    :attr:`key_selection` is the key in data, which if present and ``True``
+    will enable selection for this item from the keyboard or with a touch.
+    When None, the default, not item will be selectable.
+
+    :attr:`key_selection` is a :class:`StringProperty` and defaults to None.
+
+    .. note::
+        All data items can be selected directly using :meth:`select_node` or
+        :meth:`deselect_node`, even if :attr:`key_selection` is False.
+    '''
+
+    _selectable_nodes = []
+    _nodes_map = {}
+
+    def __init__(self, **kwargs):
+        self.nodes_order_reversed = False
+        super(LayoutSelectionBehavior, self).__init__(**kwargs)
+
+    def compute_sizes_from_data(self, data, flags):
+        # overwrite this method so that when data changes we update
+        # selectable nodes.
+        key = self.key_selection
+        if key is None:
+            nodes = self._selectable_nodes = []
+        else:
+            nodes = self._selectable_nodes = [
+                i for i, d in enumerate(data) if d.get(key)]
+
+        self._nodes_map = {v: k for k, v in enumerate(nodes)}
+        return super(LayoutSelectionBehavior, self).compute_sizes_from_data(
+            data, flags)
+
+    def get_selectable_nodes(self):
+        # the indices of the data is used as the nodes
+        return self._selectable_nodes
+
+    def get_index_of_node(self, node, selectable_nodes):
+        # the indices of the data is used as the nodes, so node
+        return self._nodes_map[node]
+
+    def goto_node(self, key, last_node, last_node_idx):
+        node, idx = super(LayoutSelectionBehavior, self).goto_node(
+            key, last_node, last_node_idx)
+        if node is not last_node:
+            self.goto_view(node)
+        return node, idx
+
+    def select_node(self, node):
+        if super(LayoutSelectionBehavior, self).select_node(node):
+            view = self.recycleview.view_adapter.get_visible_view(node)
+            if view is not None:
+                self.apply_selection(node, view, True)
+
+    def deselect_node(self, node):
+        if super(LayoutSelectionBehavior, self).deselect_node(node):
+            view = self.recycleview.view_adapter.get_visible_view(node)
+            if view is not None:
+                self.apply_selection(node, view, False)
+
+    def apply_selection(self, index, view, is_selected):
+        '''Applies the selection to the view. This is called internally when
+        a view is displayed and it needs to be shown as selected or as not
+        selected.
+
+        It is called when :meth:`select_node` or :meth:`deselect_node` is
+        called or when a view needs to be refreshed. Its function is purely to
+        update the view to reflect the selection state. So the function may be
+        called multiple times even if the selection state may not have changed.
+
+        If the view is a instance of
+        :class:`~kivy.uix.recycleview.views.RecycleDataViewBehavior`, its
+        :meth:`~kivy.uix.recycleview.views.RecycleDataViewBehavior.\
+apply_selection` method will be called every time the view needs to refresh
+        the selection state. Otherwise, the this method is responsible
+        for applying the selection.
+
+        :Parameters:
+
+            `index`: int
+                The index of the data item that is associated with the view.
+            `view`: widget
+                The widget that is the view of this data item.
+            `is_selected`: bool
+                Whether the item is selected.
+        '''
+        viewclass = view.__class__
+        if viewclass not in _view_base_cache:
+            _view_base_cache[viewclass] = isinstance(view,
+                                                     RecycleDataViewBehavior)
+
+        if _view_base_cache[viewclass]:
+            view.apply_selection(self.recycleview, index, is_selected)
+
+    def refresh_view_layout(self, index, layout, view, viewport):
+        super(LayoutSelectionBehavior, self).refresh_view_layout(
+            index, layout, view, viewport)
+        self.apply_selection(index, view, index in self.selected_nodes)
+
+
+class RecycleLayoutManagerBehavior(object):
+    """A RecycleLayoutManagerBehavior is responsible for positioning views into
+    the :attr:`RecycleView.data` within a :class:`RecycleView`. It adds new
+    views into the data when it becomes visible to the user, and removes them
+    when they leave the visible area.
+    """
+
+    viewclass = ObjectProperty(None)
+    '''See :attr:`RecyclerView.viewclass`.
+    '''
+    key_viewclass = StringProperty(None)
+    '''See :attr:`RecyclerView.key_viewclass`.
+    '''
+
+    recycleview = ObjectProperty(None, allownone=True)
+
+    asked_sizes = None
+
+    def attach_recycleview(self, rv):
+        self.recycleview = rv
+        if rv:
+            fbind = self.fbind
+            # can be made more selective update than refresh_from_data which
+            # causes a full update. But this likely affects most of the data.
+            fbind('viewclass', rv.refresh_from_data)
+            fbind('key_viewclass', rv.refresh_from_data)
+            fbind('viewclass', rv._dispatch_prop_on_source, 'viewclass')
+            fbind('key_viewclass', rv._dispatch_prop_on_source,
+                  'key_viewclass')
+
+    def detach_recycleview(self):
+        self.clear_layout()
+        rv = self.recycleview
+        if rv:
+            funbind = self.funbind
+            funbind('viewclass', rv.refresh_from_data)
+            funbind('key_viewclass', rv.refresh_from_data)
+            funbind('viewclass', rv._dispatch_prop_on_source, 'viewclass')
+            funbind('key_viewclass', rv._dispatch_prop_on_source,
+                  'key_viewclass')
+        self.recycleview = None
+
+    def compute_sizes_from_data(self, data, flags):
+        pass
+
+    def compute_layout(self, data, flags):
+        pass
+
+    def compute_visible_views(self, data, viewport):
+        '''`viewport` is in coordinates of the layout manager.
+        '''
+        pass
+
+    def set_visible_views(self, indices, data, viewport):
+        '''`viewport` is in coordinates of the layout manager.
+        '''
+        pass
+
+    def refresh_view_layout(self, index, layout, view, viewport):
+        '''`See :meth:`~kivy.uix.recycleview.views.RecycleDataAdapter.\
+refresh_view_layout`.
+        '''
+        self.recycleview.view_adapter.refresh_view_layout(
+            index, layout, view, viewport)
+
+    def get_view_index_at(self, pos):
+        """Return the view `index` on which position, `pos`, falls.
+
+        `pos` is in coordinates of the layout manager.
+        """
+        pass
+
+    def remove_views(self):
+        rv = self.recycleview
+        if rv:
+            adapter = rv.view_adapter
+            if adapter:
+                adapter.make_views_dirty()
+
+    def remove_view(self, view, index):
+        rv = self.recycleview
+        if rv:
+            adapter = rv.view_adapter
+            if adapter:
+                adapter.make_view_dirty(view, index)
+
+    def clear_layout(self):
+        rv = self.recycleview
+        if rv:
+            adapter = rv.view_adapter
+            if adapter:
+                adapter.invalidate()
+
+    def goto_view(self, index):
+        '''Moves the views so that the view corresponding to `index` is
+        visible.
+        '''
+        pass
+
+    def on_viewclass(self, instance, value):
+        # resolve the real class if it was a string.
+        if isinstance(value, string_types):
+            self.viewclass = getattr(Factory, value)