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
stream-input-buffer (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
stream-insertion-pointer stream
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
(setf stream-insertion-pointer) pointer stream
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
stream-scan-pointer stream
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
(setf stream-scan-pointer) pointer stream
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
stream-rescanning-p stream
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
reset-scan-pointer 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
immediate-rescan stream
Summary: Invokes a rescan operation immediately by "throwing" out to the most recent invocation of with-input-editing.
queue-rescan stream
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
rescan-if-necessary stream
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
erase-input-buffer 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
redraw-input-buffer 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
stream-process-gesture 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
stream-read-gesture (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
stream-unread-gesture (stream standard-input-editing-stream) gesture
Summary: Inserts the gesture gesture back into the input editor's buffer, maintaining the scan pointer.
CLIM 2.0 User Guide - 01 Dec 2021 19:39:00