Merge pull request #2956 from merriam/merriam_branch_14

Add documentation to examples/animation/animate.py

examples/animation/animate.py

@@ -2,8 +2,9 @@
 Widget animation
 ================
 
-This is an example of an animation creation, and how you can apply it to a
-widget.
+This example demonstrates creating and applying a multi-part animation to
+a button widget.  You should see a button labelled 'plop' that will move with
+an animation when clicked.
 '''
 
 import kivy
@@ -17,18 +18,23 @@ from kivy.uix.button import Button
 class TestApp(App):
 
     def animate(self, instance):
-        # create an animation object. 
+        # create an animation object. This object could be stored
+        # and reused each call or reused across different widgets.
+        # += is a sequential step, while &= is in parallel
         animation = Animation(pos=(100, 100), t='out_bounce')
         animation += Animation(pos=(200, 100), t='out_bounce')
         animation &= Animation(size=(500, 500))
         animation += Animation(size=(100, 50))
 
         # apply the animation on the button, passed in the "instance" argument
+        # Notice that default 'click' animation (changing the button
+        # color while the mouse is down) is unchanged.
         animation.start(instance)
 
     def build(self):
         # create a button, and  attach animate() method as a on_press handler
-        button = Button(size_hint=(None, None), text='plop', on_press=self.animate)
+        button = Button(size_hint=(None, None), text='plop',
+                        on_press=self.animate)
         return button
 
 if __name__ == '__main__':