Table Of Contents
ListAdapter¶
バージョン 1.5 で追加.
バージョン 1.10.0 で撤廃: The feature has been deprecated.
警告
This code is still experimental, and its API is subject to change in a future version.
A ListAdapter
is an adapter around a python list and adds support
for selection operations. If you wish to have a bare-bones list adapter,
without selection, use a
SimpleListAdapter
.
From an Adapter
, a ListAdapter
inherits cls,
template, and args_converter properties and adds others that control selection
behaviour:
selection
: a list of selected items.selection_mode
: one of ‘single’, ‘multiple’ or ‘none’.allow_empty_selection
: a boolean. If False, a selection is forced. If True, and only user or programmatic action will change selection, it can be empty.
A DictAdapter
is a subclass of a
ListAdapter
. They both dispatch the
on_selection_change
event when selection changes.
バージョン 1.6.0 で変更: Added data = ListProperty([]), which was probably inadvertently deleted at some point. This means that whenever data changes an update will fire, instead of having to reset the data object (Adapter has data defined as an ObjectProperty, so we need to reset it here to ListProperty). See also DictAdapter and its set of data = DictProperty().
-
class
kivy.adapters.listadapter.
ListAdapter
(**kwargs)[ソース]¶ ベースクラス:
kivy.adapters.adapter.Adapter
,kivy.event.EventDispatcher
A base class for adapters interfacing with lists, dictionaries or other collection type data, adding selection, view creation and management functionality.
-
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 maintenance of the selection is important for all but simple list displays. Set allow_empty_selection to False and the selection is auto-initialized and always maintained, so any observing views may likewise be updated to stay in sync.
allow_empty_selection
is aBooleanProperty
and defaults to True.
-
cached_views
¶ View instances for data items are instantiated and managed by 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 aDictProperty
and defaults to {}.
-
create_view
(index)[ソース]¶ This method is more complicated than the ones in the
Adapter
andSimpleListAdapter
classes because here we create bindings for the data items and their children back to the self.handle_selection() event. We also perform 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 also cut, 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 bind to data so that any changes will trigger updates. See also how the
DictAdapter
redefines data as aDictProperty
.data
is aListProperty
and defaults to [].
-
on_selection_change
(*args)[ソース]¶ on_selection_change() is the default handler for the on_selection_change event. You can bind to this event to get notified of selection changes.
Parameters: - adapter:
ListAdapter
or subclass The instance of the list adapter where the selection changed. Use the adapters
selection
property to see what has been selected.
- adapter:
-
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 scenarios. 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 for the 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 clash 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 correctly 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 in the data ListProperty might prove convenient in some cases.
注釈
This setting should be set to True if you wish to initialize the view with item views already selected.
propagate_selection_to_data
is aBooleanProperty
and defaults 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 aListProperty
and defaults to [].
-
selection_limit
¶ When the
selection_mode
is ‘multiple’ and the selection_limit is non-negative, this number will limit the number of selected items. It can be set to 1, which is equivalent to single selection. If selection_limit is not set, the default value is -1, meaning that no limit will be enforced.selection_limit
is aNumericProperty
and defaults to -1 (no limit).
-
selection_mode
¶ The selection_mode is a string and can be set to one of the following values:
- ‘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.
A
ListAdapter
is not meant to be used as a primary no-selection list adapter. Use aSimpleListAdapter
for that. - ‘single’: multi-touch/click ignored. Single item selection only.
- ‘multiple’: multi-touch / incremental addition to selection allowed;
may be limited to a count by setting the
selection_limit
.
selection_mode
is anOptionProperty
and defaults to ‘single’.- ‘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.
A
-
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 a selection.
-