CLIM's windowing substrate provides an input architecture and standard functionality for notifying clients of input that is distributed to their sheets. Input includes such events as the pointer entering and exiting sheets, pointer motion (whose granularity is defined by performance limitations), and pointer button and keyboard events. At this level, input is represented as event objects.
Sheets either participate fully in the input protocol or are mute for input. If any functions in the input protocol are called on a sheet that is mute for input, the sheet-is-mute-for-input error will be signaled.
In addition to handling input event, a sheet is also responsible for providing other input services, such as controlling the pointer's appearance, and polling for current pointer and keyboard state.
Input is processed on a per-port basis.
The event-processing mechanism has three main tasks when it receives an event. First, it must determine to which client the event is addressed; this process is called distributing. Typically, the client is a sheet, but there are other special-purpose clients to which events can also be dispatched. Next, it formats the event into a standard format, and finally it dispatches the event to the client. A client may then either handle the event synchronously, or it may queue it for later handling by another process.
Input events can be broadly categorized into pointer events and keyboard events. By default, pointer events are dispatched to the lowest sheet in the hierarchy whose region contains the location of the pointer. Keyboard events are dispatched to the port's keyboard input focus; the accessor port-keyboard-input-focus contains the event client that receives the port's keyboard events.
In the functions listed here, the client argument is typically a sheet, but it may be another object that supports event distribution, dispatching, and handling.
port-keyboard-input-focus Generic Function
port-keyboard-input-focus port
(setf port-keyboard-input-focus) Generic Function
(setf port-keyboard-input-focus) focus port
Summary: Returns the client to which keyboard events are to be dispatched.
distribute-event Generic Function
distribute-event port event
Summary: The event is distributed to the port's proper client. In general, this will be the keyboard input focus for keyboard events, and the lowest sheet under the pointer for pointer events.
dispatch-event Generic Function
dispatch-event client event
Summary: This function is called to inform a client about an event of interest. Most methods for this function will simply queue the event for later handling. Certain classes of clients and events may cause this function to call either queue-event or handle-event immediately, or else to ignore the event entirely.
queue-event client event
Summary: Places the event event into the queue of events for the client client.
handle-event client event
Summary: Implements the client's policy with respect to the event. For example, if the programmer wishes to highlight a sheet in response to an event that informs it that the pointer has entered its territory, there would be a method to carry out the policy that specializes the appropriate sheet and event classes.
In addition to queue-event, the queued input protocol handles the following generic functions:
event-read client
Summary: Takes the next event out of the queue of events for this client.
event-read-no-hang Generic Function
event-read-no-hang client
Summary: Takes the next event out of the queue of events for this client. It returns nil if there are no events in the queue.
event-peek client &optional event-type
Summary: Returns the next event in the queue without removing it from the queue. If event-type is supplied, events that are not of that type are first removed and discarded.
event-unread client event
Summary: Places the event at the head of the client's event queue, to be the event read next.
event-listen client
Summary: Returns t if there are any events queued for client; otherwise, it returns nil.
apply-in-sheet-process Function
apply-in-sheet-process sheet function &rest args
Summary: Applies function to args on the process that displays sheet.
The function apply-in-sheet-process arranges for function to apply to args, by (apply function args), in the process that displays sheet.
The application occurs only if sheet is inside a hierarchy of sheets that is currently displayed.
The result is t if apply-in-sheet-process "succeeded", which means it dispatched an event to perform the application. The application may still not happen if the process that display sheet does not reach the point of handling the event (e.g. the user closes the window).
apply-in-sheet-process is especially useful for using the display functions of CLIM (drawing and stream output), which need to happen on the correct process.
For example:
(apply-in-sheet-process sheet
`draw-rectangle* sheet 10 10 100 100)
Most classes of sheets will have one of the following irun timenput protocol classes mixed in. Of course, a sheet can always have a specialized method for a specific class of event that will override the default. For example, a sheet may need to have only pointer click events dispatched to itself, and may delegate all other events to some other input client. Such a sheet should have delegate-sheet-input-mixin as a superclass, and have a more specific method for dispatch-event on its class and pointer-button-click-event.
standard-sheet-input-mixin Class
Summary: This class of sheet provides a method for dispatch-event that calls queue-event on each device event. Configuration events invoke handle-event immediately.
immediate-sheet-input-mixin Class
Summary: This class of sheet provides a method for dispatch-event that calls handle-event immediately for all events.
Summary: This is mixed into any sheet class that does not handle any input events.
delegate-sheet-input-mixin Class
Summary: This class of sheet provides a method for dispatch-event that calls dispatch-event on a designated substitute and the event. The initialization argument :delegate or the accessor delegate-sheet-delegate may be used to set the recipient of dispatched events. A value of nil will cause input events to be discarded.
delegate-sheet-delegate Generic Function
delegate-sheet-delegate sheet
(setf delegate-sheet-delegate) Generic Function
(setf delegate-sheet-delegate) delegate sheet
Summary: This may be set to another recipient of events dispatched to a sheet of class delegate-sheet-input-mixin. If the delegate is nil, events are discarded.
CLIM 2.0 User Guide - 01 Dec 2021 19:39:01