22.2 Extended Input Streams

  • 22.2.1 The Extended Input Stream Protocol
  • 22.2.2 Extended Input Stream Conditions
  • 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. [annotate]

    extended-input-stream   [Protocol Class]
              

    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. All instantiable subclasses of extended-input-stream must obey the extended input stream protocol. [annotate]

    [annotate]

    extended-input-stream-p  object [Protocol Predicate]
              

    Returns true if object is a CLIM extended input stream, otherwise returns false. [annotate]

    [annotate]

    :input-buffer   [Initarg]
    :pointer   [Initarg]
    :text-cursor   [Initarg]
              

    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. [annotate]

    [annotate]

    standard-extended-input-stream   [Class]
              

    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. [annotate]

    Members of this class are mutable. [annotate]

    [annotate]

    22.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. [annotate]

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

    The 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 vector with a fill pointer capable of holding general input gesture objects (such as characters and event objects). [annotate]

    Note: Assuming that the input buffer is shared by multiple streams, it needs to be a queue (i.e not a vector), or have a shared scan pointer. [edit]-- DK 2020-07-27 11:19Z
     

    [annotate]

    stream-pointer-position  stream &key pointer [Generic Function]
              

    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 port-pointer of the stream's port. [annotate]

    Note: Yet, port-pointer is not documented. [edit]-- Gilbert Baumann 2020-01-30 19:54Z
     

    [annotate]

    (setf* stream-pointer-position)  x y stream &key pointer [Generic Function]
              

    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. [annotate]

    For CLIM implementations that do not support setf*, the "setter" function for this is stream-set-pointer-position. [annotate]

    [annotate]

    stream-set-input-focus  stream [Generic Function]
              

    Sets the "input focus" to the extended input stream stream by changing the value of port-keyboard-input-focus and returns the old input focus as its value. [annotate]

    [annotate]

    with-input-focus  (stream) &body body [Macro]
              

    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. [annotate]

    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. [annotate]

    [annotate]

    *input-wait-test*   [Variable]
    *input-wait-handler*   [Variable]
    *pointer-button-press-handler*   [Variable]
              

    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. [annotate]

    [annotate]

    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*) [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*) [Generic Function]
              

    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. [annotate]

    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 signalled. [annotate]

    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 signalled. [annotate]

    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. :around methods on this generic function can be used to implement some sort of a gesture preprocessing mechanism on every gesture; CLIM's input editor will typically be implemented this way. [annotate]

    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. [annotate]

    If the boolean peek-p is true, then the returned gesture will be left in the stream's input buffer. [annotate]

    input-wait-test is a function of one argument, the stream. The function should return true when there is input to process, otherwise it should return false. This argument will be passed on to stream-input-wait. stream-read-gesture will bind *input-wait-test* to input-wait-test. [annotate]

    Note:

    When INPUT-WAIT-TEST returns T, then STREAM-INPUT-WAIT should return

    (values nil :wait-function)

    It is provided as means to escape blocking wait when state not related to input-buffer changes. This is implicit from what is said in next paragraph.

    [edit]-- Daniel Kochmanski 2019-06-26 07:40Z
     

    input-wait-handler is a function of one argument, the stream. It is called when stream-input-wait returns false (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. [annotate]

    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. [annotate]

    input-wait-test, input-wait-handler, and pointer-button-press-handler have dynamic extent. [annotate]

    [annotate]

    stream-input-wait  stream &key timeout input-wait-test [Generic Function]
              

    Waits for input to become available on the extended input stream stream. timeout and input-wait-test are as for stream-read-gesture. [annotate]

    [annotate]

    Note: What does it do with the input? Does it return it? If not, what does it return? [edit]-- Robert Strandh 2010-08-08 09:55Z
     
    Note:

    This function is like stream-listen, but with a timeout and a wait-test. That is: it returns a generalized boolean.

    If the return value is false, then it returns also a second value denoting the reason why input is not available. This interpretation seems to be consistent with the description in

    [22.2.1 The Extended Input Stream Protocol, stream-read-gesture]

    [edit]-- Daniel Kochmanski 2020-01-21 17:10Z
     

    unread-gesture  gesture &key (stream *standard-input*) [Function]
              

    Calls stream-unread-gesture on gesture and stream. These arguments are the same as for stream-unread-gesture. [annotate]

    [annotate]

    stream-unread-gesture  stream gesture [Generic Function]
              

    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. The gesture supplied must be the most recent gesture read from the stream via read-gesture. [annotate]

    [annotate]

    22.2.2 Extended Input Stream Conditions

    *abort-gestures*   [Variable]
              

    A list of all of the gesture names that correspond to abort gestures. The exact global set of standard abort gestures is unspecified, but must include the :abort gesture name. [annotate]

    [annotate]

    abort-gesture   [Condition]
              

    This condition is signalled by read-gesture whenever an abort gesture (one of the gestures in *abort-gestures* is read from the user. This condition will handle the :event initarg, which is used to supply the event corresponding to the abort gesture. [annotate]

    [annotate]

    abort-gesture-event  condition [Generic Function]
              

    Returns the event that cause the abort gesture condition to be signalled. condition is an object of type abort-gesture. [annotate]

    [annotate]

    *accelerator-gestures*   [Variable]
              

    A list of all of the gesture names that correspond to keystroke accelerators. The global value for this is nil. [annotate]

    [annotate]

    accelerator-gesture   [Condition]
              

    This condition is signalled by read-gesture whenever an keystroke accelerator gesture (one of the gestures in *accelerator-gestures* is read from the user. This condition will handle the :event and the :numeric-argument initargs, which are used to supply the event corresponding to the abort gesture and the accumulated numeric argument (which defaults to 1). [annotate]

    [annotate]

    accelerator-gesture-event  condition [Generic Function]
              

    Returns the event that caused the accelerator gesture condition to be signalled. condition is an object of type accelerator-gesture. [annotate]

    [annotate]

    accelerator-gesture-numeric-argument  condition [Generic Function]
              

    Returns the accumlated numeric argument (maintained by the input editor) at the time the accelerator gesture condition was signalled. condition is an object of type accelerator-gesture. [annotate]

    [annotate]