15.2.1 The Extended Input Stream Protocol

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]

Arguments: stream

(setf stream-input-buffer) [Generic Function]

Arguments: 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]

Arguments: 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]

Arguments: stream

(setf stream-primary-pointer) [Generic Function]

Arguments: 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]

Arguments: 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]

Arguments: 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]

Arguments: stream

Summary: Sets the "input focus" to the extended input stream
stream
and returns the old input focus as its value.

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.

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
.

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 [Function]

Arguments: 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]

Arguments: 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
.