Quick search

Table Of Contents

Event dispatcher

All objects that produce events in Kivy implement the EventDispatcher which provides a consistent interface for registering and manipulating event handlers.

Changed in version 1.0.9: Property discovery and methods have been moved from the Widget to the EventDispatcher.

class kivy.event.EventDispatcher

Bases: kivy.event.ObjectWithUid

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)

Most callbacks are called with the arguments ‘obj’ and ‘value’. Some however, provide only one argument, ‘obj’ e.g. the on_press event.

Usage in a class:

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

    def state_callback(self, obj, value):
        print obj, value

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

Create a new property at runtime.

New in version 1.0.9.

Changed in version 1.8.0: value parameter added, can be used to set the default value of the property. Also, the type of the value is used to specialize the created property.

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

value: object, optional

Default value of the property. Type is also used for creating a more appropriate property types. Default to None.

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 handlers added in bind(). As soon as a handler returns True, the dispatching stops.

The function collects all the positional and keyword arguments and passes them on to the handlers.

Note

The handlers are called in reverse order than they were registered with bind().

Parameters :
event_type: str

the event name to dispatch.

Changed in version 1.8.1: keyword arguments collection and forwarding was added. Before, only positional arguments would be collected and forwarded.

events()

Return all the events in the class. Can be used for introspection.

New in version 1.8.0.

get_property_observers()

Returns a list of methods that are bound to the property/event passed as the name argument:

widget_instance.get_property_observers('on_release')

New in version 1.8.0.

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 the class in a dictionary 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 derived 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 a 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. Use: instance.setter(‘name’). The setter is a convenient callback function useful if you want to directly bind one property to another. It returns a partial function that will accept (obj, value) args and results in the property ‘name’ of instance being set to value.

New in version 1.0.9.

For example, to bind number2 to number1 in python you would do:

class ExampleWidget(Widget):
    number1 = NumericProperty(None)
    number2 = NumericProperty(None)

    def __init__(self, **kwargs):
        super(ExampleWidget, self).__init__(**kwargs)
        self.bind(number1=self.setter('number2'))

This is equivalent to kv binding:

<ExampleWidget>:
    number2: self.number1
unbind()

Unbind properties from callback functions.

Same usage as bind().

unregister_event_types()

Unregister an event type in the dispatcher.