The material in this section is advanced; most CLIM programmers can skip to the next chapter. This section discusses the Input Editing Stream Protocol.
Input editing streams obey both the extended input and extended output stream protocols, and must support the generic functions that comprise those protocols. For the most part, this simply entails "trampolining" those operations to the encapsulated interactive stream. However, such generic functions as stream-read-gesture and stream-unread-gesture will need methods that observe the use of the input editor's scan pointer.
Input editing streams implement methods for prompt-for-accept (in order to provide in-line prompting that interacts correctly with input editing) and stream-accept (in order to cause accept to obey the scan pointer).
The following generic functions comprise the remainder of the input editing protocol, and must be implemented for all classes that inherit from input-editing-stream .
stream-input-buffer [Generic Function]
Arguments: (stream input-editing-stream )
Summary: Returns the input buffer (that is, the string being edited) associated with the input editing stream stream . This must be an unspecialized vector with a fill pointer. The fill pointer of the vector points past the last gesture object in the buffer. This buffer is affected during input editing. The effects of modifying the input buffer other than by the specified API (such as replace-input ) are unspecified.
stream-insertion-pointer [Generic Function]
Summary: Returns an integer corresponding to the current input position in the input editing stream stream 's buffer, that is, the point in the buffer at which the next user input gesture will be inserted. The insertion pointer will always be less than or equal to (fill-pointer (stream-input-buffer stream )) . The insertion pointer can also be thought of as an editing cursor.
(setf stream-insertion-pointer) [Generic Function]
Summary: Changes the input position of the input editing stream stream to pointer , an integer less than or equal to (fill-pointer (stream-input-buffer stream )) .
stream-scan-pointer [Generic Function]
Summary: Returns an integer corresponding to the current scan pointer in the input editing stream stream 's buffer, that is, the point in the buffer at which calls to accept have stopped parsing input. The scan pointer will always be less than or equal to (stream-insertion-pointer stream ) .
(setf stream-scan-pointer) [Generic Function]
Summary: Changes the scan pointer of the input editing stream stream to pointer , an integer less than or equal to (stream-insertion-pointer stream ) .
stream-rescanning-p [Generic Function]
Summary: Returns the state of the input editing stream stream 's "rescan in progress" flag, which is t if stream is performing a rescan operation, but otherwise nil . All extended input streams must implement a method for this, but non-input editing streams will always returns nil .
reset-scan-pointer [Generic Function]
Arguments: stream &optional (scan-pointer 0 )
Summary: Sets the input editing stream stream 's scan pointer to scan-pointer , and sets the state of stream-rescanning-p to t .
immediate-rescan [Generic Function]
Summary: Invokes a rescan operation immediately by "throwing" out to the most recent invocation of with-input-editing .
queue-rescan [Generic Function]
Summary: Sets the "rescan queued" flag to t , meaning that the input editing stream stream should be rescanned after the next non-input editing gesture is read.
rescan-if-necessary [Generic Function]
Summary: Invokes a rescan operation on the input editing stream stream if queue-rescan was called on the same stream and no intervening rescan operation has taken place. Resets the state of the "rescan queued" flag to nil .
erase-input-buffer [Generic Function]
Arguments: stream &optional (start-position 0 )
Summary: Erases the part of the display that corresponds to the input editor's buffer, starting at the position start-position .
redraw-input-buffer [Generic Function]
Arguments: stream &optional (start-position 0 )
Summary: Displays the input editor's buffer starting at the position start-position on the interactive stream that is encapsulated by the input editing stream stream .
stream-process-gesture [Generic Function]
Arguments: stream gesture type
Summary: If gesture is an input editing command, stream-process-gesture performs the input editing operation on the input editing stream stream and returns nil . Otherwise, it returns the two values gesture and type .
stream-read-gesture [Generic Function]
Arguments: (stream standard-input-editing-stream ) &allow-other-keys
Summary: Reads and returns a gesture from the user on the input editing stream stream .
The stream-read-gesture method calls stream-process-gesture , which will either return a "real" gesture (such as a typed character, a pointer gesture, or a timeout) or nil (indicating that some sort of input editing operation was performed). stream-read-gesture only returns when a real gesture has been read; if an input editing operation was performed, stream-read-gesture will loop until a "real" gesture is typed by the user.
stream-unread-gesture [Generic Function]
Arguments: (stream standard-input-editing-stream ) gesture
Summary: Inserts the gesture gesture back into the input editor's buffer, maintaining the scan pointer.