Event dispatcher

All objects that produce events in Kivy implement EventDispatcher, providing a consistent interface for registering and manipulating event handlers.

Changed in version 1.0.9: Properties discovering and methods have been moved from Widget to EventDispatcher

class kivy.event.EventDispatcher

Bases: object

Generic event dispatcher interface

See the module docstring for usage.

bind()

Bind an event type or a property to a callback

Usage:

# With properties
def my_x_callback(obj, value):
    print 'on object', obj, 'x changed to', value
def my_width_callback(obj, value):
    print 'on object', obj, 'width changed to', value
self.bind(x=my_x_callback, width=my_width_callback)

# With event
self.bind(on_press=self.my_press_callback)

Usage in a class:

class MyClass(BoxLayout):
    def __init__(self):
        super(MyClass, self).__init__()
        btn = Button(text='click me')
        # Bind event to callback
        btn.bind(on_press=self.my_callback)
        self.add_widget(btn)

    def my_callback(self, obj):
        print 'press on button', obj
create_property()

Create a new property at runtime.

New in version 1.0.9.

Warning

This function is designed for the Kivy language, don’t use it in your code. You should declare the property in your class instead of using this method.

Parameters :
name: string

Name of the property

The class of the property cannot be specified, it will always be an ObjectProperty class. The default value of the property will be None, until you set a new value.

>>> mywidget = Widget()
>>> mywidget.create_property('custom')
>>> mywidget.custom = True
>>> print mywidget.custom
True
dispatch()

Dispatch an event across all the handler added in bind(). As soon as a handler return True, the dispatching stop

getter()

Return the getter of a property.

New in version 1.0.9.

is_event_type()

Return True if the event_type is already registered.

New in version 1.0.4.

properties()

Return all the properties in that class in a dictionnary of key/property class. Can be used for introspection.

New in version 1.0.9.

property()

Get a property instance from the name.

New in version 1.0.9.

Returns:A Property derivated instance corresponding to the name.
register_event_type()

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers. Each event type declaration must :

  1. start with the prefix on_
  2. have a default handler in the class

Example of creating custom event:

class MyWidget(Widget):
    def __init__(self, **kwargs):
        super(MyWidget, self).__init__(**kwargs)
        self.register_event_type('on_swipe')

    def on_swipe(self):
        pass

def on_swipe_callback(*largs):
    print 'my swipe is called', largs
w = MyWidget()
w.dispatch('on_swipe')
setter()

Return the setter of a property. Useful if you want to directly bind a property to another.

New in version 1.0.9.

For example, if you want to position one widget next to you:

self.bind(right=nextchild.setter('x'))
unbind()

Unbind properties from callback functions.

Same usage as bind().

unregister_event_types()

Unregister an event type in the dispatcher