Merge pull request #837 from geojeff/listview_docs

Listview docs

kivy/adapters/simplelistadapter.py

@@ -9,9 +9,9 @@ SimpleListAdapter
     This code is still experimental, and its API is subject to change in a
     future version.
 
-: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.
+:class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` is for basic lists,
+such as for showing a text-only display of strings, that have no user
+interaction.
 
 '''
 
@@ -24,7 +24,7 @@ from kivy.lang import Builder
 
 class SimpleListAdapter(Adapter):
     ''':class:`~kivy.adapters.simplelistadapter.SimpleListAdapter` is an
-    adapter around a simple Python list.
+    adapter around a Python list.
 
     From :class:`~kivy.adapters.adapter.Adapter`,
     :class:`~kivy.adapters.simplelistadapter.ListAdapter` gets cls, template,
@@ -34,7 +34,7 @@ class SimpleListAdapter(Adapter):
     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
+    is an args_converter, the data objects will be passed to it for
     instantiation of item view class instances from the data.
 
     :data:`data` is a :class:`~kivy.properties.ListProperty`,

kivy/uix/listview.py

@@ -32,15 +32,15 @@ run first, to get a taste of the range of functionality offered. You can tell
 from the names of the examples that they illustrate the "ramping up" from
 simple to advanced:
 
-    kivy/examples/widgets/lists/list_simple.py
-    kivy/examples/widgets/lists/list_master_detail.py
-    kivy/examples/widgets/lists/list_two_up.py
-    kivy/examples/widgets/lists/list_kv.py
-    kivy/examples/widgets/lists/list_composite.py
-    kivy/examples/widgets/lists/list_cascade.py
-    kivy/examples/widgets/lists/list_cascade_dict.py
-    kivy/examples/widgets/lists/list_cascade_images.py
-    kivy/examples/widgets/lists/list_ops.py
+    * kivy/examples/widgets/lists/list_simple.py
+    * kivy/examples/widgets/lists/list_master_detail.py
+    * kivy/examples/widgets/lists/list_two_up.py
+    * kivy/examples/widgets/lists/list_kv.py
+    * kivy/examples/widgets/lists/list_composite.py
+    * kivy/examples/widgets/lists/list_cascade.py
+    * kivy/examples/widgets/lists/list_cascade_dict.py
+    * kivy/examples/widgets/lists/list_cascade_images.py
+    * kivy/examples/widgets/lists/list_ops.py
 
 Many of the examples feature selection, some restricting selection to single
 selection, where only one item at at time can be selected, and others allowing
@@ -438,14 +438,18 @@ on_selection_change event::
 
     list_adapter.bind(on_selection_change=callback_function)
 
-where callback_function() does whatever is needed for the update.
+where callback_function() does whatever is needed for the update. See the
+example called list_master_detail.py, and imagine that the list one the left
+would be a list of dog breeds, and the detail view on the right would show
+details for a selected dog breed.
 
 In another example, we could set the selection_mode of a listview to
 'multiple', and load it with a list of answers to a multiple-choice question.
 The question could have several correct answers. A color swatch view could be
 bound to selection change, as above, so that it turns green as soon as the
 correct choices are made, unless the number of touches exeeds a limit, when the
-answer session would be terminated.
+answer session would be terminated. See the examples that feature thumbnail
+images to get some ideas, e.g., list_cascade_dict.py.
 
 In a more involved example, we could chain together three listviews, where
 selection in the first controls the items shown in the second, and selection in