ListAdapter¶
New in version 1.5.
Warning
This code is still experimental, and its API is subject to change in a future version.
ListAdapter is an adapter around a python list.
Selection operations are a main concern for the class.
From Adapter, ListAdapter gets cls, template, and args_converter properties.
and adds several for selection:
- selection, a list of selected items.
- selection_mode, ‘single’, ‘multiple’, ‘none’
- allow_empty_selection, a boolean – False, and a selection is forced; True, and only user or programmatic action will change selection, and it can be empty.
and several methods used in selection operations.
If you wish to have a bare-bones list adapter, without selection, use SimpleListAdapter.
DictAdapter is a subclass of ListAdapter. They both dispatch the on_selection_change event.
Events:
- on_selection_change: (view, view list )
Fired when selection changes
Changed in version 1.6.0.
- class kivy.adapters.listadapter.ListAdapter(**kwargs)¶
Bases: kivy.adapters.adapter.Adapter, kivy.event.EventDispatcher
A base class for adapters interfacing with lists, dictionaries, or other collection type data, adding selection and view creation and management functonality.
- allow_empty_selection¶
The allow_empty_selection may be used for cascading selection between several list views, or between a list view and an observing view. Such automatic maintainence of selection is important for all but simple list displays. Set allow_empty_selection False, so that selection is auto-initialized, and always maintained, and so that any observing views may likewise be updated to stay in sync.
allow_empty_selection is a BooleanProperty, default to True.
- cached_views¶
View instances for data items are instantiated and managed in the adapter. Here we maintain a dictionary containing the view instances keyed to the indices in the data.
This dictionary works as a cache. get_view() only asks for a view from the adapter if one is not already stored for the requested index.
cached_views is a DictProperty, default to {}.
- create_view(index)¶
This method is more complicated than the one in kivy.adapters.adapter.Adapter and kivy.adapters.simplelistadapter.SimpleListAdapter, because here we create bindings for the data item, and its children back to self.handle_selection(), and do other selection-related tasks to keep item views in sync with the data.
- cut_to_sel(*args)¶
Same as trim_to_sel, but intervening list items within the selected range are cut also, leaving only list items that are selected.
- data¶
The data list property is redefined here, overriding its definition as an ObjectProperty in the Adapter class.. We will bind to data and want any changes to trigger updates. See also how DictAdapter redefines data as DictProperty.
data is a ListProperty, default to [].
- on_selection_change(*args)¶
on_selection_change() is the default handler for the on_selection_change event.
- propagate_selection_to_data¶
Normally, data items are not selected/deselected, because the data items might not have an is_selected boolean property – only the item view for a given data item is selected/deselected, as part of the maintained selection list. However, if the data items do have an is_selected property, or if they mix in SelectableDataItem, the selection machinery can propagate selection to data items. This can be useful for storing selection state in a local database or backend database for maintaining state in game play or other similar needs. It is a convenience function.
To propagate selection or not?
Consider a shopping list application for shopping for fruits at the market. The app allows selection of fruits to buy for each day of the week, presenting seven lists, one for each day of the week. Each list is loaded with all the available fruits, but the selection for each is a subset. There is only one set of fruit data shared between the lists, so it would not make sense to propagate selection to the data, because selection in any of the seven lists would clobber and mix with that of the others.
However, consider a game that uses the same fruits data for selecting fruits available for fruit-tossing. A given round of play could have a full fruits list, with fruits available for tossing shown selected. If the game is saved and rerun, the full fruits list, with selection marked on each item, would be reloaded fine if selection is always propagated to the data. You could accomplish the same functionality by writing code to operate on list selection, but having selection stored on the data might prove convenient in some cases.
propagate_selection_to_data is a BooleanProperty, default to False.
- select_list(view_list, extend=True)¶
The select call is made for the items in the provided view_list.
Arguments:
view_list: the list of item views to become the new selection, or to add to the existing selection
extend: boolean for whether or not to extend the existing list
- selection¶
The selection list property is the container for selected items.
selection is a ListProperty, default to [].
- selection_limit¶
When selection_mode is multiple, if selection_limit is non-negative, this number will limit the number of selected items. It can even be 1, which is equivalent to single selection. This is because a program could be programmatically changing selection_limit on the fly, and all possible values should be included.
If selection_limit is not set, the default is -1, meaning that no limit will be enforced.
selection_limit is a NumericProperty, default to -1 (no limit).
- selection_mode¶
Selection modes:
- none, use the list as a simple list (no select action). This option is here so that selection can be turned off, momentarily or permanently, for an existing list adapter. ListAdapter is not meant to be used as a primary no-selection list adapter. Use SimpleListAdapter for that.
- single, multi-touch/click ignored. single item selecting only
- multiple, multi-touch / incremental addition to selection allowed; may be limited to a count by selection_limit
selection_mode is an OptionProperty, default to ‘single’.
- trim_left_of_sel(*args)¶
Cut list items with indices in sorted_keys that are less than the index of the first selected item, if there is selection.
- trim_right_of_sel(*args)¶
Cut list items with indices in sorted_keys that are greater than the index of the last selected item, if there is selection.
- trim_to_sel(*args)¶
Cut list items with indices in sorted_keys that are les than or greater than the index of the last selected item, if there is selection. This preserves intervening list items within the selected range.