Event Manager

The EventManagerBase is the abstract class intended for specific implementation of dispatching motion events (instances of MotionEvent) to widgets through on_motion() method of the Widget class.

Warning

This feature is experimental and it remains so while this warning is present.

Manager is a layer between the window and its widgets. WindowBase will forward all the events it receives in on_motion() method to the all managers who declared to receive types of those events. Event will continue to go through the managers list even if one of them accept it (by returning True).

When to use an event manager

Use a manager when you want to:

• Dispatch touch, hover, keyboard, joystick or any other events to the widgets through on_motion() method.

• Dispatch filtered motion events by any criteria, like by a device or a profile.

• Combine several motion events (touch, hover etc.) into one new event and dispatch it to the widgets.

• Dispatch one-time generic events, like app pause/resume.

• Write an event simulator, like a touch simulator which draws a circle on window’s canvas for every simulated touch.

Defining and registering an event manager

1. Inherit EventManagerBase and set which events this manager should receive by declaring event types in EventManagerBase.type_ids attribute.

2. Implement EventManagerBase.dispatch() which will be called by window to pass event type (one of “begin”, “update”, “end”) and an event.

3. Implement EventManagerBase.start() and EventManagerBase.stop() to allocate and release additional resources if needed.

4. Register a manager instance to window using method register_event_manager(). This can be done by overriding methods build() or on_start().

All registered managers are kept in the event_managers list. To unregister a manager call unregister_event_manager() which itself can be called in on_stop() method.

Dispatching events to the widgets

Once registered, window will start the manager and forward all events of types declared in EventManagerBase.type_ids to the manager’s EventManagerBase.dispatch() method. It’s up to manager to decide how to dispatch them, either by going through EventManagerBase.window.children list and dispatching on_motion event or by using some different logic. It’s also up to manager to dispatch grabbed events if grab feature is supported by the event (see grab() and ungrab() methods).

Manager can assign a different dispatch mode to decide how event should be dispatched throughout the widget tree by changing the value of the dispatch_mode attribute. Before changing the mode manager should store/restore the current one, either by using a local variable or by using event’s push() / pop() methods.

Currently there are three dispatch modes (behaviors) recognized by the on_motion method in Widget class:

1. Default dispatch (requires MODE_DEFAULT_DISPATCH) - event will go through widget’s children list, starting with the first widget in the list until event gets accepted or last widget registered for that event is reached. Mode MODE_DEFAULT_DISPATCH is assigned by default in MotionEvent class.

2. Filtered dispatch (requires MODE_FILTERED_DISPATCH) - event will go only through registered child widgets.

3. No dispatch to children (requires MODE_DONT_DISPATCH) - event will not be dispatched to child widgets.

Note that window does not have a motion_filter property and therefore does not have a list of filtered widgets from its children list.

class kivy.eventmanager.EventManagerBase

Bases: builtins.object

Abstract class with methods start(), stop() and dispatch() for specific class to implement.

Example of the manager receiving touch and hover events:

class TouchHoverManager(EventManagerBase):

    type_ids = ('touch', 'hover')

    def start(self):
        # Create additional resources, bind callbacks to self.window

    def dispatch(self, etype, me):
        if me.type_id == 'touch':
            # Handle touch event
        elif me.type_id == 'hover'
            # Handle hover event

    def stop(self):
        # Release resources

dispatch(etype, me)

Dispatch event me to the widgets in the window.

Parameters:

etype: str

One of “begin”, “update” or “end”

me: MotionEvent

The Motion Event currently dispatched.

Returns:

bool True to stop event dispatching

New in version 2.1.0.

start()

Start the manager, bind callbacks to the objects and create additional resources. Attribute window is assigned when this method is called.

New in version 2.1.0.

stop()

Stop the manager, unbind from any objects and release any allocated resources.

New in version 2.1.0.

type_ids = None

Override this attribute to declare the type ids of the events which manager wants to receive. This attribute will be used by WindowBase to know which events to pass to the dispatch() method.

New in version 2.1.0.

window = None

Holds the instance of the WindowBase.

New in version 2.1.0.

kivy.eventmanager.MODE_DEFAULT_DISPATCH = 'default'

Assign this mode to make event dispatch through widget’s children list, starting with the first widget in the list until event gets accepted or last widget registered for that event is reached. Widgets after the last registered widget are ignored.

New in version 2.1.0.

kivy.eventmanager.MODE_DONT_DISPATCH = 'none'

Assign this mode to prevent event from dispatching to child widgets.

New in version 2.1.0.

kivy.eventmanager.MODE_FILTERED_DISPATCH = 'filtered'

Assign this mode to make event dispatch only to child widgets which were previously registered to receive events of the same type_id and not to all child widgets.

New in version 2.1.0.