doc: added functional example to behaviors/compoundselection.py

Author: Zen-CODE

kivy/uix/behaviors/compoundselection.py

@@ -8,16 +8,23 @@
 derived widget. For example, it can be combined with a
 :class:`~kivy.uix.gridlayout.GridLayout` to add selection to the layout.
 
+Compound selection concepts
+---------------------------
+
 At its core, it keeps a dynamic list of widgets that can be selected.
 Then, as the touches and keyboard input are passed in, it selects one or
 more of the widgets based on these inputs. For example, it uses the mouse
 scroll and keyboard up/down buttons to scroll through the list of widgets.
 Multiselection can also be achieved using the keyboard shift and ctrl keys.
-Finally, in addition to the up/down type keyboard inputs, it can also
-accepts letters from the keyboard to be used to select nodes with
+
+Finally, in addition to the up/down type keyboard inputs, compound selection
+can also accept letters from the keyboard to be used to select nodes with
 associated strings that start with those letters, similar to how files
 are selected by a file browser.
 
+Selection mechanics
+-------------------
+
 When the controller needs to select a node, it calls :meth:`select_node` and
 :meth:`deselect_node`. Therefore, they must be overwritten in order alter
 node selection. By default, the class doesn't listen for keyboard or
@@ -30,27 +37,69 @@
 -------
 
 To add selection to a grid layout which will contain
-:class:`~kivy.uix.Button` widgets::
+:class:`~kivy.uix.Button` widgets. For each button added to the layout, you
+need to bind the :attr:`~kivy.uix.widget.Widget.on_touch_down` of the button
+to :meth:`select_with_touch` to pass on the touch events::
+
+    from kivy.uix.behaviors.compoundselection import CompoundSelectionBehavior
+    from kivy.uix.button import Button
+    from kivy.uix.gridlayout import GridLayout
+    from kivy.core.window import Window
+    from kivy.app import App
 
-    class SelectableGrid(CompoundSelectionBehavior, GridLayout):
 
+    class SelectableGrid(CompoundSelectionBehavior, GridLayout):
         def __init__(self, **kwargs):
+            """ Use the initialize method to bind to the keyboard to enable
+            keyboard interaction e.g. using shift and control for multi-select.
+            """
             super(CompoundSelectionBehavior, self).__init__(**kwargs)
             keyboard = Window.request_keyboard(None, self)
             keyboard.bind(on_key_down=self.select_with_key_down,
-            on_key_up=self.select_with_key_up)
+                          on_key_up=self.select_with_key_up)
+
+        def add_widget(self, widget):
+            """ Override the adding of widgets so we can bind and catch their
+            *on_touch_down* events. """
+            widget.bind(on_touch_down=self.button_touch_down,
+                        on_touch_up=self.button_touch_up)
+            return super(SelectableGrid, self).add_widget(widget)
+
+        def button_touch_down(self, button, touch):
+            """ Use collision detection to select buttons when the touch occurs
+            within their area. """
+            if button.collide_point(*touch.pos):
+                self.select_with_touch(button, touch)
+
+        def button_touch_up(self, button, touch):
+            """ Use collision detection to de-select buttons when the touch
+            occurs outside their area and *touch_multiselect* is not True. """
+            if not (button.collide_point(*touch.pos) or self.touch_multiselect):
+                self.deselect_node(button)
 
         def select_node(self, node):
             node.background_color = (1, 0, 0, 1)
-            return super(CompoundSelectionBehavior, self).select_node(node)
+            return super(SelectableGrid, self).select_node(node)
 
         def deselect_node(self, node):
             node.background_color = (1, 1, 1, 1)
-            super(CompoundSelectionBehavior, self).deselect_node(node)
+            super(SelectableGrid, self).deselect_node(node)
+
+        def on_selected_nodes(self, gird, nodes):
+            print("Selected nodes = {0}".format(nodes))
+
+
+    class TestApp(App):
+        def build(self):
+            grid = SelectableGrid(cols=3, rows=2, touch_multiselect=True,
+                                  multiselect=True)
+            for i in range(0, 6):
+                grid.add_widget(Button(text="Button {0}".format(i)))
+            return grid
+
+
+    TestApp().run()
 
-Then, for each button added to the layout, bind the
-:attr:`~kivy.uix.widget.Widget.on_touch_down` of the button
-to :meth:`select_with_touch` to pass on the touch events.
 
 .. warning::
 
@@ -92,7 +141,7 @@ class CompoundSelectionBehavior(object):
 
     touch_multiselect = BooleanProperty(False)
     '''A special touch mode which determines whether touch events, as
-    processed with :meth:`select_with_touch`, will add the currently touched
+    processed by :meth:`select_with_touch`, will add the currently touched
     node to the selection, or if it will clear the selection before adding the
     node. This allows the selection of multiple nodes by simply touching them.