From 0debf84859d291ad892c6eb8de1be3e0332957d1 Mon Sep 17 00:00:00 2001 From: tshirtman Date: Sun, 25 Nov 2012 02:34:15 +0100 Subject: [PATCH 1/2] explain app creation and events --- doc/sources/guide2/basic.rst | 21 +++++++++++++++ doc/sources/guide2/events.rst | 51 +++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) diff --git a/doc/sources/guide2/basic.rst b/doc/sources/guide2/basic.rst index 152d60ffe..d4ae3200e 100644 --- a/doc/sources/guide2/basic.rst +++ b/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 ----------------------- diff --git a/doc/sources/guide2/events.rst b/doc/sources/guide2/events.rst index e9277f95c..5fa466c26 100644 --- a/doc/sources/guide2/events.rst +++ b/doc/sources/guide2/events.rst @@ -4,15 +4,66 @@ 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 contept to get to +newcomers, and the specificies of how to use these in kivy. Once you understand +how events and ways to bind to these, 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 -------------------------- From 0078438566fda33f64f883befa8204ec98312bbd Mon Sep 17 00:00:00 2001 From: tshirtman Date: Mon, 26 Nov 2012 01:11:46 +0100 Subject: [PATCH 2/2] some addition to new documentation --- doc/sources/guide2/basic.rst | 6 ++--- doc/sources/guide2/events.rst | 41 +++++++++++++++++++++++++++++----- doc/sources/guide2/widgets.rst | 25 +++++++++++++++++++++ 3 files changed, 63 insertions(+), 9 deletions(-) diff --git a/doc/sources/guide2/basic.rst b/doc/sources/guide2/basic.rst index d4ae3200e..bc7ccd5fd 100644 --- a/doc/sources/guide2/basic.rst +++ b/doc/sources/guide2/basic.rst @@ -38,9 +38,9 @@ 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. +- 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:: diff --git a/doc/sources/guide2/events.rst b/doc/sources/guide2/events.rst index 5fa466c26..08ae2095b 100644 --- a/doc/sources/guide2/events.rst +++ b/doc/sources/guide2/events.rst @@ -5,19 +5,19 @@ 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 contept to get to -newcomers, and the specificies of how to use these in kivy. Once you understand -how events and ways to bind to these, are everywhere in kivy, it becomes easy +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 +: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. +dispatchers). :cls:`kivy.uix.widget.Widget`, :cls:`kivy.animation.Animation` +and :obj:`kivy.clock.Clock` for example are event dispatchers. Creating custom events ---------------------- @@ -67,8 +67,37 @@ example:: 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 ---------------------------- diff --git a/doc/sources/guide2/widgets.rst b/doc/sources/guide2/widgets.rst index aeb188dac..fe5b8453b 100644 --- a/doc/sources/guide2/widgets.rst +++ b/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.