Next Prev Up Top Contents Index

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.

stream-restore-input-focus [Generic Function]

Arguments: stream old-focus

Summary: Restores the "input focus" of the extended input stream stream to old-focus .

with-input-focus [Macro]	

Arguments: (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* 

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

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

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

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


CommonLisp Interface Manager 2.0 User's Guide - 8 Aug 2003

Next Prev Up Top Contents Index