mirror of https://github.com/kivy/kivy.git
75 lines
2.2 KiB
ReStructuredText
75 lines
2.2 KiB
ReStructuredText
.. _events:
|
|
.. _properties:
|
|
|
|
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
|
|
--------------------------
|
|
|
|
Declaration of a Property
|
|
-------------------------
|
|
|
|
Dispatching a Property event
|
|
----------------------------
|