mirror of https://github.com/kivy/kivy.git
Formatted for API docs, fixing many :class: references, and other layout problems.
This commit is contained in:
geojeff
parent
739bf32b12
commit
6e9f6146d3
|
|
@ -0,0 +1,35 @@
|
|||
'''
|
||||
Adapters
|
||||
========
|
||||
|
||||
An adapter is an intermediating controller-type class that builds views
|
||||
for top-level widgets, interacting with data as prescribed by parameters.
|
||||
On the view side is :class:`AbstractView`, which is the base view for
|
||||
:class:`ListView`.
|
||||
|
||||
- **Adapters**: The base :class:`Adapter` is subclassed by
|
||||
:class:`SimpleListAdapter` and by :class:`ListAdapter`. Further,
|
||||
:class:`DictAdapter` is subclass of :class:`ListAdapter`.
|
||||
|
||||
:doc:`api-kivy.adapters.adapter`,
|
||||
:doc:`api-kivy.adapters.simplelistadapter`,
|
||||
:doc:`api-kivy.adapters.listadapter`,
|
||||
:doc:`api-kivy.adapters.dictadapter`,
|
||||
|
||||
- **Models**: The data for which an adapter serves as a bridge to views can be
|
||||
any sort of data. However, as a convenience, model mixin classes can ease the
|
||||
preparation of data, or the shaping for use in the system. For selection
|
||||
operations, :class:`SelectableDataItem` can optionally prepare data items to
|
||||
provide and receive selection information (data items are not required to be
|
||||
"selection-aware", but in some cases it may be desired).
|
||||
|
||||
:doc:`api-kivy.adapters.models`,
|
||||
|
||||
- **Args Converters**: Argument converters are made by the application programmer
|
||||
to do the work of converting data items to argument dictionaries suitable for
|
||||
instantiating views.
|
||||
|
||||
:doc:`api-kivy.adapters.args_converters`,
|
||||
|
||||
----
|
||||
'''
|
||||
|
|
@ -9,6 +9,30 @@ Adapter
|
|||
This widget is still experimental, and his API is subject to change in a
|
||||
future version.
|
||||
|
||||
:class:`~kivy.adapters.adapter.Adapter` is a bridge between data and
|
||||
:class:`~kivy.uix.abstractview.AbstractView` or one of its subclasses, such as
|
||||
:class:`~kivy.uix.listview.ListView`.
|
||||
|
||||
Arguments:
|
||||
|
||||
* *data*, for any sort of data to be used in a view. In
|
||||
:class:`~kivy.adapters.adapter.Adapter`, data can be an object, as well as a
|
||||
list, dict, etc. For :class:`~kivy.adapters.listadapter.ListAdapter`, data
|
||||
is a list, and for :class:`~kivy.adapters.dictadapter.DictAdapter`, it is a
|
||||
dict.
|
||||
|
||||
* *cls*, for a list key class to use to instantiate key view
|
||||
instances (Use this or the template argument)
|
||||
|
||||
* *template*, a kv template to use to instantiate key view instances (Use
|
||||
this or the cls argument)
|
||||
|
||||
* *args_converter*, a function to transform data item argument
|
||||
sets, in preparation for either a cls instantiation, or a kv template
|
||||
invocation. If no args_converter is provided, a default one is set, that
|
||||
assumes that the data items are strings.
|
||||
|
||||
|
||||
'''
|
||||
|
||||
__all__ = ('Adapter', )
|
||||
|
|
@ -20,7 +44,9 @@ from kivy.adapters.args_converters import list_item_args_converter
|
|||
|
||||
|
||||
class Adapter(EventDispatcher):
|
||||
'''Adapter is a bridge between an AbstractView and data.
|
||||
''':class:`~kivy.adapters.adapter.Adapter` is a bridge between data and
|
||||
:class:`~kivy.uix.abstractview.AbstractView` or one of its subclasses,
|
||||
such as :class:`~kivy.uix.listview.ListView`.
|
||||
'''
|
||||
|
||||
data = ObjectProperty(None)
|
||||
|
|
@ -32,9 +58,11 @@ class Adapter(EventDispatcher):
|
|||
In this base class, data is an ObjectProperty, so it could be used for a
|
||||
wide variety of single-view needs.
|
||||
|
||||
Subclasses may override to another data type, such as ListProperty or
|
||||
DictProperty, as appropriate. For example, in ListAdapter, data is a
|
||||
ListProperty.
|
||||
Subclasses may override to another data type, such as
|
||||
:class:`~kivy.properties.ListProperty` or
|
||||
:class:`~kivy.properties.DictProperty, as appropriate. For example, in
|
||||
:class:`~.kivy.adapters.listadapter.ListAdapter, data is a
|
||||
:class:`~kivy.properties.ListProperty`.
|
||||
|
||||
:data:`data` is an :class:`~kivy.properties.ObjectProperty`, default
|
||||
to None.
|
||||
|
|
|
|||
|
|
@ -9,6 +9,12 @@ The default list item args converter for list adapters is this function
|
|||
that takes a string and returns the string as the text argument in a dict,
|
||||
along with two properties suited for simple text items with height of 25.
|
||||
|
||||
These may be normal functions or, in the case of the default args converter,
|
||||
lambdas::
|
||||
|
||||
list_item_args_converter = lambda x: {'text': x,
|
||||
'size_hint_y': None,
|
||||
'height': 25}
|
||||
'''
|
||||
list_item_args_converter = lambda x: {'text': x,
|
||||
'size_hint_y': None,
|
||||
|
|
|
|||
|
|
@ -9,32 +9,12 @@ DictAdapter
|
|||
This widget is still experimental, and his API is subject to change in a
|
||||
future version.
|
||||
|
||||
:class:`DictAdapter` is an adapter around a python dictionary of records.
|
||||
|
||||
From :class:`ListAdapter`, :class:`DictAdapter` gets these properties:
|
||||
|
||||
Use only one:
|
||||
|
||||
- cls, for a list key class to use to instantiate key view
|
||||
instances
|
||||
|
||||
- template, a kv template to use to instantiate key view
|
||||
instances
|
||||
|
||||
- args_converter, an optional function to transform data item argument
|
||||
sets, in preparation for either a cls instantiation,
|
||||
or a kv template invocation. If no args_converter is
|
||||
provided, a default one is set, that assumes that the
|
||||
data items are strings.
|
||||
|
||||
- selection
|
||||
- selection_mode
|
||||
- allow_empty_selection
|
||||
|
||||
and several methods used in selection operations.
|
||||
:class:`~kivy.adapters.dictadapter.DictAdapter` is an adapter around a python
|
||||
dictionary of records. It extends the list-like capabilities of
|
||||
:class:`~kivy.adapters.listadapter.ListAdapter`.
|
||||
|
||||
If you wish to have a bare-bones list adapter, without selection, use
|
||||
:class:`SimpleListAdapter`.
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`.
|
||||
|
||||
'''
|
||||
|
||||
|
|
@ -47,6 +27,10 @@ from kivy.adapters.models import SelectableDataItem
|
|||
|
||||
|
||||
class DictAdapter(ListAdapter):
|
||||
''':class:`~kivy.adapters.dictadapter.DictAdapter` is an adapter around a
|
||||
python dictionary of records. It extends the list-like capabilities of
|
||||
:class:`~kivy.adapters.listadapter.ListAdapter`.
|
||||
'''
|
||||
|
||||
sorted_keys = ListProperty([])
|
||||
'''The sorted_keys list property contains a list of hashable objects (can
|
||||
|
|
|
|||
|
|
@ -13,39 +13,27 @@ ListAdapter
|
|||
|
||||
Selection operations are a main concern for the class.
|
||||
|
||||
From :class:`Adapter`, :class:`ListAdapter` gets these properties:
|
||||
|
||||
Use only one:
|
||||
|
||||
- cls, for a list key class to use to instantiate key view
|
||||
instances
|
||||
|
||||
- template, a kv template to use to instantiate key view
|
||||
instances
|
||||
|
||||
- args_converter, an optional function to transform data item argument
|
||||
sets, in preparation for either a cls instantiation,
|
||||
or a kv template invocation. If no args_converter is
|
||||
provided, a default one is set, that assumes that the
|
||||
data items are strings.
|
||||
From :class:`Adapter`, :class:`ListAdapter` gets cls, template, and
|
||||
args_converter properties.
|
||||
|
||||
and adds several for selection:
|
||||
|
||||
- selection, a list of selected items.
|
||||
* *selection*, a list of selected items.
|
||||
|
||||
- selection_mode, 'single', 'multiple', 'none'
|
||||
* *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.
|
||||
* *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
|
||||
:class:`SimpleListAdapter`.
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`.
|
||||
|
||||
:class:`DictAdapter` is a subclass of :class:`ListAdapter`. They both dispatch
|
||||
the on_selection_change event.
|
||||
:class:`~kivy.adapters.dictadapter.DictAdapter` is a subclass of
|
||||
:class:`~kivy.adapters.listadapter.ListAdapter`. They both dispatch the
|
||||
*on_selection_change* event.
|
||||
|
||||
:Events:
|
||||
`on_selection_change`: (view, view list )
|
||||
|
|
@ -86,16 +74,17 @@ class ListAdapter(Adapter, EventDispatcher):
|
|||
options=('none', 'single', 'multiple'))
|
||||
'''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. :class:`ListAdapter`
|
||||
is not meant to be used as a primary no-selection list adapter.
|
||||
Use :class:`SimpleListAdapter` for that.
|
||||
* *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.
|
||||
:class:`~kivy.adapters.listadapter.ListAdapter` is not meant to be
|
||||
used as a primary no-selection list adapter. Use
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` for that.
|
||||
|
||||
single -- multi-touch/click ignored. single item selecting only
|
||||
* *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
|
||||
* *multiple*, multi-touch / incremental addition to selection allowed;
|
||||
may be limited to a count by selection_limit
|
||||
|
||||
:data:`selection_mode` is an :class:`~kivy.properties.OptionProperty`,
|
||||
default to 'single'.
|
||||
|
|
@ -106,10 +95,11 @@ class ListAdapter(Adapter, EventDispatcher):
|
|||
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 :class:`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.
|
||||
they mix in :class:`~kivy.adapters.models.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?
|
||||
|
||||
|
|
@ -213,10 +203,12 @@ class ListAdapter(Adapter, EventDispatcher):
|
|||
return item_view
|
||||
|
||||
def create_view(self, index):
|
||||
'''This method is more complicated than the one in Adapter and
|
||||
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.
|
||||
'''This method is more complicated than the one in
|
||||
:class:`kivy.adapters.adapter.Adapter` and
|
||||
:class:`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.
|
||||
'''
|
||||
item = self.get_data_item(index)
|
||||
if item is None:
|
||||
|
|
|
|||
|
|
@ -9,9 +9,9 @@ SimpleListAdapter
|
|||
This widget is still experimental, and his API is subject to change in a
|
||||
future version.
|
||||
|
||||
:class:`SimpleListAdapter` is for simple lists, such as for showing a
|
||||
text-only display of strings, or a list of views of some type that have
|
||||
no user interaction.
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` is for simple
|
||||
lists, such as for showing a text-only display of strings, or a list of views
|
||||
of some type that have no user interaction.
|
||||
|
||||
'''
|
||||
|
||||
|
|
@ -22,30 +22,19 @@ from kivy.properties import ListProperty
|
|||
from kivy.lang import Builder
|
||||
|
||||
class SimpleListAdapter(Adapter):
|
||||
''':class:`SimpleListAdapter` is an adapter around a simple Python list.
|
||||
''':class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` is an
|
||||
adapter around a simple Python list.
|
||||
|
||||
From :class:`Adapter`, :class:`SimpleListAdapter` gets these properties:
|
||||
|
||||
Use only one:
|
||||
|
||||
- cls, for a list item class to use to instantiate item view
|
||||
instances
|
||||
|
||||
- template, a kv template to use to instantiate item view
|
||||
instances
|
||||
|
||||
- args_converter, an optional function to transform data item argument
|
||||
sets, in preparation for either a cls instantiation,
|
||||
or a kv template invocation (If an args_converter is
|
||||
not provided, a default one that assumes simple
|
||||
strings content is set)
|
||||
From :class:`~kivy.adapters.adapter.Adapter`,
|
||||
:class:`~kivy.adapters.simplelistadapter.ListAdapter` gets cls, template,
|
||||
and args_converter properties.
|
||||
'''
|
||||
|
||||
data = ListProperty([])
|
||||
'''The data list property contains a list of objects (can be strings) that
|
||||
will be used directly if no args_converter function is provided. If there
|
||||
is an args_converter, the data objects will be passed to it, for
|
||||
instantiation of item view class (cls) instances from the data.
|
||||
instantiation of item view class instances from the data.
|
||||
|
||||
:data:`data` is a :class:`~kivy.properties.ListProperty`,
|
||||
default to [].
|
||||
|
|
|
|||
|
|
@ -4,9 +4,10 @@ Abstract View
|
|||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
The :class:`AbstractView` widget has an adapter property for an adapter that
|
||||
mediates to data. The adapter manages an item_view_instances dict property
|
||||
that holds views for each data item, operating as a cache.
|
||||
The :class:`~kivy.uix.abstractview.AbstractView` widget has an adapter property
|
||||
for an adapter that mediates to data. The adapter manages an
|
||||
item_view_instances dict property that holds views for each data item,
|
||||
operating as a cache.
|
||||
|
||||
'''
|
||||
|
||||
|
|
@ -17,10 +18,12 @@ from kivy.properties import ObjectProperty, DictProperty
|
|||
|
||||
|
||||
class AbstractView(FloatLayout):
|
||||
'''View using an Adapter as a data provider
|
||||
'''
|
||||
View using an :class:`~kivy.adapters.adapter.Adapter` as a data provider.
|
||||
'''
|
||||
|
||||
adapter = ObjectProperty(None)
|
||||
'''The adapter can be one of several defined in kivy/adapters. The most
|
||||
common example is the ListAdapter used for managing data items in a list.
|
||||
common example is the :class:`~kivy.adapters.listadapter.ListAdapter` used
|
||||
for managing data items in a list.
|
||||
'''
|
||||
|
|
|
|||
|
|
@ -9,14 +9,16 @@ List View
|
|||
This widget is still experimental, and his API is subject to change in a
|
||||
future version.
|
||||
|
||||
The :class:`ListView` widget provides a scrollable/pannable viewport that is
|
||||
clipped at the scrollview's bounding box, which contains a list of
|
||||
list item view instances.
|
||||
The :class:`~kivy.uix.listview.ListView` widget provides a scrollable/pannable
|
||||
viewport that is clipped at the scrollview's bounding box, which contains a
|
||||
list of list item view instances.
|
||||
|
||||
:class:`ListView` implements :class:`AbstractView` as a vertical scrollable
|
||||
list. :class:`AbstractView` has one property, adapter. :class:`ListView` sets
|
||||
adapter to one of: :class:`SimpleListAdapter`, :class:`ListAdapter`, or
|
||||
:class`DictAdapter`.
|
||||
:class:`~kivy.uix.listview.ListView` implements :class:`AbstractView` as a
|
||||
vertical scrollable list. :class:`AbstractView` has one property, adapter.
|
||||
:class:`~kivy.uix.listview.ListView` sets adapter to one of:
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`,
|
||||
:class:`~kivy.adapters.listadapter.ListAdapter`, or
|
||||
:class:`~kivy.adapters.dictadapter.DictAdapter`.
|
||||
|
||||
|
||||
:Events:
|
||||
|
|
@ -52,13 +54,16 @@ In its simplest form, we make a listview with 100 items::
|
|||
Using an Adapter
|
||||
-------------------
|
||||
|
||||
Behind the scenes, the basic example above uses :class:`SimpleListAdapter`.
|
||||
When the constructor for :class:`ListView` sees that only a list of strings is
|
||||
provided as an argument, called item_strings, it creates an instance of
|
||||
:class:`SimpleListAdapter` with the list of strings.
|
||||
Behind the scenes, the basic example above uses
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`. When the
|
||||
constructor for :class:`~kivy.uix.listview.ListView` sees that only a list of
|
||||
strings is provided as an argument, called item_strings, it creates an instance
|
||||
of :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` with the list of
|
||||
strings.
|
||||
|
||||
Simple in :class:`SimpleListAdapter` means: *without selection support*. It is
|
||||
a scrollable list of items that do not respond to touch events.
|
||||
Simple in :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` means:
|
||||
*without selection support*. It is a scrollable list of items that do not
|
||||
respond to touch events.
|
||||
|
||||
To use :class:`SimpleListAdaper` explicitly in creating a ListView instance,
|
||||
do::
|
||||
|
|
@ -69,19 +74,22 @@ do::
|
|||
|
||||
list_view = ListView(adapter=simple_list_adapter)
|
||||
|
||||
The instance of :class:`SimpleListAdapter` has a required data argument, which
|
||||
contains data items to use as the basis for list items, along with a cls
|
||||
argument for the class to be instantiated for each list item from the data.
|
||||
The instance of :class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` has
|
||||
a required data argument, which contains data items to use as the basis for
|
||||
list items, along with a cls argument for the class to be instantiated for each
|
||||
list item from the data.
|
||||
|
||||
ListAdapter and DictAdapter
|
||||
---------------------------
|
||||
|
||||
For many uses of a list, the data is more than a simple list of strings and
|
||||
selection functionality is often needed. :class:`ListAdapter` and
|
||||
:class:`DictAdapter` each contain functionality for selection.
|
||||
selection functionality is often needed.
|
||||
:class:`~kivy.adapters.listadapter.ListAdapter` and
|
||||
:class:`~kivy.adapters.dictadapter.DictAdapter` each contain functionality for
|
||||
selection.
|
||||
|
||||
See the :class:`ListAdapter` docs for details, but here are synopses of
|
||||
its arguments:
|
||||
See the :class:`~kivy.adapters.listadapter.ListAdapter` docs for details, but
|
||||
here are synopses of its arguments:
|
||||
|
||||
* *data*: strings, class instances, dicts, etc. that form the basis data
|
||||
for instantiating view item classes.
|
||||
|
|
@ -130,8 +138,9 @@ list adapter, looks like this::
|
|||
- | |
|
||||
- ----------------------------------------------------
|
||||
|
||||
:class:`DictAdapter` has the same arguments and requirements as ListAdapter,
|
||||
except for two things:
|
||||
:class:`~kivy.adapters.dictadapter.DictAdapter` has the same arguments and
|
||||
requirements as :class:`~kivy.adapters.listadapter.ListAdapter`, except for two
|
||||
things:
|
||||
|
||||
1) There is an additional argument, sorted_keys, which must meet the
|
||||
requirements of normal python dictionary keys.
|
||||
|
|
@ -144,13 +153,15 @@ except for two things:
|
|||
Using an Args Converter
|
||||
-----------------------
|
||||
|
||||
:class:`ListView` allows use of built-in list item views, such as
|
||||
:class:`ListItemButton`, your own custom item view class, or a custom kv
|
||||
template. Whichever type of list item view is used, an args_converter function
|
||||
is needed to prepare, per list data item, args for either a cls or template.
|
||||
:class:`~kivy.uix.listview.ListView` allows use of built-in list item views,
|
||||
such as :class:`~kivy.uix.listview.ListItemButton`, your own custom item view
|
||||
class, or a custom kv template. Whichever type of list item view is used, an
|
||||
args_converter function is needed to prepare, per list data item, args for
|
||||
either a cls or template.
|
||||
|
||||
Here is an args_converter for use with the built-in :class:`ListItemButton`,
|
||||
specified as a normal Python function::
|
||||
Here is an args_converter for use with the built-in
|
||||
:class:`~kivy.uix.listview.ListItemButton`, specified as a normal Python
|
||||
function::
|
||||
|
||||
def args_converter(an_obj):
|
||||
return {'text': an_obj.text,
|
||||
|
|
@ -205,7 +216,8 @@ listview will only allow single selection -- additional touches will be
|
|||
ignored. When the listview is first shown, the first item will already be
|
||||
selected, because allow_empty_selection is False.
|
||||
|
||||
:class:`ListItemLabel` works much the same way as :class:`ListItemButton`.
|
||||
:class:`~kivy.uix.listview.ListItemLabel` works much the same way as
|
||||
:class:`~kivy.uix.listview.ListItemButton`.
|
||||
|
||||
Using a Custom Item View Class
|
||||
------------------------------
|
||||
|
|
@ -267,9 +279,9 @@ is_selected properties.
|
|||
Using an Item View Template
|
||||
---------------------------
|
||||
|
||||
:class:`SelectableView` is another simple mixin class that has required
|
||||
properties for a list item: text, and is_selected. To make your own template,
|
||||
mix it in as follows::
|
||||
:class:`~kivy.uix.listview.SelectableView` is another simple mixin class that
|
||||
has required properties for a list item: text, and is_selected. To make your
|
||||
own template, mix it in as follows::
|
||||
|
||||
from kivy.uix.listview import ListItemButton
|
||||
from kivy.uix.listview import SelectableView
|
||||
|
|
@ -283,9 +295,9 @@ mix it in as follows::
|
|||
is_selected: ctx.is_selected
|
||||
</triplequotes>)
|
||||
|
||||
A class called CustomListItem will be instantiated for each list item. Note that
|
||||
it is a layout, BoxLayout, and is thus a kind of container. It contains a
|
||||
:class:`ListItemButton` instance.
|
||||
A class called CustomListItem will be instantiated for each list item. Note
|
||||
that it is a layout, BoxLayout, and is thus a kind of container. It contains a
|
||||
:class:`~kivy.uix.listview.ListItemButton` instance.
|
||||
|
||||
Using the power of the Kivy language (kv), you can easily build composite list
|
||||
items -- in addition to ListItemButton, you could have a ListItemLabel, or a
|
||||
|
|
@ -315,12 +327,13 @@ template. For example, to use the kv template above::
|
|||
|
||||
The list_vew would then be added to a view with add_widget().
|
||||
|
||||
Using CompositeItemView
|
||||
Using CompositeListItem
|
||||
-----------------------
|
||||
|
||||
The class :class:`CompositeItemView` is another option for building complex
|
||||
composite list items. The kv language approach has its advantages, but here we
|
||||
build a composite list view using a straight Kivy widget method::
|
||||
The class :class:`~kivy.uix.listview.CompositeListItem` is another option for
|
||||
building complex composite list items. The kv language approach has its
|
||||
advantages, but here we build a composite list view using a straight Kivy
|
||||
widget method::
|
||||
|
||||
# This is quite an involved args_converter, so we should go through the
|
||||
# details. A CompositeListItem instance is made with the args
|
||||
|
|
@ -349,7 +362,7 @@ build a composite list view using a straight Kivy widget method::
|
|||
# And now the dict adapter, constructed with the item_strings as
|
||||
# the sorted_keys, the integers_dict as data, and our args_converter()
|
||||
# that produce list item view instances from the
|
||||
# :class:`CompositeListItem` class.
|
||||
# :class:`~kivy.uix.listview.CompositeListItem` class.
|
||||
dict_adapter = DictAdapter(sorted_keys=item_strings,
|
||||
data=integers_dict,
|
||||
args_converter=args_converter,
|
||||
|
|
@ -359,8 +372,8 @@ build a composite list view using a straight Kivy widget method::
|
|||
|
||||
list_view = ListView(adapter=dict_adapter)
|
||||
|
||||
For details on how :class:`CompositeListItem` works, view the code and look
|
||||
for parsing of the cls_dicts list and kwargs processing.
|
||||
For details on how :class:`~kivy.uix.listview.CompositeListItem` works, view
|
||||
the code and look for parsing of the cls_dicts list and kwargs processing.
|
||||
|
||||
Uses for Selection
|
||||
------------------
|
||||
|
|
@ -389,9 +402,6 @@ the items shown in the third. If allow_empty_selection were set to False for
|
|||
these listviews, a dynamic system, a "cascade" from one list to the next,
|
||||
would result. Several examples show such "cascading" behavior.
|
||||
|
||||
More Examples
|
||||
-------------
|
||||
|
||||
There are so many ways that listviews and related functionality can be used,
|
||||
that we have only scratched the surface here. For on-disk examples, see:
|
||||
|
||||
|
|
@ -417,11 +427,12 @@ from math import ceil, floor
|
|||
|
||||
|
||||
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.
|
||||
'''The :class:`~kivy.uix.listview.SelectableView` mixin is used to design
|
||||
list item and other classes that are to be instantiated by an adapter to be
|
||||
used in a listview. The :class:`~kivy.adapters.listadapter.ListAdapter`
|
||||
and :class:`~kivy.adapters.dictadapter.DictAdapter` adapters are
|
||||
selection-enabled. select() and deselect() are to be overridden with
|
||||
display code to mark items as selected or not, if desired.
|
||||
'''
|
||||
|
||||
index = NumericProperty(-1)
|
||||
|
|
@ -457,6 +468,12 @@ class SelectableView(object):
|
|||
|
||||
|
||||
class ListItemButton(SelectableView, Button):
|
||||
''':class:`~kivy.uix.listview.ListItemButton` mixes
|
||||
:class:`~kivy.uix.listview.SelectableView` with
|
||||
:class:`~kivy.uix.button.Button` to produce a button suitable for use in
|
||||
:class:`~kivy.uix.listview.ListView`.
|
||||
'''
|
||||
|
||||
selected_color = ListProperty([1., 0., 0., 1])
|
||||
'''
|
||||
:data:`selected_color` is a :class:`~kivy.properties.ListProperty`,
|
||||
|
|
@ -495,7 +512,15 @@ class ListItemButton(SelectableView, Button):
|
|||
return self.text
|
||||
|
||||
|
||||
# [TODO] Why does this mix in SelectableView -- that makes it work like
|
||||
# button, which is redundant.
|
||||
|
||||
class ListItemLabel(SelectableView, Label):
|
||||
''':class:`~kivy.uix.listview.ListItemLabel` mixes
|
||||
:class:`~kivy.uix.listview.SelectableView` with
|
||||
:class:`~kivy.uix.label.Label` to produce a label suitable for use in
|
||||
:class:`~kivy.uix.listview.ListView`.
|
||||
'''
|
||||
|
||||
def __init__(self, **kwargs):
|
||||
super(ListItemLabel, self).__init__(**kwargs)
|
||||
|
|
@ -521,6 +546,11 @@ class ListItemLabel(SelectableView, Label):
|
|||
|
||||
|
||||
class CompositeListItem(SelectableView, BoxLayout):
|
||||
''':class:`~kivy.uix.listview.CompositeListItem` mixes
|
||||
:class:`~kivy.uix.listview.SelectableView` with :class:`BoxLayout` for a
|
||||
generic container-style list item, to be used in
|
||||
:class:`~kivy.uix.listview.ListView`.
|
||||
'''
|
||||
|
||||
background_color = ListProperty([1, 1, 1, 1])
|
||||
'''ListItem sublasses Button, which has background_color, but
|
||||
|
|
@ -629,6 +659,25 @@ Builder.load_string('''
|
|||
|
||||
|
||||
class ListView(AbstractView, EventDispatcher):
|
||||
''':class:`~kivy.uix.listview.ListView` is a primary high-level widget,
|
||||
handling the common task of presenting items in a scrolling list.
|
||||
Flexibility is afforded by use of a variety of adapters to interface with
|
||||
data.
|
||||
|
||||
The adapter property comes via the mixed in
|
||||
:class:`~kivy.uix.abstractview.AbstractView` class.
|
||||
|
||||
:class:`~kivy.uix.listview.ListView` also subclasses
|
||||
:class:`EventDispatcher` for scrolling. The event *on_scroll_complete* is
|
||||
used in refreshing the main view.
|
||||
|
||||
For a simple list of string items, without selection, use
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter`. For list items
|
||||
that respond to selection, ranging from simple items to complex composites,
|
||||
use :class:`~kivy.adapters.listadapter.ListAdapter`. For an alternate
|
||||
powerful adapter, use :class:`~kivy.adapters.dictadapter.DictAdapter`,
|
||||
rounding out the choice for designing highly interactive lists.
|
||||
'''
|
||||
|
||||
divider = ObjectProperty(None)
|
||||
'''[TODO] Not used.
|
||||
|
|
@ -639,12 +688,14 @@ class ListView(AbstractView, EventDispatcher):
|
|||
'''
|
||||
|
||||
container = ObjectProperty(None)
|
||||
'''The container is a GridLayout widget held within a ScrollView widget.
|
||||
(See the associated kv block in the Builder.load_string() setup). Item
|
||||
view instances managed and provided by the adapter are added to this
|
||||
container. The container is cleared with a call to clear_widgets() when
|
||||
the list is rebuilt by the populate() method. A padding Widget instance
|
||||
is also added as needed, depending on the row height calculations.
|
||||
'''The container is a :class:`~kivy.uix.gridlayout.GridLayout` widget held
|
||||
within a :class:`~kivy.uix.scrollview.ScrollView` widget. (See the
|
||||
associated kv block in the Builder.load_string() setup). Item view
|
||||
instances managed and provided by the adapter are added to this container.
|
||||
The container is cleared with a call to clear_widgets() when the list is
|
||||
rebuilt by the populate() method. A padding
|
||||
:class:`~kivy.uix.widget.Widget` instance is also added as needed,
|
||||
depending on the row height calculations.
|
||||
|
||||
:data:`container` is an :class:`~kivy.properties.ObjectProperty`,
|
||||
default to None.
|
||||
|
|
@ -660,8 +711,8 @@ class ListView(AbstractView, EventDispatcher):
|
|||
|
||||
item_strings = ListProperty([])
|
||||
'''If item_strings is provided, create an instance of
|
||||
:class:`SimpleListAdapter` with this list of strings, and use it to manage
|
||||
a no-selection list.
|
||||
:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` with this list
|
||||
of strings, and use it to manage a no-selection list.
|
||||
|
||||
:data:`item_strings` is a :class:`~kivy.properties.ListProperty`,
|
||||
default to [].
|
||||
|
|
|
|||
Loading…
Reference in New Issue