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.my_callback, state=self.state_callback) self.add_widget(btn) def state_callback(self, obj, value): print obj, value def my_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.
- 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 :
- start with the prefix on_.
- 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
- unregister_event_types()¶
Unregister an event type in the dispatcher.