In addition to the basic input stream protocol, CLIM defines an extended input stream protocol. This protocol extends the stream model to allow manipulation of non-character user gestures, such as pointer button presses. The extended input protocol provides the programmer with more control over input processing, including the options of specifying input wait timeouts and auxiliary input test functions.
extended-input-stream Protocol Class
Summary: The protocol class for CLIM extended input streams. This is a subclass of input-stream. If you want to create a new class that behaves like an extended input stream, it should be a subclass of extended-input-stream. Subclasses of extended-input-stream must obey the extended input stream protocol.
extended-input-stream-p Function
extended-input-stream-p object
Summary: Returns t if object is a CLIM extended input stream; otherwise, it returns nil.
:input-buffer
:pointer
:text-cursor Initargs
Summary: All subclasses of extended-input-stream must handle these initargs, which are used to specify, respectively, the input buffer, pointer, and text cursor for the extended input stream.
standard-extended-input-stream Class
Summary: This class provides an implementation of the CLIM extended input stream protocol based on CLIM's input kernel. The extended input stream maintains the state of the display's pointing devices (such as a mouse) in pointer objects associated with the stream. It defines a handle-event methods for keystroke and pointer motion and button press events and updates the pointer object state and queues the resulting events in a per-stream input buffer.
Members of this class are mutable.
The following generic functions comprise the extended input stream protocol. All extended input streams must implement methods for these generic functions.
stream-input-buffer Generic Function
stream-input-buffer stream
(setf stream-input-buffer) Generic Function
(setf stream-input-buffer) buffer stream
Summary: These functions provide access to the stream's input buffer. Normally programs do not need to manipulate the input buffer directly. It is sometimes useful to cause several streams to share the same input buffer so that input that comes in on one of them is available to an input call on any of the streams. The input buffer must be a vector with a fill pointer capable of holding general input gesture objects (such as characters and event objects).
stream-pointers Generic Function
stream-pointers stream
Summary: Returns the list of pointer objects corresponding to the pointing devices of the port associated with stream. This function returns objects that reveal CLIM's internal state; do not modify those objects.
stream-primary-pointer Generic Function
stream-primary-pointer stream
(setf stream-primary-pointer) Generic Function
(setf stream-primary-pointer) pointer stream
Summary: Returns (or sets) the pointer object corresponding to the primary pointing device of the console.
Note: CLIM currently supports only a single pointer for any port. Therefore, the length of the list returned by stream-pointers will always be one, and stream-primary-pointer will always return an object that is the only element of that list.
stream-pointer-position Generic Function
stream-pointer-position stream &key pointer
Summary: Returns the current position of the pointing device pointer for the extended input stream stream as two values, the x and y positions in the stream's drawing surface coordinate system. If pointer is not supplied, it defaults to the stream-primary-pointer of the stream.
(setf* stream-pointer-position) Generic Function
(setf* stream-pointer-position) x y stream &key pointer
Summary: Sets the position of the pointing device for the extended input stream stream to x and y, which are integers. pointer is as for stream-pointer-position. For the details of setf*, see C.4 Multiple-Value Setf.
stream-set-input-focus Generic Function
stream-set-input-focus stream
Summary: Sets the "input focus" to the extended input stream stream and returns the old input focus as its value.
stream-restore-input-focus Generic Function
stream-restore-input-focus stream old-focus
Summary: Restores the "input focus" of the extended input stream stream to old-focus.
with-input-focus (stream) &body body
Summary: Temporarily gives the keyboard input focus to the extended input stream stream. By default, an application frame gives the input focus to the window associated with frame-query-io.
The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t, *standard-input* is used. body may have zero or more declarations as its first forms.
*input-wait-test*
*input-wait-handler*
*pointer-button-press-handler* Variables
Summary: These three variables are used to hold the default values for the current input wait test, wait handler, and pointer button press handler. These variables are globally bound to nil.
read-gesture &key (stream *standard-input*) timeout peek-p (input-wait-test *input-wait-test*) (input-wait-handler *input-wait-handler*) (pointer-button-press-handler *pointer-button-press-handler*)
Summary: Calls stream-read-gesture on the extended input stream stream and all of the other keyword arguments. Returns the next gesture available in the extended input stream stream; the gesture will be a character, an event (such as a pointer button event), or (values nil :timeout) if no input is available. The input is not echoed.
These arguments are the same as for stream-read-gesture.
stream-read-gesture Generic Function
stream-read-gesture stream &key timeout peek-p (input-wait-test *input-wait-test*) (input-wait-handler *input-wait-handler*) (pointer-button-press-handler *pointer-button-press-handler*)
Summary: Returns the next gesture available in the extended input stream stream; the gesture will be either a character or an event (such as a pointer button event). The input is not echoed.
If the user types an abort gesture (that is, a gesture that matches any of the gesture names in *abort-gestures*), then the abort-gesture condition will be signaled.
If the user types an accelerator gesture (that is, a gesture that matches any of the gesture names in *accelerator-gestures*), then the accelerator-gesture condition will be signaled.
stream-read-gesture works by invoking stream-input-wait on stream, input-wait-test, and timeout, and then processing the input, if there is any.
timeout is either nil or an integer that specifies the number of seconds that stream-read-gesture will wait for input to become available. If no input is available, stream-read-gesture will return two values, nil and :timeout.
If peek-p is t, the returned gesture will be left in the stream's input buffer.
input-wait-test is a function of one argument, the stream. The function should return t when there is input to process, otherwise it should return nil. This argument will be passed on to stream-input-wait. stream-read-gesture will bind *input-wait-test* to input-wait-test.
input-wait-handler is a function of one argument, the stream. It is called when stream-input-wait returns nil (that is, no input is available). This option can be used in conjunction with input-wait-test to handle conditions other than keyboard gestures, or to provide some sort of interactive behavior (such as highlighting applicable presentations). stream-read-gesture will bind *input-wait-handler* to input-wait-handler.
pointer-button-press-handler is a function of two arguments, the stream and a pointer button press event. It is called when the user clicks a pointer button. stream-read-gesture will bind *pointer-button-press-handler* to pointer-button-press-handler.
input-wait-test, input-wait-handler, and pointer-button-press-handler have dynamic extent.
stream-input-wait Generic Function
stream-input-wait stream &key timeout input-wait-test
Summary: Waits for input to become available on the extended input stream stream. timeout and input-wait-test are as for stream-read-gesture.
unread-gesture gesture &key (stream *standard-input*)
Summary: Calls stream-unread-gesture on gesture and stream. These arguments are the same as for stream-unread-gesture.
stream-unread-gesture Generic Function
stream-unread-gesture stream gesture
Summary: Places gesture back into the extended input stream stream's input buffer. The next call to stream-read-gesture request will return the unread gesture. gesture must be the most recent gesture read from the stream via read-gesture.
Summary: A list of all of the gesture names that correspond to abort gestures. The global set of standard abort gestures is unspecified; it includes the :abort gesture name. The actual keystroke sequence is Control-z.
Summary: This condition is signaled by read-gesture whenever an abort gesture (one of the gestures in *abort-gestures*) is read from the user.
abort-gesture-event Generic Function
abort-gesture-event condition
Summary: Returns the event that cause the abort gesture condition to be signaled. condition is an object of type abort-gesture.
*accelerator-gestures* Variable
Summary: A list of all of the gesture names that correspond to keystroke accelerators. The global value for this is nil.
accelerator-gesture Condition Class
Summary: This condition is signaled by read-gesture whenever an keystroke accelerator gesture (one of the gestures in *accelerator-gestures*) is read from the user.
accelerator-gesture-event Generic Function
accelerator-gesture-event condition
Summary: Returns the event that causes the accelerator gesture condition to be signaled. condition is an object of type accelerator-gesture.
accelerator-gesture-numeric-argument Generic Function
accelerator-gesture-numeric-argument condition
Summary: Returns the accumulated numeric argument (maintained by the input editor) at the time the accelerator gesture condition was signaled. condition is an object of type accelerator-gesture.
CLIM 2.0 User Guide - 01 Dec 2021 19:39:00