5.2 EventFetcher

The EventFetcher can provide events to the window manager from a number of sources: the X server, timers, files or the window manager itself.

Synthetic events are generated by some code in the window manager, typically as an abstraction of some user input. As an example, the focus module generates ClientFocusOut and ClientFocusIn events when the focus change, which it can do as an effect of an X.EnterNotify event, or a call to focus.move_focus. Synthetic events have precedence over all other event types.

Method: EventFetcher put_event ( event )

Insert a synthetic event object. Synthetic events are always returned before any timer or X events, in FIFO order.

Timer events are used to do something at a later time. The keys module uses it to implement a time-out on keyboard grabs, and the mw_clock module uses it to update a clock display once a minute. Timer events are represented by TimerEvent objects, and have precedence over file and X events. A timer event object is not reusable, so if something should be done periodically, a new timer event will have to be rescheduled whenever the previous one expires.

Method: EventFetcher add_timer ( timer )

Add the TimerEvent object timer to the list of timers. The expiration time of the event is specified when creating the timer event. The event will be returned when the timer expires unless it is cancelled before that.

Class: TimerEvent ( event_type, after = 0, at = 0 )

Create a a timer event that will expire either at a relative time, set with after, or at a specific time, set with at. Times are measured in seconds as in the time module, and can be integers or floating point values.

Timer events are identified by its type member, which are specified with the event_type argument.

Method: TimerEvent cancel ( )

Cancel this timer event, if it hasn't expired yet.

File events can be used to handle non-blocking I/O. They are generated when some file is ready for reading or writing, and is typically used for network services, e.g. by the inspect module. File events are represented by FileEvent objects, which remain on the list of watched files until they are explicitly cancelled. File events have the lowest priority, and are preceeded by X events.

Method: EventFetcher add_file ( file )

Add the FileEvent object file to the list of watched files. It will be returned whenever its file is ready for the choosen I/O operation.

Class: FileEvent ( event_type, file, mode = None )

Create a file event wathing file, which could be any object with a fileno() method. The event is identified by event_type.

mode is the types of I/O that the caller is interested in, and should be a bitmask of the flags FileEvent.READ, FileEvent.WRITE, or FileEvent.EXCEPTION. If mode is None, the mode attribute of file, as specified to the open() call, will be used instead.

Instance Variable: FileEvent state

When a file event is returned by the event loop, this attribute will be set to a mask of the I/O modes that the file is ready to perform, a subset of the modes waited for.

If FileEvent.READ is set, at least one byte can be read from the file without blocking. If FileEvent.WRITE is set, at least one byte can be written to the file without blocking. If FileEvent.EXCEPTION is set, some exceptional I/O has occured, e.g. out-of-band data on a TCP socket.

Method: FileEvent set_mode ( newmode = None, set = 0, clear = 0 )

Change the I/O modes waited for. If newmode is not None, the mode will be reset to newmode, otherwise the old mode will be modifed. Then the flags in the bitmask set will be added, and the flags in clear will be removed, in that order.

Method: FileEvent cancel ( )

Cancel this file event, removing it from the list of watched files.