Merge branch 'new_doc_review'

doc/sources/guide2/basic.rst

@@ -36,6 +36,27 @@ git::
 Create an application
 ---------------------
 
+Creating a kivy application is as simple as:
+
+- subclassing the :cls:`kivy.app.App` class, 
+- implementing its :meth:`kivy.app.App.build` method so it returns a :cls:`kivy.uix.Widget` instance (the root of your widget tree)
+- instanciating this class, and call its :meth:`kiyv.app.App.run` method.
+
+here is an example of such a minimum application::
+
+    from kivy.app import App
+    from kivy.uix.label import Label
+
+
+    class MyApp(App):
+        def build(self):
+            return Label(text='Hello world')
+
+
+    if __name__ == '__main__':
+        MyApp().run()
+
+
 Running the application
 -----------------------
 

doc/sources/guide2/events.rst

@@ -4,20 +4,100 @@
 Events and Properties
 =====================
 
+Events are a big part of kivy programming, that may not be surprising to those
+having done GUI development before, but it's an important concept to get for
+newcomers, and the specifics of how to use these in kivy. Once you understand
+how events and ways to bind to them, are everywhere in kivy, it becomes easy
+to build about whatever you want with kivy.
+
 Introduction to Event Dispatcher
 --------------------------------
 
+One of the most important base class of the framework is the
+:cls:`kivy.event.EventDispatcher` class, this class allows to register event
+types, and to dispatch them to interrested parties (usually other event
+dispatchers). :cls:`kivy.uix.widget.Widget`, :cls:`kivy.animation.Animation`
+and :obj:`kivy.clock.Clock` for example are event dispatchers.
+
 Creating custom events
 ----------------------
 
+To create an event dispatcher with custom events, you need to register
+the name of the event in the class, and to create a method of the same
+name.
+
+See the following example::
+
+    class MyEventDispatcher(EventDispatcher):
+        def __init__(self, **kwargs):
+            super(MyEventDispatcher, self).__init__(**kwargs)
+            self.register_event_type('on_test')
+
+        def test(self, value):
+            # when test is called, the 'on_test' event will be
+            # dispatched with the value
+            self.dispatch('on_test', value)
+
+        def on_test(self):
+            pass
+
+
 Attaching callbacks
 -------------------
 
+To use events, you have to bind callbacks to them, when the event is
+dispatched, your callbacks will be called with the various data the event has
+to pass around.
+
+A callback can be any python callable, but you need to be sure it can accept
+the arguments the event will use, for this, it's usually safer to accept the
+`*args` argument, that will catch any remaining arguments in the `args` list.
+
+example::
+
+    def my_callback(value, *args):
+        print "Hello, I got an event!", value
+
+
+    ev = MyEventDispatcher()
+    ev.bind(on_test=my_callback)
+    ev.test('test')
+
+
 Introduction to properties
 --------------------------
 
+Properties are an awesome way to define events and bind to them, it basically
+produce events when the attributes to your object changes, so you can bind
+actions to the change of these values.
+
+There are different kind of properties to describe the type of data you want to describe.
+
+:cls:`kivy.properties.StringProperty`
+:cls:`kivy.properties.NumericProperty`
+:cls:`kivy.properties.ObjectProperty`
+:cls:`kivy.properties.ListProperty`
+:cls:`kivy.properties.ObjectProperty`
+:cls:`kivy.properties.AliasProperty`
+
 Declaration of a Property
 -------------------------
 
+To declare a property, you must create it at class level, the class will do the
+work to instanciate the real attributes when the object will be created, the
+properties is not the attribute, it's a mecanism to create events for your
+attributes::
+
+    class MyWidget(Widget):
+        text = StringProperty('')
+
+
+If you override `__init__`, *always* accept `**kwargs` and use super() to call
+parent's `__init__` with it::
+
+        def __init__(self, **kwargs):
+            super(MyWidget, self).__init__(**kwargs)
+
+
 Dispatching a Property event
 ----------------------------

doc/sources/guide2/widgets.rst

@@ -6,12 +6,37 @@ Widgets
 Introduction to Widget
 ----------------------
 
+A `:cls:kivy.uix.widget.Widget` is the basic component of the interface,
+it can display things at places, and recieve touch (and other) events,
+and react to them. It's representation and behaviour.
+
 Manipulating the Widget tree
 ----------------------------
 
+Widgets are organized in Trees, your application usually
+have a root widget, which have children, which can
+have children on their own. Childrens of a widget are
+represented as a :cls:`kivy.properties.ListProperty`
+:attr:`kivy.uix.widget.Widget.children`. The way to add a children to a
+widget is to call :meth:`kivy.uix.widget.Widget.add_widget`, likely, to
+remove a widget, you use :meth:`kivy.uix.widget.Widget.remove_widget`.
+
 Organize with Layouts
 ---------------------
 
+Layouts are a special kind of widget that allows automatic control of the size
+and position of their children. There are different kind of layouts, allowing
+for different automatic organisation. A common caracteristic of layouts is that
+they use (even if differently) of the
+:attr:`kivy.uix.widget.Widget.size_hint` and
+:attr:`kivy.uix.widget.Widget.pos_hint` properties. Those properties allow to
+define size and pos of the widget relatively to the parent layout.
+
 Seperate with Screen Manager
 ----------------------------
 
+If your application is composed of various screens, you likely want an
+easy way to navigate from one to another, fortunately, there is the
+:cls:`kivy.uix.screenmanager.ScreenManager` class, that allows you
+to define screens separatly, and to set the transitions from one to
+another.