Merge branch 'master' of ssh://github.com/kivy/kivy

doc/sources/guide/designwithkv.rst

@@ -3,7 +3,7 @@
 .. highlight:: python
     :linenothreshold: 3
 
-Designing with Kivy language
+Designing with the Kivy Language
 ============================
 
 Let's start with a little example. First, the Python file named `main.py`:
@@ -13,42 +13,50 @@ Let's start with a little example. First, the Python file named `main.py`:
 
 In this example, we are creating a Controller class, with 2 properties:
 
-    * `info` for receving some text
-    * `label_wid` for receving the label widget
+    * ``info`` for receving some text
+    * ``label_wid`` for receving the label widget
 
-In addition, we are creating a `do_action()` method, that will use both of
-theses properties: change the `info` text, and use `label_wid` to change the
-content of the label with a nex text.
+In addition, we are creating a ``do_action()`` method, that will use both of
+these properties. It will change the ``info`` text, and change text in the
+``label_wid`` widget.
 
-If you execute that application without kv, it will work... but nothing will be
-showed on the screen. That's normal: `Controller` class have no widget in it,
-it's just a Layout. We can now create a kv file and create the UI around the
-`Controller` class in a file named `controller.kv`. The relation between the
-previous file and the kv is described in the :class:`kivy.app.App` class.
+Executing this application without a corresponding `.kv` file will work, but
+nothing will be shown on the screen. This is expected, because the
+``Controller`` class has no widgets in it, it's just a ``FloatLayout``. We can
+create the UI around the ``Controller`` class in a file named `controller.kv`,
+which will be loaded when we run the ``ControllerApp``. How this is done and
+what files are loaded is described in the :func:`kivy.app.App.load_kv` method.
 
 .. include:: ../../../examples/guide/designwithkv/controller.kv
     :literal:
 
-Yes, one label and one button in a vertical boxlayout. Seem very simple. Now, we have 2 things here:
+One label and one button in a vertical ``BoxLayout``. Seems very simple. There
+are 3 things going on here:
 
-    1. Use data from `Controller`: that's the goal of `info` property: as soon
-       as the property is changed in the controller, the kv part that use it
-       will be automatically re-evaluated, and change the button text.
+    1. Using data from the ``Controller``. As soon as the ``info`` property is
+       changed in the controller, the expression ``text: 'My controller info is
+       : ' + root.info`` will automatically be re-evaluated, changing the text
+       in the ``Button``.
 
-    2. Give data to `Controller`: the first assignation `label_wid:
-       my_custom_label` is to assign a new value to the `label_wid` property.
-       Using id, you can give the instance of one of your widget to the
-       `Controller`.
+    2. Giving data to the ``Controller``. The expression ``id: my_custom_label``
+       is assigning the created ``Label`` the id of ``my_custom_label``. Then,
+       using ``my_custom_label`` in the expression ``label_wid:
+       my_custom_label`` gives the instance of that ``Label`` widget to your
+       ``Controller``.
 
-Also, we are creating a custom callback in the `Button` using `on_press`. Remember that:
+    3. Creating a custom callback in the ``Button`` using the ``Controller``'s
+       ``on_press`` method.
 
-    * `root` and `self` are 2 reserved keyword, that can be used anywhere for
-      evaluation. `root` represent the top widget in the rule and `self`
-      represent the current widget.
+        * ``root`` and ``self`` are 2 reserved keywords, useable anywhere.
+          ``root`` represents the top widget in the rule and ``self`` represents
+          the current widget.
 
-    * you can use any id declared in the rule same as `root` and `self`. For example, you could do in on_press::
+        * You can use any id declared in the rule, same as ``root`` and
+          ``self``. For example, you could do this in the ``on_press()``::
 
-        Button:
-            on_press: root.do_action(); my_custom_label.font_size = 18
+            Button:
+                on_press: root.do_action(); my_custom_label.font_size = 18
 
+And that's that. Now when we run `main.py`, `controller.kv` will be loaded so
+that the ``Button`` and ``Label`` will show up and respond to our touch events.
 

examples/guide/designwithkv/controller.kv

@@ -8,7 +8,7 @@
         padding: 20
 
         Button:
-            text: 'My controler info is : ' + root.info
+            text: 'My controller info is : ' + root.info
             on_press: root.do_action()
 
         Label:

examples/guide/designwithkv/main.py

@@ -7,8 +7,9 @@ from kivy.properties import ObjectProperty, StringProperty
 
 
 class Controller(FloatLayout):
-    '''Create a controler that can receive custom widget from kv lang
-    + add action to be called from kv lang
+    '''Create a controller that receives a custom widget from the kv lang file.
+
+    Add an action to be called from the kv lang file.
     '''
     label_wid = ObjectProperty(None)
     info = StringProperty('')