mirror of https://github.com/kivy/kivy.git
105 lines
3.3 KiB
ReStructuredText
105 lines
3.3 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 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 classes of the framework is the
|
|
:class:`kivy.event.EventDispatcher` class, this class allows to register event
|
|
types, and to dispatch them to interrested parties (usually other event
|
|
dispatchers). :class:`kivy.uix.widget.Widget`,
|
|
:class:`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):
|
|
self.register_event_type('on_test')
|
|
super(MyEventDispatcher, self).__init__(**kwargs)
|
|
|
|
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.
|
|
|
|
- :class:`kivy.properties.StringProperty`
|
|
- :class:`kivy.properties.NumericProperty`
|
|
- :class:`kivy.properties.ObjectProperty`
|
|
- :class:`kivy.properties.ListProperty`
|
|
- :class:`kivy.properties.ObjectProperty`
|
|
- :class:`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
|
|
----------------------------
|