12.3 Processing Events

Events received by a CLX client are stored in an event queue until they are read and processed. Events are processed by handler functions.

handler-function

&rest event-slots &key :display :event-key :send-event-p & allow-other-keys

Function

:display: A display for the connection that returned the event.
:event-key: An event-key keyword specifying the event type.
:send-event-p: If true, the event was sent from another application using the send-event function.

The arguments to a handler function are keyword-value pairs that describe the contents of an event. The actual event-slots passed depend on the event type, except that :display, :event-key, and :send-event-p are given for all event types. The keyword symbols used for each event type are event slot names defined by the declare-event macro and are described in paragraph 12.12.8, Declaring Event Types.

If a handler returns non-nil, the event is considered processed and can be removed from the event queue. Otherwise, if a handler function returns nil, the event can remain in the event queue for later processing.

handled-p: Type boolean.

process-event

display &key :handler :timeout :peek-p :discard-p (:force-output-p t)

Function

display: A display.
:handler: A handler function or a sequence of handler functions.
:timeout: Specifies the timeout delay in seconds.
:peek-p: If nil, events are removed from the event queue after processing.
:discard-p: If true, unprocessed events are discarded.
:force-output-p: If true, buffered output requests are sent.

Invokes :handler on each queued event until :handler returns non-nil. Then, the non-nil :handler value is returned by process-event. If :handler returns nil for each event in the event queue, process-event waits for another event to arrive. If timeout is non-nil and no event arrives within the specified timeout interval (given in seconds), process-event returns nil; if timeout is nil , process-event will not return until :handler returns non-nil. process-event may wait only once on network data, and therefore timeout prematurely.

If :force-output-p is true, process-event first invokes display-force-output to send any buffered requests. If :peek-p is true, a processed event is not removed from the queue. If :discard-p is true, unprocessed events are removed from the queue; otherwise, unprocessed events are left in place.

If :handler is a sequence, it is expected to contain handler functions for each event type. The sequence index of the handler function for a particular event type is given by ( position event-key *event-key-vector*).

handled-p: Type boolean.

event-case

display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses

Macro

display: A display.
:handler: A handler function or a sequence of handler functions.
:timeout: Specifies the timeout delay, in seconds.
:peek-p: If nil, events are removed from the event queue after processing.
:discard-p: If true, unprocessed events are discarded.
:force-output-p: If true, buffered output requests are sent.
clauses: Code to process specified event types.

Executes the matching clause for each queued event until a clause returns non-nil. The non-nil clause value is then returned. Each of the clauses is a list of the form ( event-match [event-slots] &rest forms), where:

event-match -- Either an event-key, a list of event-keys, otherwise, or t. It is an error for the same key to appear in more than one clause.
event-slots -- If given, a list of (non-keyword) event slot symbols defined for the specified event type(s). See paragraph 12.12.8, Declaring Event Types.
forms -- A list of forms that process the specified event type(s). The value of the last form is the value returned by the clause.

A clause matches an event if the event-key is equal to or a member of the event-match, or if the event-match is t or otherwise. If no t or otherwise clause appears, it is equivalent to having a final clause that returns nil. If event-slots is given, these symbols are bound to the value of the corresponding event slot in the clause forms. Each element of event-slots can also be a list of the form ( event-slot-keyword variable), in which case the variable symbol is bound to the value of the event slot specified by the event-slot-keyword.

If every clause returns nil for each event in the event queue, event-case waits for another event to arrive. If :timeout is non-nil and no event arrives within the specified timeout interval (given in seconds), event-case returns nil; if :timeout is nil, event-case will not return until a clause returns non-nil. event-case may wait only once on network data and therefore timeout prematurely.

If :force-output-p is true, event-case first invokes display-force-output to send any buffered requests. If :peek-p is true, a processed event is not removed from the queue. If :discard-p is true, unprocessed events are removed from the queue; otherwise, unprocessed events are left in place.

handled-p: Type boolean.

event-cond

display &key :timeout :peek-p :discard-p (:force-output-p t) &body clauses

Macro

display: A display.
:handler: A handler function or a sequence of handler functions.
:timeout: Specifies the timeout delay in seconds.
:peek-p: If nil, events are removed from the event queue after processing.
:discard-p: If true, unprocessed events are discarded.
:force-output-p: If true, buffered output requests are sent.
clauses: Code to process specified event types.

Similar to event-case except that each of the clauses is a list of the form (event-match [event-slots] test-form &rest forms). Executes the test-form of the clause that matches each queued event until a test-form returns non-nil. The body forms of the clause are then executed. The values returned by the last clause body form are then returned by event-cond .

When a test-form returns true and :peek-p is nil, or when a test-form returns nil and :discard-p is true, the matching event is removed from the event queue before the body forms are executed.

handled-p: Type boolean.