Under X11, events are selected on a per window basis by ORing
individual event select bitmasks into the event_mask attribute
of the window. To determine which window gets an event, the X server
searches the window hierarchy bottom up, starting with the innermost
window where the event logically happened. If a window selects that
particular event, it is sent to it. If the window discards that event,
the event is thrown away and the search stops. If the window neither
selects nor discards the event, the search resumes with its parent.
Any event that propagates all the way up to the root window without being
selected, is discarded anyway.
When using ProXL, in most cases, the user does not need to know about bitmasks. Events are selected by name, and Prolog routines are attached to Windows to handle the conditions.
The ProXL event handler mechanism receives X11 events, extracts user-specified values and calls the appropriate callback routine.
If there is no registered callback for a given event (including default handlers, as specified later), the event is quietly discarded.
If multiple callbacks are registered for an event in a Window
(as might be the case for button_press or button_release
events),
they are tried sequentially until one succeeds, at which point
the callback is considered satisfied and no more alternatives are tried.
If all the registered callbacks fail, the event is quietly discarded.
Callbacks are Window attributes, and are established using
put_window_attributes/N, or create_window/N,
using one of the following attribute formats:
callback(+EventSpec, +EventValues, +ExitVar, +Context, +Goal)
callback(+EventSpec, +EventValues, +ExitVar, +Goal)
callback(+EventSpec, +EventValues, +Goal)
where EventSpec is a description of the event that should cause the user-supplied callback Goal, a Prolog goal, to be called.
EventValues is either a list of the event fields that the user wants
to be supplied as arguments to Goal
, or the term xevent(E), which instructs
ProXL
to deliver the whole event structure, in the same internal format
used by the event handling functions described in pxl-evf.
ExitVar, if supplied, is either a term that is bound by Goal
when the user wants to exit the event handling
loop and return, or the atom none. If omitted,
it defaults to none and Goal is assumed to not contain an exit
variable.
Context, if supplied, is a term that will be unified with the
Context argument supplied to handle_events/[2,3] when
the callback Goal is executed. If omitted, it defaults to none.
If the user calls handle_events/[0,1], Goal will be called
with Context unbound.