Table Of Contents

• RecycleView Layouts

RecycleView Layouts

New in version 1.10.0.

The Layouts handle the presentation of views for the RecycleView.

Warning

This module is highly experimental, its API may change in the future and the documentation is not complete at this time.

exception kivy.uix.recycleview.layout.LayoutChangeException

Bases: Exception

class kivy.uix.recycleview.layout.LayoutSelectionBehavior(**kwargs)

Bases: kivy.uix.behaviors.compoundselection.CompoundSelectionBehavior

The LayoutSelectionBehavior can be combined with RecycleLayoutManagerBehavior to allow its derived classes selection behaviors similarly to how CompoundSelectionBehavior can be used to add selection behaviors to normal layout.

RecycleLayoutManagerBehavior manages its children differently than normal layouts or widgets so this class adapts CompoundSelectionBehavior based selection to work with RecycleLayoutManagerBehavior as well.

Similarly to CompoundSelectionBehavior, one can select using the keyboard or touch, which calls select_node() or deselect_node(), or one can call these methods directly. When a item is selected or deselected apply_selection() is called. See apply_selection().

apply_selection(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 select_node() or 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 RecycleDataViewBehavior, its 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.

deselect_node(node)

Deselects a possibly selected node.

It is called by the controller when it deselects a node and can also be called from the outside to deselect a node directly. The derived widget should overwrite this method and change the node to its unselected state when this is called

Parameters

node

The node to be deselected.

Warning

This method must be called by the derived widget using super if it is overwritten.

get_index_of_node(node, selectable_nodes)

(internal) Returns the index of the node within the selectable_nodes returned by get_selectable_nodes().

get_selectable_nodes()

(internal) Returns a list of the nodes that can be selected. It can be overwritten by the derived widget to return the correct list.

This list is used to determine which nodes to select with group selection. E.g. the last element in the list will be selected when home is pressed, pagedown will move (or add to, if shift is held) the selection from the current position by negative page_count nodes starting from the position of the currently selected node in this list and so on. Still, nodes can be selected even if they are not in this list.

Note

It is safe to dynamically change this list including removing, adding, or re-arranging its elements. Nodes can be selected even if they are not on this list. And selected nodes removed from the list will remain selected until deselect_node() is called.

Warning

Layouts display their children in the reverse order. That is, the contents of children is displayed form right to left, bottom to top. Therefore, internally, the indices of the elements returned by this function are reversed to make it work by default for most layouts so that the final result is consistent e.g. home, although it will select the last element in this list visually, will select the first element when counting from top to bottom and left to right. If this behavior is not desired, a reversed list should be returned instead.

Defaults to returning children.

goto_node(key, last_node, last_node_idx)

(internal) Used by the controller to get the node at the position indicated by key. The key can be keyboard inputs, e.g. pageup, or scroll inputs from the mouse scroll wheel, e.g. scrollup. ‘last_node’ is the last node selected and is used to find the resulting node. For example, if the key is up, the returned node is one node up from the last node.

It can be overwritten by the derived widget.

Parameters

key

str, the string used to find the desired node. It can be any of the keyboard keys, as well as the mouse scrollup, scrolldown, scrollright, and scrollleft strings. If letters are typed in quick succession, the letters will be combined before it’s passed in as key and can be used to find nodes that have an associated string that starts with those letters.

last_node

The last node that was selected.

last_node_idx

The cached index of the last node selected in the get_selectable_nodes() list. If the list hasn’t changed it saves having to look up the index of last_node in that list.

Returns

tuple, the node targeted by key and its index in the get_selectable_nodes() list. Returning (last_node, last_node_idx) indicates a node wasn’t found.

key_selection

The key used to check whether a view of a data item can be selected with touch or the keyboard.

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.

key_selection is a StringProperty and defaults to None.

Note

All data items can be selected directly using select_node() or deselect_node(), even if key_selection is False.

select_node(node)

Selects a node.

It is called by the controller when it selects a node and can be called from the outside to select a node directly. The derived widget should overwrite this method and change the node state to selected when called.

Parameters

node

The node to be selected.

Returns

bool, True if the node was selected, False otherwise.

Warning

This method must be called by the derived widget using super if it is overwritten.

class kivy.uix.recycleview.layout.RecycleLayoutManagerBehavior

Bases: builtins.object

A RecycleLayoutManagerBehavior is responsible for positioning views into the RecycleView.data within a RecycleView. It adds new views into the data when it becomes visible to the user, and removes them when they leave the visible area.

compute_visible_views(data, viewport)

viewport is in coordinates of the layout manager.

get_view_index_at(pos)

Return the view index on which position, pos, falls.

pos is in coordinates of the layout manager.

goto_view(index)

Moves the views so that the view corresponding to index is visible.

key_viewclass

See RecyclerView.key_viewclass.

refresh_view_layout(index, layout, view, viewport)

See :meth:`~kivy.uix.recycleview.views.RecycleDataAdapter.refresh_view_layout.

set_visible_views(indices, data, viewport)

viewport is in coordinates of the layout manager.

viewclass

See RecyclerView.viewclass.

« RecycleView Data Model

RecycleView Views »