% -*- Mode: LaTeX; Package: CLIM-USER -*-

\chapter {Extended Stream Input}
\label {extended-input}

CLIM provides a stream-oriented input layer that is implemented on top of the
sheet input architecture.  The basic CLIM input stream protocol is based on the
character input stream protocol proposal submitted to the ANSI Common Lisp
committee by David Gray.  This proposal was not approved by the committee, but
has been implemented by most Lisp vendors.

\section {Basic Input Streams}

CLIM provides an implementation of the basic input stream facilities (described
in more detail in Appendix~\ref{gray-streams}), either by directly using the
underlying Lisp implementation, or by implementing the facilities itself.

\Defclass {standard-input-stream}

This class provides an implementation of the CLIM's basic input stream protocol
based on CLIM's input kernel.  It defines a \cl{handle-event} method for
keystroke events and queues the resulting characters in a per-stream input
buffer.
\Mutable

\Defgeneric {stream-read-char} {stream}

Returns the next character available in the \term{input stream} \arg{stream}, or
\cl{:eof} if the stream is at end-of-file.  If no character is available this
function will wait until one becomes available.

\Defgeneric {stream-unread-char} {stream character}

Places the character \arg{character} back into the \term{input stream}
\arg{stream}'s input buffer.  The next call to \cl{read-char} on \arg{stream}
will return the unread character.  The character supplied must be the most
recent character read from the stream.

\Defgeneric {stream-read-char-no-hang} {stream}

Like \cl{stream-read-char}, except that if no character is available the
function returns \term{false}.

\Defgeneric {stream-peek-char} {stream}

Returns the next character available in the \term{input stream} \arg{stream}.
The character is not removed from the input buffer.  Thus, the same character
will be returned by a subsequent call to \cl{stream-read-char}.

\Defgeneric {stream-listen} {stream}

Returns \term{true} if there is input available on the \term{input stream}
\arg{stream}, \term{false} if not.

\Defgeneric {stream-read-line} {stream}

Reads and returns a string containing a line of text from the \term{input
stream} \arg{stream}, delimited by the \verb+#\Newline+ character.

\Defgeneric {stream-clear-input} {stream}

Clears any buffered input associated with the \term{input stream} \arg{stream},
and returns \term{false}.


\section {Extended Input Streams}

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.

\Defprotoclass {extended-input-stream}

The protocol class for CLIM extended input streams.  This is a subclass of
\cl{input-stream}.
\IfYouWantClass {an} {extended input stream} {extended-input-stream}

\Defun {extended-input-stream-p} {object}

Returns \term{true} if \arg{object} is a CLIM \term{extended input stream},
otherwise returns \term{false}.

\definitarg {:input-buffer}
\definitarg {:pointer}
\Definitarg {:text-cursor}

All subclasses of \cl{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.

\Defclass {standard-extended-input-stream}

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 \cl{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.

\Mutable


\subsection {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.

\Defgeneric {stream-input-buffer} {stream}
\Defgeneric {(setf stream-input-buffer)} {buffer stream}

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 characters and event objects).

\Defgeneric {stream-pointers} {stream}

Returns the list of pointer objects corresponding to the pointing devices of the
port associated with \arg{stream}.
\ReadOnly

\Defgeneric {stream-primary-pointer} {stream}
\Defgeneric {(setf stream-primary-pointer)} {pointer stream}

Returns (or sets) the pointer object corresponding to the primary pointing
device of the console.

{\bf Note:} CLIM currently supports only a single pointer for any port.
Therefore, the length of the list returned by \cl{stream-pointers} will always
be one, and \cl{stream-primary-pointer} will always return an object that is the
only element of that list.

\Defgeneric {stream-pointer-position*} {stream \key pointer}

Returns the current position of the pointing device \arg{pointer} for the
\term{extended input stream} \arg{stream} as two values, the $x$ and $y$
positions in the stream's drawing surface coordinate system.  If \arg{pointer}
is not supplied, it defaults to the \cl{stream-primary-pointer} of the stream.

\Defgeneric {(setf stream-pointer-position*)} {x y stream \key pointer}

Sets the position of the pointing device for the \term{extended input stream}
\arg{stream} to \arg{x} and \arg{y}, which are integers.  \arg{pointer} is as
for \cl{stream-pointer-position*}.


\Defgeneric {stream-set-input-focus} {stream}

Sets the ``input focus'' to the \term{extended input stream} \arg{stream} and
returns the old input focus as its value.

\Defgeneric {stream-restore-input-focus} {stream old-focus}

Restores the ``input focus'' of the \term{extended input stream} \arg{stream} to
\arg{old-focus}.

\Defmacro {with-input-focus} {(stream) \body body}

Temporarily gives the keyboard input focus to the \term{extended input stream}
\arg{stream}.  By default, an application frame gives the input focus to the
window associated with \cl{frame-query-io}.

The \arg{stream} argument is not evaluated, and must be a symbol that is bound
to a stream.  If \arg{stream} is \cl{t}, \cl{*standard-input*} is used.
\arg{body} may have zero or more declarations as its first forms.


\defvar {*input-wait-test*}
\defvar {*input-wait-handler*}
\Defvar {*pointer-button-press-handler*}

These three variables are used to hold the default values for the current input
wait test, wait handler, and pointer button press handler.


\Defun {read-gesture} {\key (stream \cl{*standard-input*})
                            timeout peek-p 
                            (input-wait-test \cl{*input-wait-test*})
                            (input-wait-handler \cl{*input-wait-handler*})
                            (pointer-button-press-handler \cl{*pointer-button-press-handler*})}

Calls \cl{stream-read-gesture} on the \term{extended input stream} \arg{stream}
and all of the other keyword arguments.  These arguments are the same as for
\cl{stream-read-gesture}.

\Defgeneric {stream-read-gesture} {stream
                                   \key timeout peek-p 
                                        (input-wait-test \cl{*input-wait-test*})
                                        (input-wait-handler \cl{*input-wait-handler*})
                                        (pointer-button-press-handler \cl{*pointer-button-press-handler*})}

Returns the next gesture available in the \term{extended input stream}
\arg{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
\cl{*abort-gestures*}), then the \cl{abort-gesture} condition will be signalled.

\cl{stream-read-gesture} works by invoking \cl{stream-input-wait} on
\arg{stream}, \arg{input-wait-test}, and \arg{timeout}, and then processing the
input, if there is any.  \cl{:around} methods on this generic function invoke a
gesture preprocessing mechanism on every gesture.  For a discussion of this
facility, see the Section~\ref{gesture-preproc}.

\arg{timeout} is either \cl{nil} or an integer that specifies the number of
seconds that \cl{stream-read-gesture} will wait for input to become available.
If no input is available, \cl{stream-read-gesture} will return two values,
\cl{nil} and \cl{:timeout}.

If the boolean \arg{peek-p} is \term{true}, then the returned gesture will be
left in the stream's input buffer.

\arg{input-wait-test} is a function of one argument, the stream.  The function
should return \term{true} when there is input to process, otherwise it should
return \term{false}.  This argument will be passed on to \cl{stream-input-wait}.

\arg{input-wait-handler} is a function of one argument, the stream.  It is
called when \cl{stream-input-wait} returns \term{false} (that is, no input is
available).  This option can be used in conjunction with \arg{input-wait-test}
to handle conditions other than keyboard gestures, or to provide some sort of
interactive behavior (such as highlighting applicable presentations).

\arg{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.

\arg{input-wait-test}, \arg{input-wait-handler}, and
\arg{pointer-button-press-handler} have dynamic extent.


\Defgeneric {stream-input-wait} {stream \key timeout input-wait-test}

Waits for input to become available on the \term{extended input stream}
\arg{stream}.  \arg{timeout} and \arg{input-wait-test} are as for
\cl{stream-read-gesture}.


\Defun {unread-gesture} {gesture \key (stream \cl{*standard-input*})}

Calls \cl{stream-unread-gesture} on \arg{gesture} and \arg{stream}.  These
arguments are the same as for \cl{stream-unread-gesture}.

\Defgeneric {stream-unread-gesture} {stream gesture}

Places \arg{gesture} back into the \term{extended input stream} \arg{stream}'s
input buffer.  The next call to \cl{stream-read-gesture} request will return the
unread gesture.  The gesture supplied must be the most recent gesture read from
the stream via \cl{read-gesture}.


\section {Gestures and Gesture Names\label{gesture-names}}

A \concept{gesture} is some sort of input action by the user, such as typing a
character or clicking a pointer button.  A \concept{keyboard gesture} refers to
those gestures that are input by typing something on the keyboard.  A
\concept{pointer gesture} refers to those gestures that are input by doing
something with the pointer, such as clicking a button.

A \concept{gesture name} is a symbol that gives a name to a set of similar
gestures.  Gesture names are used in order to provide a level of abstraction
above raw device events; greater portability can thus be achieved by avoiding
referring directly to platform-dependent constructs, such as character objects
that refer to a particular key on the keyboard.  For example, the \cl{:complete}
gesture is used to name the gesture that causes the \cl{complete-input} complete
the current input string; on Genera, this may correspond to the Complete key on
the keyboard (which generates a \verb+#\Complete+ character), but on a Unix
workstation, it may correspond to some other key.  Another example is
\cl{:select}, which is commonly used to indicate a left button click on the
pointer.

Note that gesture names participate in a one-to-many mapping, that is, a single
gesture name can name a group of physical gestures.  For example, an \cl{:edit}
might include both a pointer button click and a key press.

CLIM uses \term{event} objects to represent user gestures.  Some of the more
comment events are those of the class \cl{pointer-button-event}.  Event objects
store the sheet associated with the event, a timestamp, and the modifier key
state (a quantity that indicates which modifier keys were held down on the
keyboard at the time the event occurred).  Pointer button event objects also
store the pointer object, the button that was clicked on the pointer, the window
the pointer was over and the $x$ and $y$ position within that window.  Keyboard
gestures store the key name.

In some contexts, the object used to represent a user gesture is referred to as
an \concept{gesture object}.  An gesture object might be exactly the same as an
event object, or might contain less information.  For example, for a keyboard
gesture that corresponds to a standard printing character, it may be enough to
represent the gesture object as a character.


\Defmacro {define-gesture-name} {name type gesture-spec \key unique}

Defines a new gesture named by the symbol \arg{name}.  \arg{type} is the type of
gesture being created, and must be one of the symbols described below.
\arg{gesture-spec} specifies the physical gesture that corresponds to the named
gesture; its syntax depends on the value of \arg{type}.
\cl{define-gesture-name} must expand into a call to \cl{add-gesture-name}.

If \arg{unique} is \term{true}, all old gestures named by \arg{name} are first
removed.  \arg{unique} defaults to \cl{nil}.

None of the arguments to \cl{define-gesture-name} is evaluated.

\Defun {add-gesture-name} {name type gesture-spec}

Adds a gesture named by the symbol \arg{name} to the set of gesture names.
\arg{type} is the type of gesture being created, and must be one of the symbols
described below.  \arg{gesture-spec} specifies the physical gesture that
corresponds to the named gesture; its syntax depends on the value of \arg{type}.

When \arg{type} is \cl{:keyboard}, \arg{gesture-spec} is a list of the form
\arg{(key-name . modifier-key-names)}.  \arg{key-name} is the name of a
non-modifier key on the keyboard (see below).  \arg{modifier-key-names} is a
(possibly empty) list of modifier key names (\cl{:shift}, \cl{:control},
\cl{:meta}, \cl{:super}, and \cl{:hyper}).

For the standard Common Lisp characters (the 95 ASCII printing characters
including \verb+#\Space+), \arg{key-name} is the character object itself.  For
the other ``semi-standard'' characters, \arg{key-name} is a keyword symbol
naming the character (\cl{:newline}, \cl{:linefeed}, \cl{:return}, \cl{:tab},
\cl{:backspace}, \cl{:page}, and \cl{:rubout}).  CLIM implementations may extend
the set of key names on a per-port basic, but should choose a port-specific
package.  For example, the Genera port might include \cl{on-genera:help} and
\cl{on-genera:complete}.

The names of the modifier keys have been chosen to be uniform across all
platforms, even though not all platforms will have keys on the keyboard with
these names.  The per-port part of a CLIM implementation must simply choose a
sensible mapping from the modifier key names to the names of the keys on the
keyboard.  For example, a CLIM implementation on the Macintosh might map
\cl{:meta} to the Command shift key, and \cl{:super} to the Option shift key.

When \arg{type} is \cl{:pointer-button}, \cl{:pointer-button-press}, or
\cl{:pointer-button-release}, \arg{gesture-spec} is a list of the form
\arg{(button-name . modifier-key-names)}.  \arg{button} is the name of a pointer
button (\cl{:left}, \cl{:middle}, or \cl{:right}), and \arg{modifier-key-names}
is as above.

CLIM implementations are permitted to have other values of \arg{type} as an
extension, such as \cl{:pointer-motion} or \cl{:timer}.

As an example, the \cl{:edit} gesture name above could be defined as follows
using \cl{define-gesture-name}:

\begin{verbatim}
(define-gesture-name :edit :pointer-button (:left :meta))
(define-gesture-name :edit :keystroke (#\E :control))
\end{verbatim}

\Defun {delete-gesture-name} {name}

Removes the gesture named by the symbol \arg{name}.


\Defun {event-matches-gesture-name-p} {event gesture-name}

Returns \term{true} if the device event \arg{event} ``matches'' the gesture
named by \arg{gesture-name}.

For pointer button events, the event matches the gesture name when the pointer
button from the event matches the name of the pointer button one of the gesture
specifications named by \arg{gesture-name}, and the modifier key state from the
event matches the names of the modifier keys in that same gesture specification.

For keyboard events, the event matches the gesture name when the key name from
the event matches the key name of one of the gesture specifications named by
\arg{gesture-name}, and the modifier key state from the event matches the names
of the modifier keys in that same gesture specification.

\Defun {modifier-state-matches-gesture-name-p} {modifier-state gesture-name}

Returns \term{true} if the modifier key state from the device event \arg{event}
matches the names of the modifier keys in one of the gesture specifications
named by \arg{gesture-name}.

\issue {SWM} {The problem with all of the stuff above is that gesture names are
port-specific, but there is no port argument anywhere.}


\subsection {Standard Gesture Names}

Every CLIM implementation must provide a standard set of gesture names that
correspond to a common set of gestures.  These gesture names must have a
meaningful mapping for every port type.

Here are the required, standard keyboard gesture names:

\begin{itemize}
\item \cl{:abort}---corresponds to gestures that cause the currently running
application to be aborted back to top-level.  On Genera, this will match the
\verb+#\Abort+ character.  On other systems, this may match the event
corresponding to typing {\tt Control-C}.

\item \cl{:clear-input}---corresponds to gestures that cause the current input
buffer to be cleared.  On Genera, this will match the \verb+#\Clear-Input+
character.  On other systems, this may match the event corresponding to typing
{\tt Control-U}.

\item \cl{:complete}---corresponds to the gestures that tell the completion
facility to complete the current input.  On most systems, this will typically
match the \verb+#\Tab+ character.  On Genera, this will match the
\verb+#\Complete+ character as well.

\item \cl{:help}---corresponds to the gestures that tell \cl{accept} and the
completion facility to display a help message.  On most systems, this will
typically match the event corresponding to typing {\tt Control-/}.  On Genera,
this will match the \verb+#\Help+ character as well.

\item \cl{:possibilities}---corresponds to the gestures that tell the completion
facility to display the current set of possible completions.  On most systems,
this will typically match the event corresponding to typing {\tt Control-?}.
\end{itemize}

Here are the required, standard pointer gesture names:

\begin{itemize}
\item{:select}---corresponds to the gesture that is used to ``select'' the
object being pointed to with the pointer.  Typically, this will correspond to
the left button on the pointer.

\item{:describe}---corresponds to the gesture that is used to ``describe'' or
display some sort of documentation on the object being pointed to with the
pointer.  Typically, this will correspond to the middle button on the pointer.

\item{:menu}---corresponds to the gesture that is used to display a menu of all
possible operation on the object being pointed to with the pointer.  Typically,
this will correspond to the right button on the pointer.

\item{:edit}---corresponds to the gesture that is used to ``edit'' the object
being pointed to with the pointer.  Typically, this will correspond to the left
button on the pointer with some modifier key held down (such as the \cl{:meta}
key).

\item{:delete}---corresponds to the gesture that is used to ``delete'' the
object being pointed to with the pointer.  Typically, this will correspond to
the middle button on the pointer with some modifier key held down (such as the
\cl{:shift} key).
\end{itemize}


\section {The Pointer Protocol}

\Defprotoclass {pointer}

The protocol class that corresponds to a pointing device.
\IfYouWantClass {a} {pointer} {pointer}
\Mutable

\Defun {pointerp} {object}

Returns \term{true} if \arg{object} is a \term{pointer}, otherwise returns
\term{false}.

\Definitarg {:port}

The \cl{:port} initarg is used to specify the port with which the pointer is
associated.

\Defclass {standard-pointer}

The instantiable class that implements a pointer.

\Defgeneric {pointer-port} {pointer}

Returns the port with which the \term{pointer} \arg{pointer} is associated.

\defgeneric {pointer-sheet} {pointer}
\Defgeneric {(setf pointer-sheet)} {sheet pointer}

Returns (or sets) the sheet over which the \term{pointer} \arg{pointer} is located.

\Defgeneric {pointer-buttons} {pointer}

Returns the state of the buttons of the \term{pointer} \arg{pointer}.  This is
represented in the same as \cl{pointer-event-button}.

\Defgeneric {pointer-position*} {pointer}

Returns the $x$ and $y$ position of the \term{pointer} \arg{pointer} as two
values.

\Defgeneric {(setf pointer-position*)} {x y pointer}

Sets the $x$ and $y$ position of the \term{pointer} \arg{pointer} to the
specified position.

\defgeneric {pointer-cursor} {pointer}
\Defgeneric {(setf pointer-cursor)} {cursor pointer}

A pointer object usually has a visible cursor associated with it.  These
functions return (or set) the cursor associated with the \term{pointer}
\arg{pointer}.


\section {Pointer Tracking}

\Defmacro {tracking-pointer} {(sheet \key pointer multiple-windows
                                          transformp context-type)
                              \body body}

Provides a general means for running code while following the position of a
pointing device, and monitoring for other input events.  The programmer supplies
code (the clauses in \arg{body}) to be run upon the occurrence of any of the
following types of events:

\begin{itemize}
\item Motion of the pointer

\item Motion of the pointer over a presentation

\item Clicking or releasing a pointer button

\item Clicking of a pointer button on a presentation

\item Keyboard event (typing a character)
\end{itemize}

The \arg{sheet} argument is not evaluated, and must be a symbol that is bound to
an input sheet or stream.  If \arg{sheet} is \cl{t}, \cl{*standard-output*} is
used.  \arg{body} may have zero or more declarations as its first forms.

The \arg{pointer} argument specifies a pointer to track.  It defaults to
the primary pointer for the sheet, \cl{(stream-primary-pointer \arg{sheet})}.

When the boolean \arg{multiple-window} is \term{true}, then the pointer will be
tracked across multiple windows, otherwise is will be tracked only in the window
corresponding to \arg{sheet}.

When the boolean \arg{transformp} is \term{true}, then the coordinates supplied
to the \cl{:pointer-motion} clause will be in the ``user'' coordinate system
rather than in stream coordinates, that is, the medium's transformation will be
applied to the coordinates.

\arg{context-type} is used to specify the presentation type of presentations
that will be ``visible'' to the tracking code.  This is only meaningful when
\arg{sheet} is an output recording stream. \arg{context-type} defaults to
\cl{t}, meaning that all presentations are visible.

The body of \cl{tracking-pointer} consists of a list of clauses.  Each clause is
of the form
\\
\arg{(clause-keyword arglist . clause-body)}
\\
and defines a local function to be run upon occurrence of each type of event.
The possible values for \arg{clause-keyword} and the associated \arg{arglist}
are:

\begin{itemize}
\item {\cl{:presentation} \arg{(\key presentation window x y)}} \\
Defines a clause to run whenever the pointer moves over a presentation of the
desired type.  (See the keyword argument \cl{:context-type} above for a
description of how to specify the desired type.)  In the clause,
\arg{presentation} is bound to the presentation, \arg{window} to the window in
which the motion occurred, and \arg{x} and \arg{y} to the coordinates of the
pointer.  (See the keyword argument \cl{:transformp} above for a description of
the coordinate system in which \arg{x} and \arg{y} are expressed.)

\item {\cl{:pointer-motion} \arg{(\key window x y)}} \\
Defines a clause to run whenever the pointer moves.  In the clause, \arg{window}
is bound to the window in which the motion occurred, and \arg{x} and \arg{y} to
the coordinates of the pointer. (See the keyword argument \cl{:transformp} below
for a description of the coordinate system in which \arg{x} and \arg{y} are
expressed.)

When both \cl{:presentation} and \cl{:pointer-motion} clauses are provided, the
two clauses are mutually exclusive.  The \cl{:presentation} clause will run if
applicable, otherwise the \cl{:pointer-motion} clause will run.

\item {\cl{:keyboard} \arg{(\key gesture)}} \\
Defines a clause to run whenever a character is typed on the keyboard.  In the
clause, \arg{gesture} is bound to the keyboard gesture corresponding to the
character typed.

\item {\cl{:presentation-button-press} \arg{(\key presentation event x y)}} \\
Defines a clause to run whenever the pointer button is pressed while the pointer
is over a presentation of the desired type. (See the keyword argument
\cl{:context-type} below for a description of how to specify the desired type.)
In the clause, \arg{presentation} is bound to the presentation, and \arg{event}
to the pointer button press event.  (The window and the stream coordinates of
the pointer are part of \arg{event}.)

\arg{x} and \arg{y} are the transformed $x$ and $y$ positions of the pointer.
These will be different from \cl{pointer-event-x} and \cl{pointer-event-y} if
the user transformation is not the identity transformation.

\item {\cl{:pointer-button-press} \arg{(\key event x y)}} \\
Defines a clause to run whenever a pointer button is pressed. In the clause,
\arg{event} is bound to the pointer button press event. (The window and the
coordinates of the pointer are part of \arg{event}.)

When both \cl{:presentation-button-press} and \cl{:pointer-button-press}
clauses are provided, the two clauses are mutually exclusive. The
\cl{:presentation-button-press} clause will run if applicable, otherwise the
\cl{:pointer-button-press} clause will run.

\arg{x} and \arg{y} are the transformed $x$ and $y$ positions of the pointer.
These will be different from \cl{pointer-event-x} and \cl{pointer-event-y} if
the user transformation is not the identity transformation.

\item {\cl{:pointer-button-release} \arg{(\key event x y)}} \\
Defines a clause to run whenever a pointer button is released. In the clause,
\arg{event} is bound to the pointer button release event. (The window and the
coordinates of the pointer are part of \arg{event}.)

\arg{x} and \arg{y} are the transformed $x$ and $y$ positions of the pointer.
These will be different from \cl{pointer-event-x} and \cl{pointer-event-y} if
the user transformation is not the identity transformation.
\end{itemize}


\Defgeneric {drag-output-record} {stream output-record
                                  \key repaint erase feedback finish-on-release}

Enters an interaction mode in which the user moves the pointer and
\arg{output-record} ``follows'' the pointer by being dragged on the \term{output
recording stream} \arg{stream}.  By default, the dragging is accomplished by
erasing the output record from its previous position and redrawing at the new
position.  \arg{output-record} remains in the output history of \arg{stream} at
its final position.

The returned values are the final $x$ and $y$ position of the pointer.

The boolean \arg{repaint} allows the programmer to control the appearance of
windows as the pointer is dragged.  If \arg{repaint} is \term{true} (the
default), displayed contents of windows are not disturbed as the output record
is dragged over them (that is, those regions of the screen are repainted).  If
it is \term{false}, then no repainting is done as the output record is dragged.

\arg{erase} allows the programmer to identify a function that will be called to
erase the output record as it is dragged.  It must be a function of two
arguments, the output record to erase and the stream; it has dynamic extent.
The default is \cl{erase-output-record}.

\arg{feedback} allows the programmer to identify a ``feedback'' function.
\arg{feedback} must be a is a function of seven arguments: the output record,
the stream, the initial $x$ and $y$ position of the pointer, the current $x$ and
$y$ position of the pointer, and a drawing argument (either \cl{:erase} or
\cl{:draw}).  It has dynamic extent.  The default is \cl{nil}, meaning that the
feedback behavior will be for the output record to track the pointer.  (The
\arg{feedback} argument is used when the programmer desires more complex
feedback behavior, such as drawing a ``rubber band'' line as the user moves the
mouse.)  Note that if \arg{feedback} is supplied, \arg{erase} is ignored.

If the boolean \arg{finish-on-release} is \term{false} (the default),
\cl{drag-output-record} is exited when the user presses a pointer button.  When
it is \term{true}, \cl{drag-output-record} is exited when the user releases the
pointer button currently being held down.

\Defmacro {dragging-output} {(\optional stream \key repaint finish-on-release)
                             \body body}

Evaluates \arg{body} inside of \cl{with-output-to-output-record} to produce an
output record for the stream \arg{stream}, and then invokes
\cl{drag-output-record} on the record in order to drag the output.  The output
record is not inserted into \arg{stream}'s output history.

The returned values are the final $x$ and $y$ position of the pointer.

The \arg{stream} argument is not evaluated, and must be a symbol that is bound
to an \term{output recording stream} stream.  If \arg{stream} is \cl{t} (the
default), \cl{*standard-output*} is used.  \arg{body} may have zero or more
declarations as its first forms.

\arg{repaint} and \arg{finish-on-release} are as for \cl{drag-output-record}.


\section {Gesture Preprocessing\label{gesture-preproc}}

Every gesture that goes through \cl{stream-read-gesture} gets processed before
it is returned.  This allows applications to intercept gestures and alter the
flow of control.  Gesture processing is done via a gesture table that associates
each gesture with a function of two arguments, \arg{stream} and \arg{gesture},
which is applied when the gesture is read.

\issue {SWM} {So what is ``gesture preprocessing'' anyway?  It should surely
specialize on the stream, or the application frame, or both.}

\defun {gesture-processing-handler} {gesture}
\Defun {(setf gesture-processing-handler)} {gesture}

Manipulate the gesture processing handler for a particular gesture.  All pointer
button presses are considered equivalent at this layer; to modify the handler
for pointer button presses, specify \cl{:pointer-button-press} as the
\arg{gesture}.  The default values for the handlers for all gestures is
\cl{nil}, meaning there is no handler.  The presentation subsystem could be
implemented by installing \cl{input-context-button-press-handler} as the handler
for pointer button presses.