EventDispatcher

Each Screen and Client has an EventDispatcher connected to their root window or client window, respectivly. Additionally, the WindowManager has an EventDispatcher which is connected to all the root windows (through the dispatchers of each Screen).

An event is passed to the event handling functions which have been registered for that particular event type. There are three levels of event handlers in a dispatcher:

System Handlers

System handlers will always be called, even if grab handlers are installed. They will be called before the other types of handlers in this dispatcher. They are primarily meant to be used by the core classes.

Grab Handlers

Grab handlers override previously installed grab handlers and all normal handlers, but not system handlers.

Normal Handlers

Normal handlers are the most useful type of handlers for extension modules. They will be called only if there are no grab handlers installed for this event type.

First of all the handlers in the global dispatcher are called. Then, if the event can be associated with a managed screen through its client, window, or screen attributes the handlers in the dispatcher for that screen are called. Finally, if the event is for a managed window the handlers in the dispatcher for that client are called.

Grab handlers do not interfere with the dispatcher sequence directly, but a grab handler do block grab handlers and normal handlers in later dispatchers. System handler are always called, though.

An example: Assume that an event for a managed client has been fetched and is about to be passed through the dispatchers. The matching event handlers are the following: in the global dispatcher one system handler and two normal handlers, in the screen dispatcher a grab handler and one normal handler, and in the client dispatcher one system handler, one grab handler and one normal handler. The handlers will be called in this order: global system, global normals, screen grab, client system. The screen normal, client grab and normal handlers will be ignored because of the grab handler in the screen.

Handlers are registered with one of these methods:

Method: EventDispatcher add_handler ( type, handler, [ masks = None ], [ handler_id = None ] )

Method: EventDispatcher add_grab_handler ( type, handler, [ masks = None ], [ handler_id = None ] )

Method: EventDispatcher add_system_handler ( type, handler, [ masks = None ], [ handler_id = None ] )

Add a handler for type events. handler is a function which will get one argument, the event object.

If masks is omitted or None the default X event masks for the event type will be set for the EventDispatcher's window. Otherwise it should be an event mask or a list or tuple of event masks to set.

handler_id identifies this handler, and defaults to the handler itself if not provided.

Method: EventDispatcher remove_handler ( handler_id )

Remove the handler or handlers identified by handler_id. This will also clear the masks the handlers had installed.

Event masks can also be handled manually when necessary. All event masks keep a reference count, so calls to the following functions nest neatly.

Method: EventDispatcher set_masks ( masks )

Set masks on the window, without installing any handlers. masks should be an event mask or a list or tuple of event masks to set.

Method: EventDispatcher unset_masks ( masks )

Clear masks on the window. masks should be an event mask or a list or tuple of event masks to set.

Method: EventDispatcher block_masks ( masks )

Block masks on the window. This will prevent any matching X events to be generated on the window until a matching unblock_masks. masks should be an event mask or a list or tuple of event masks to set.

Method: EventDispatcher unblock_masks ( masks )

Unblock masks on the window, allowing the matching X events to be generated. masks should be an event mask or a list or tuple of event masks to set.

Go to the first, previous, next, last section, table of contents.