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.