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

\chapter {Overview of Window Facilities}

\section {Introduction}

A central notion in organizing graphical user interfaces is allocating screen
regions to particular tasks and recursively subdividing these regions into
subregions.  The layer of CLIM known as Silica defines an extensible framework
for constructing, using, and managing such \concept{hierarchies of interactive
regions}.  This framework allows uniform treatment of the following things:

\begin{itemize}
\item Window objects like those in X or NeWS.

\item Lightweight gadgets typical of toolkit layers.

\item Structured graphics like output records and an application's presentation
objects.

\item Objects that act as Lisp handles for windows or gadgets implemented in a
different language (such as OpenLook gadgets implemented in C).
\end{itemize}

From the perspective of most CLIM users, Silica plays the role of a window
system.  However Silica will usually utilize the services of a window system
platform to provide efficient windowing, input, and output facilities.  In this
specification, such window system platforms will be referred to as host window
or display servers.

The fundamental abstraction defined by Silica is called a \concept{sheet}.  A
sheet can participate in a relationship called a \concept{windowing
relationship}.  This relationship is one in which one sheet called the
\concept{parent} provides space to a number of other sheets called
\concept{children}.  Support for establishing and maintaining this kind of
relationship is the essence of what window systems provide.  At any point in
time, Silica allows a sheet to be a child in one relationship called its
\concept{youth windowing relationship} and a parent in another relationship
called its \concept{adult windowing relationship}.

Programmers can manipulate unrooted hierarchies of sheets (those without a
connection to any particular display server).  However, a sheet hierarchy must
be attached to a display server to make it visible.  \concept{Ports} and
\concept{grafts} provide the functionality for managing this capability.  A
\term{port} is an abstract connection to a display service that is responsible
for managing host display server resources and for processing input events
received from the host display server.  A \term{graft} is a special kind of
sheet that represents a host window, typically a root window (that is, a
screen-level window).  A sheet is attached to a display by making it a child of
a graft, which represents an appropriate host window.  The sheet will then
appear to be a child of that host window.  So, a sheet is put onto a particular
screen by making it a child of an appropriate graft and enabling it.  Ports and
grafts are described in detail in Chapter~\ref{ports-and-grafts}.

\issue {RSL} {An open issue in Silica's design is allowing a sheet to participate
in multiple youth relationships.}

\issue {SWM} {Allowing a sheet to have multiple parents at different times is
necessary for allowing the same pane to appear in multiple layouts of a frame.
We need to resolve this.}


\section {Properties of Sheets}

Sheets have the following properties:

\begin{description}
\item [A coordinate system] Provides the ability to refer to locations in a
sheet's abstract plane.

\item [A region] Defines an area within a sheet's coordinate system that
indicates the area of interest within the plane, that is, a clipping region for
output and input.  This typically corresponds to the visible region of the sheet
on the display.

\item [A parent] A sheet that is the parent in a windowing relationship in which
this sheet is a child.

\item [Children] An ordered set of sheets that are each a child in a windowing
relationship in which this sheet is a parent.  The ordering of the set
corresponds to the stacking order of the sheets.  Not all sheets have children.

\item [A transformation] Determines how points in this sheet's coordinate system
are mapped into points in its parents.

\item [An enabled flag] Indicates whether the sheet is currently actively
participating in the windowing relationship with its parent and siblings.

\item [An event handler] A procedure invoked when the display server wishes to
inform CLIM of external events.

\item [Output state] A set of values used when CLIM causes graphical or textual
output to appear on the display.  This state is often represented by a medium.
\end{description}


\section {Sheet Protocols}

A sheet is a participant in a number of protocols.  Every sheet must provide
methods for the generic functions that make up these protocols.  These protocols
are:

\begin{description}
\item [The windowing protocol] Describes the relationships between the sheet and
its parent and children (and, by extension, all of its ancestors and
descendants).

\item [The input protocol] Provides the event handler for a sheet.  Events may
be handled synchronously, asynchronously, or not at all.

\item [The output protocol] Provides graphical and textual output, and manages
descriptive output state such as color, transformation, and clipping.

\item [The repaint protocol] Invoked by the event handler and by user programs
to ensure that the output appearing on the display device appears as the program
expects it to appear.

\item [The notification protocol] Invoked by the event handler and user programs
to ensure that CLIM's representation of window system information is equivalent
to the display server's.
\end{description}

These protocols may be handled directly by a sheet, queued for later processing
by some other agent, or passed on to a delegate sheet for further processing.


\section {Sample Silica Program}

\begin{verbatim}
(defun test-silica ()
  (let* ((sheet
          (make-standard-sheet :parent (find-graft) 
                               :transformation (make-translation 100 100)
                               :region (make-rectangle 0 0 200 200 )))
         (w (bounding-rectangle-width sheet))
         (h (bounding-rectangle-height sheet))
         (x1 (/ w 4))
         (y1 (/ h 4))
         (x2 (* 3 (/ w 4)))
         (y2 (* 3 (/ h 4))))
    (enable-sheet sheet t)
    (draw-line sheet (make-point x1 y1) (make-point x1 y2))
    (draw-line sheet (make-point x1 y2) (make-point x2 y2))
    (draw-line sheet (make-point x2 y2) (make-point x2 y1))
    (draw-line sheet (make-point x2 y1) (make-point x1 y1))
    (draw-line* sheet x1 y1 x2 y2)
    (draw-line* sheet x1 y2 x2 y1)
    (output-finish sheet)
    (sleep 1)
    (disable-sheet sheet)
    (sheet-disown-child (sheet-parent sheet) sheet)))
\end{verbatim}

\issue {York} {This needs to be a set of more compelling examples.}


\chapter {Properties of Sheets}
\label {sheet-properties}

\Defprotoclass {sheet}

The protocol class that corresponds to a sheet, a subclass of
\cl{bounding-rectangle}.  This and the next chapter describe all of the sheet
protocols.
\IfYouWantClass {a} {sheet} {sheet}

All of the subclasses of \cl{sheet} are mutable.

\Defun {sheetp} {object}

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


\section {Relationships Between Sheets}

Sheets are arranged in a tree-structured, acyclic, top-down hierarchy.  Thus, in
general, a sheet has one parent (or no parent) and zero or more children.  A
sheet may have zero or more siblings (that is, other sheets that share the same
parent).  In order to describe the relationships between sheets, we need to
define some terms.

\begin{description}
\item [Adopted] A sheet is said to be \concept{adopted} if it has a parent.  A
sheet becomes the parent of another sheet by adopting that sheet.

\item [Disowned] A sheet is said to be \concept{disowned} if it does not have a
parent.  A sheet ceases to be a child of another sheet by being disowned.

\item [Grafted] A sheet is said to be \concept{grafted} when it is part of a
sheet hierarchy whose highest ancestor is a graft.  In this case, the sheet may
be visible on a particular window server.

\item [Degrafted] A sheet is said to be \concept{degrafted} when it is part of a
sheet hierarchy that cannot possibly be visible on a server, that is, the
highest ancestor is not a graft.

\item [Enabled] A sheet is said to be \concept{enabled} when it is actively
participating in the windowing relationship with its parent.  If a sheet is
enabled and grafted, and all its ancestors are enabled (they are grafted by
definition), then the sheet will be visible if it occupies a portion of the
graft region that isn't clipped by its ancestors or ancestor's siblings.

\item [Disabled] The opposite of enabled is \concept{disabled}.
\end{description}


\subsection {Sheet Relationship Functions}

The generic functions in this section comprise the sheet protocol.  All sheet
objects must implement methods for each of these generic functions.

\issue {SWM} {Is the above statement accurate?}

\Defgeneric {sheet-parent} {sheet} 

Returns the parent of the \term{sheet} \arg{sheet}, or \cl{nil} if the sheet has
no parent.

\Defgeneric {sheet-children} {sheet}

Returns a list of sheets that are the children of the \term{sheet} \arg{sheet}.
Some sheet classes support only a single child; in this case, the result of
\cl{sheet-children} will be a list of one element.
\ReadOnly

\Defgeneric {sheet-adopt-child} {sheet child}

Adds the child sheet \arg{child} to the set of children of the \term{sheet}
\arg{sheet}, and makes the \arg{sheet} the child's parent.  If \arg{child}
already has a parent, the \cl{sheet-already-has-parent} error will be signalled.

Some sheet classes support only a single child.  For such sheets, attempting to
adopt more than a single child will cause the \cl{sheet-supports-only-one-child}
error to be signalled.

\Defgeneric {sheet-disown-child} {sheet child}

Removes the child sheet \arg{child} from the set of children of the \term{sheet}
\arg{sheet}, and makes the parent of the child be \cl{nil}.  If \arg{child} is
not actually a child of \arg{sheet}, the \cl{sheet-is-not-child} error will be
signalled.

\Defgeneric {sheet-siblings} {sheet}

Returns a list of all of the siblings of the \term{sheet} \arg{sheet}.  The
sibling are all of the children of \arg{sheet}'s parent excluding \arg{sheet}
itself.
\FreshOutputs

\Defgeneric {sheet-enabled-children} {sheet}

Returns a list of those children of the \term{sheet} \arg{sheet} that are enabled.
\FreshOutputs

\Defgeneric {sheet-ancestor-p} {sheet putative-ancestor}

Returns \term{true} if the the \term{sheet} \arg{putative-ancestor} is in fact
an ancestor of the \term{sheet} \arg{sheet}, otherwise returns \term{false}.

\defgeneric {raise-sheet} {sheet}
\Defgeneric {bury-sheet}  {sheet}

These functions reorder the children of a sheet by raising the \term{sheet}
\arg{sheet} to the top or burying it at the bottom.  Raising a sheet puts it at
the beginning of the ordering; burying it puts it at the end.  If sheets
overlap, the one that appears ``on top'' on the display device is earlier in the
ordering than the one underneath.

This may change which parts of which sheets are visible on the display device.

\Defgeneric {reorder-sheets} {sheet new-ordering}

Reorders the children of the \term{sheet} \arg{sheet} to have the new ordering
specified by \arg{new-ordering}.  \arg{new-ordering} is an ordered list of the
child sheets; elements at the front of \arg{new-ordering} are ``on top'' of
elements at the rear.

If \arg{new-ordering} does not contain all of the children of \arg{sheet}, the
\cl{sheet-ordering-underspecified} error will be signalled.  If
\arg{new-ordering} contains a sheet that is not a child of \arg{sheet}, the
\cl{sheet-is-not-child} error will be signalled.

\Defgeneric {sheet-enabled-p} {sheet}

Returns \term{true} if the the \term{sheet} \arg{sheet} is enabled by its
parent, otherwise returns \term{false}.  Note that all of a sheet's ancestors
must be enabled before the sheet is viewable.

\Defgeneric {(setf sheet-enabled-p)} {enabled-p sheet}

When \arg{enabled-p} is \term{true}, this enables the the \term{sheet}
\arg{sheet}.  When \arg{enabled-p} is \term{false}, this disables the sheet.

Note that a sheet is not visible unless it and all of its ancestors are enabled.


\Defgeneric {sheet-viewable-p} {sheet}

Returns \term{true} if the \term{sheet} \arg{sheet} and all its ancestors are
enabled, and if one of its ancestors is a graft.  See
Chapter~\ref{ports-and-grafts} for further information.

\Defgeneric {sheet-occluding-sheets} {sheet child}

Returns a list of the \term{sheet} \arg{child}'s siblings that occlude part or
all of the region of the \arg{child}.  In general, these are the siblings that
are enabled and appear earlier in the \term{sheet} \arg{sheet}'s children.  If
\arg{sheet} does not permit overlapping among its children,
\cl{sheet-occluding-sheets} will return \cl{nil}.

\FreshOutputs


\subsection {Sheet Genealogy Classes}

Different ``mixin'' classes are provided that implement the relationship protocol.

\Defclass {sheet-leaf-mixin}

This class is mixed into sheet classes that will never have children.

\Defclass {sheet-single-child-mixin}

This class is mixed into sheet classes that have at most a single child.

\Defclass {sheet-multiple-child-mixin}

This class is mixed into sheet classes that may have zero or more children.


\section {Sheet Geometry}

Every sheet has a region and a coordinate system.  A sheet's region refers to
its position and extent on the display device, and is represented by some sort
of a region object, frequently a rectangle.  A sheet's coordinate system is
represented by a coordinate transformation that converts coordinates in its
coordinate system to coordinates in its parent's coordinate system.

\subsection {Sheet Geometry Functions}

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

Returns a transformation that converts coordinates in the \term{sheet}
\arg{sheet}'s coordinate system into coordinates in its parent's coordinate
system.  Using \cl{setf} on this accessor will modify the sheet's coordinate
system, including moving its region in its parent's coordinate system.

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

Returns a region object that represents the set of points to which the
\term{sheet} \arg{sheet} refers.  The region is in the sheet's coordinate
system.  Using \cl{setf} on this accessor modifies the sheet's region.

\issue {SWM} {Aren't there some notification functions that get called when the
sheet's region and transformation are changed?}

\issue {RSL} {I'm not convinced I like this business of requesting a change by
modifying an accessor.  It would actually be better to have a \cl{request-}
function, so it would be clear that there might be some delay before the region
or transformation was modified.}

\issue {RSL} {To reshape and move a region, you generally have to manipulate
both of the above.  Maybe there should be a single function that takes either
or both of a new transformation or region?  Maybe region coordinates should be
expressed in parents' coordinates, since that's easier to set only one?}

\issue {RSL} {Using \cl{setf} on mirrored sheets actually requests that the
server move/resize the sheet; the accessor will continue to return the old value
until the notification comes in saying that the mirror has been moved.}


\Defgeneric {map-sheet-point*-to-parent} {sheet x y}

Applies the \term{sheet} \arg{sheet}'s transformation to the point $(x,y)$,
returning the coordinates of that point in \arg{sheet}'s parent's coordinate
system.

\Defgeneric {map-sheet-point*-to-child} {sheet x y}

Applies the inverse of the \term{sheet} \arg{sheet}'s transformation to the
point $(x,y)$ (represented in \arg{sheet}'s parent's coordinate system),
returning the coordinates of that same point in \arg{sheet} coordinate system.

\Defgeneric {map-sheet-bounding-rectangle*-to-parent} {sheet x1 y1 x2 y2} 

Applies the \term{sheet} \arg{sheet}'s transformation to the bounding rectangle
specified by the corner points $(x1,y1)$ and $(x2,y2)$, returning the bounding
rectangle of the transformed region as four values, \arg{min-x}, \arg{min-y},
\arg{max-x}, and \arg{max-y}.  The arguments \arg{x1}, \arg{y1}, \arg{x2}, and
\arg{y1} are canonicalized in the same way as for \cl{make-bounding-rectangle}.

\Defgeneric {map-sheet-bounding-rectangle*-to-child} {sheet x1 y1 x2 y2}

Applies the inverse of the \term{sheet} \arg{sheet}'s transformation to the
bounding rectangle delimited by the corner points $(x1,y1)$ and $(x2,y2)$
(represented in \arg{sheet}'s parent's coordinate system), returning the
bounding rectangle of the transformed region as four values, \arg{min-x},
\arg{min-y}, \arg{max-x}, and \arg{max-y}.  The arguments \arg{x1}, \arg{y1},
\arg{x2}, and \arg{y1} are canonicalized in the same way as for
\cl{make-bounding-rectangle}.


\defgeneric {child-containing-point}  {sheet point}
\Defgeneric {child-containing-point*} {sheet x y}

Returns the topmost (earliest) enabled child of the \term{sheet} \arg{sheet}
whose region contains the \term{point} \arg{point} (or the position $(x,y)$).
The point is expressed in \arg{sheet}'s coordinate system.

\issue {SWM} {What does ``earliest'' mean exactly in this context?  And does it
return the earliest child, or the earliest descendant?  And does it return an
enabled sheet, or any sheet?}

\defgeneric {children-overlapping-region}     {sheet region}
\Defgeneric {children-overlapping-rectangle*} {sheet x1 y1 x2 y2}

Returns the list of enabled children of the \term{sheet} \arg{sheet} whose
region overlaps the \term{region} \arg{region}.
\cl{children-overlapping-rectangle*} is a special case of
\cl{children-overlapping-region} in which the region is a bounding rectangle
whose corner points are $(x1,y1)$ and $(x2,y2)$.  The region is expressed in
\arg{sheet}'s coordinate system.
\FreshOutputs


\Defgeneric {sheet-delta-transformation} {sheet ancestor}

Returns a transformation that is the composition of all of the sheet
transformations between the \term{sheets} \arg{sheet} and \arg{ancestor}.  If
\arg{ancestor} is \cl{nil}, \cl{sheet-delta-transformation} will return the
transformation to the root of the sheet hierarchy.  If \arg{ancestor} is not an
ancestor of sheet, the \cl{sheet-is-not-ancestor} error will be signalled.

The computation of the delta transformation is likely to be cached.

\issue {SWM} {This used to be called \cl{fetch-delta-transformation}, right?}

\Defgeneric {sheet-allocated-region} {sheet child}

Returns the visible region of the \term{sheet} \arg{child} in the \term{sheet}
\arg{sheet}'s coordinate system.  If \arg{child} is occluded by any of its
siblings, those siblings' regions are subtracted (using \cl{region-difference})
from \arg{child}'s actual region.


\subsection {Sheet Geometry Classes}

Each of the following implements the sheet geometry protocol in a different
manner, according to the sheet's requirements.

\Defclass {sheet-identity-transformation-mixin}

This class is mixed into sheet classes whose coordinate system is identical to
that of its parent.

\Defclass {sheet-translation-mixin}

This class is mixed into sheet classes whose coordinate system is related to
that of its parent by a simple translation.

\Defclass {sheet-y-inverting-transformation-mixin}

This class is mixed into sheet classes whose coordinate system is related to
that of its parent by inverting the $y$ coordinate system, and optionally
translating by some amount in $x$ and $y$.

\Defclass {sheet-transformation-mixin}

This class is mixed into sheet classes whose coordinate system is related to
that of its parent by an arbitrary affine transformation.


\section {Creating Sheets}

\issue {RSL} {Still needs fleshing out.  I'm trying to eliminate contracts from
this entire chapter, so I need to figure out how much we want to say here.  It
may be sufficient to have a function \cl{make-sheet} that takes a class object
and some initialization keywords, and perhaps some interface to the runtime
dynamic class stuff.}

\Defun {make-sheet} {???}
\Defun {make-standard-sheet} {???}


\chapter {Sheet Protocols}
\label {sheet-protocols}

\section {Input Protocol}

CLIM's windowing substrate provides an input architecture and standard
functionality for notifying clients of input that is distributed to their
sheets.  Input includes such events as the pointer entering and exiting sheets,
pointer motion (whose granularity is defined by performance limitations), and
pointer button and keyboard events.  At this level, input is represented as
\term{event} objects.

Sheets either participate fully in the input protocol or are mute for input.  If
any functions in the input protocol are called on a sheet that is mute for
input, the \cl{sheet-is-mute-for-input} error will be signalled.

Input is processed on a per-port basis by the function \cl{process-next-event}.
In multiprocessing environments, a process that calls \cl{process-next-event} in a
loop is created for each port.  In single-process Lisps, \cl{process-next-event}
is called whenever the user would go blocked for input.

\cl{process-next-event} has three main tasks when it receives an event.  First,
it must determine to which \concept{client} the event is addressed.  Typically,
the client is a sheet, but there are other special-purpose clients to which
events can also be dispatched.  Next, \cl{process-next-event} formats the event
into a standard format, and finally it \concept{distributes} the event to the
client.  A client may then either handle the event synchronously, or it may
queue it for later handling by another process.

Input events can be broadly categorized into \concept{pointer events} and
\concept{keyboard events}.  By default, pointer events are dispatched to the
lowest sheet in the hierarchy whose region contains the location of the pointer.
Keyboard events are dispatched to the port's keyboard input focus; the accessor
\cl{port-keyboard-input-focus} contains the event client that receives the
port's keyboard events.

\issue {SWM} {Can someone explain to me the exact distinction between
dispatching, distributing, and processing?}


\subsection {Input Protocol Functions}

\issue {SWM} {Do we want to advertise \cl{sheet-event-queue}?  Probably not.}

\Defgeneric {process-next-event} {port \key wait-function timeout}

This function provides a standard interface for one pass through a port's event
processing loop.  \arg{wait-function} is either \cl{nil} or a function of no
arguments that acts as a predicate; it has dynamic extent.  The predicate should
wait until one of three conditions occurs:

\begin{itemize}
\item If an event if received and processed, the predicate should return
\term{true}.

\item If a timeout occurs, the predicate should return \term{false}.

\item If the wait function returns \term{true}, the predicate should return the
two values \term{false} and \cl{:timeout}.
\end{itemize}

A port implementation must provide a method for this function that reads the
next window server-specific device event, blocking if necessary, and then
invokes the event distributor.

\defgeneric {port-keyboard-input-focus} {port}
\Defgeneric {(setf port-keyboard-input-focus)} {focus port}

Returns the client to which keyboard events are to be dispatched.

\issue {RSL} {Name of this accessor?  Maybe it should just be
\cl{keyboard-input-focus}.  We might like to have this object be a frame, which
in turn might also want to have a per-frame focus sheet or pane or mosaic or
whatever.}

\Defgeneric {distribute-event} {port event}

The \arg{event} is distributed to the \arg{port}'s proper client.  In general,
this will be the keyboard input focus for keyboard events, and the lowest sheet
under the pointer for pointer events.

\issue {RSL} {Do we just want to call this function \cl{dispatch-event} and have
it called on the port first?}

\Defgeneric {dispatch-event} {client event}

This function is called by \cl{process-next-event} to inform a client about an
event of interest.  It is invoked synchronously by whatever process called
\cl{process-next-event}, so many methods for this function will simply queue the
event for later handling.  Certain classes of clients and events may cause this
function immediately to call either \cl{queue-event} or \cl{handle-event}, or to
ignore the event entirely.

\issue {SWM} {What exactly is a ``client''?  It says above that it can be
something other than a sheet, but what are those other things?}

\Defgeneric {queue-event} {client event}

Places the event \arg{event} into the queue of events for the client \arg{client}.

\Defgeneric {handle-event} {client event}

Implements the client's policy with respect to the event.  For example, if the
programmer wishes to highlight a sheet in response to an event that informs it
that the pointer has entered its territory, there would be a method to carry out
the policy that specializes the appropriate sheet and event classes.

In addition to \cl{queue-event}, the queued input protocol handles the following
generic functions:

\issue {RSL} {These names are subject to change.}

\Defgeneric {event-read} {client}

Takes the next event out of the queue of events for this client.

\Defgeneric {event-read-no-hang} {client}

Takes the next event out of the queue of events for this client.  It returns
\cl{nil} if there are no events in the queue.

\Defgeneric {event-peek} {client \optional event-type}

Returns the next event in the queue without removing it from the queue.  If
\arg{event-type} is supplied, events that are not of that type are first
removed and discarded.

\Defgeneric {event-unread} {client event}

Places the \arg{event} at the head of the \arg{client}'s event queue, so as to
be the next event read.

\Defgeneric {event-listen} {client}

Returns \term{true} if there are any events queued for \arg{client}, otherwise
returns \term{false}.


\subsection {Input Protocol Classes}

\issue {RSL} {Maybe these names should be \cl{-client-} and not \cl{-sheet-}?
For example, \cl{standard-input-client} instead of \cl{standard-sheet-input-mixin}?}

Most classes of sheets will have one of the following input protocol classes
mixed in.  Of course, a sheet can always have a specialized method for a
specific class of event that will override the default.  For example, a sheet
may need to have only pointer click events dispatched to itself, and may
delegate all other events to some other input client.  Such a sheet should have
\cl{delegate-sheet-input-mixin} as a superclass, and have a more specific method
for \cl{dispatch-event} on its class and \cl{click-event}.

\Defclass {standard-sheet-input-mixin}

This class of sheet provides a method for \cl{dispatch-event} that calls
\cl{queue-event} on each device event.  Note that configuration events invoke
\cl{handle-event} immediately.

\Defclass {immediate-sheet-input-mixin}

\issue {RSL} {Is this a good name?  RWK proposed this.  Anybody have other
opinions?}

This class of sheet provides a method for \cl{dispatch-event} that calls
\cl{handle-event} immediately for all events.

\Defclass {mute-sheet-input-mixin}

\Defclass {delegate-sheet-input-mixin}

\issue {RSL} {Is this a good name?}

This class of sheet provides a method for \cl{dispatch-event} that calls
\cl{dispatch-event} on a designated substitute and the event.  The
initialization argument \cl{:delegate} or the accessor {delegate-sheet-delegate}
may be used to set the recipient of dispatched events.

\issue {SWM} {What is a ``substitute'' and how do you ``designate'' it?  Is the
substitute what \cl{delegate-sheet-delegate} returns?  Does't this want an
initarg for the substitute?}

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

This may be set to another recipient of events dispatched to a sheet of class
\cl{delegate-sheet-input-mixin}.  If the delegate is \cl{nil}, events are
discarded.


\section {Standard Device Events}

An \concept{event} is a CLIM object that represents some sort of user gesture
(such as moving the pointer or pressing a key on the keyboard) or that
corresponds to some sort of notification from the display server.  Event objects
store such things as the sheet associated with the event, the $x$ and $y$
bposition of the pointer within that sheet, the key name or character
corresponding to a key on the keyboard, and so forth.

Figure~\ref{event-hier} shows all the event classes.

\begin{figure}
\hrule
\begin{tabbing}
XX\=XX\=XX\=XX\=XX\=XX\=  \kill
\cl{event} \\
\>\cl{device-event}          \\
\>\>\cl{keyboard-event}      \\
\>\>\>\cl{key-press-event}   \\
\>\>\>\cl{key-release-event} \\
\>\>\cl{pointer-event}       \\
\>\>\>\cl{pointer-button-event} \\
\>\>\>\>\cl{pointer-button-press-event}   \\
\>\>\>\>\cl{pointer-button-release-event} \\
\>\>\>\>\cl{pointer-button-hold-event}    \\
\>\>\>\cl{pointer-motion-event}  \\
\>\>\>\>\cl{pointer-enter-event} \\
\>\>\>\>\cl{pointer-exit-event}  \\
\>\cl{window-event} \\
\>\>\cl{window-configuration-event} \\
\>\>\cl{window-repaint-event}       \\
\>\cl{timer-event} \\
\end{tabbing}
\caption{\label{event-hier} CLIM event classes.  All classes that appear
at a given indentation are subclasses of the class that appears above and at a
lesser indentation.} 
\vspace{2pc}
\hrule
\end{figure}

\Defprotoclass {event}

The protocol class that corresponds to any sort of ``event''.
\IfYouWantClass {an} {event} {event}

All of the event classes are immutable.

\Defun {eventp} {object}

Returns \term{true} if \arg{object} is an \term{event}, otherwise returns
\term{false}.

\Definitarg {:timestamp}

All subclasses of \cl{event} must take a \cl{:timestamp} initarg, which is used
to specify the timestamp for the event.

\Defgeneric {event-timestamp} {event}

Returns an integer that is a monotonically increasing timestamp for the the
\term{event} \arg{event}.  The timestamp must have at least as many bits of
precision as a fixnum.

\Defgeneric {event-type} {event}

For the \term{event} \arg{event}, returns a keyword with the same name as the
class name, except stripped of the ``-event'' ending.  For example, the keyword
\cl{:key-press} is returned by \cl{event-type} for an event whose class is
\cl{key-press-event}.

All event classes must implement methods for \cl{event-type} and
\cl{event-timestamp}.


\defclass {device-event}
\definitarg {:sheet}
\Definitarg {:modifier-key-state}

The class that corresponds to any sort of device event.  This is a subclass of
\cl{event}.

All subclasses of \cl{device-event} must take the \cl{:sheet} and
\cl{:modifier-key-state} initargs, which are used to specify the sheet and
modifier key state components for the event.

\Defgeneric {event-sheet} {device-event}

Returns the sheet associated with the event \arg{device-event}.

\Defgeneric {event-modifier-key-state} {device-event}

Returns a value that encodes the state of all the modifier keys on the keyboard.
This will be a mask consisting of the \cl{logior} of \cl{+shift-key+},
\cl{+control-key+}, \cl{+meta-key+}, \cl{+super-key+}, and \cl{+hyper-key+}.

All device event classes must implement methods for \cl{event-sheet} and
\cl{event-modifier-key-state}.


\defclass {keyboard-event}
\Definitarg {:key-name}

The class that corresponds to any sort of keyboard event.  This is a subclass of
\cl{device-event}.

All subclasses of \cl{keyboard-event} must take the \cl{:key-name} initarg,
which is used to specify the key name component for the event.

\Defgeneric {keyboard-event-key-name} {keyboard-event}

Returns the name of the key that was pressed or released in a keyboard event.
This will be a symbol whose value is port-specific.  Key names corresponding to
the set of ``standard'' characters (such as the alphanumerics) will be a symbol
in the keyword package.

\Defgeneric {keyboard-event-character} {keyboard-event}

Returns the character associated with the event \arg{keyboard-event}, if there
is any.

All keyboard event classes must implement methods for
\cl{keyboard-event-key-name} and \cl{keyboard-event-character}.

\defclass {key-press-event}
\Defclass {key-release-event}
 
The classes that correspond to a key press or release event.  This is a subclass
of \cl{keyboard-event}.


\defclass {pointer-event}
\definitarg {:pointer}
\definitarg {:button}
\definitarg {:x}
\Definitarg {:y}
 
The class that corresponds to any sort of pointer event.  This is a subclass of
\cl{device-event}.

All subclasses of \cl{pointer-event} must take the \cl{:pointer}, \cl{:button},
\cl{:x}, and \cl{:y} initargs, which are used to specify the pointer object,
pointer button, and native $x$ and $y$ position of the pointer at the time of
the event.  The sheet's $x$ and $y$ positions are derived from the supplied
native $x$ and $y$ positions and the sheet itself.

\defgeneric {pointer-event-x} {pointer-event}
\Defgeneric {pointer-event-y} {pointer-event}

Returns the $x$ and $y$ position of the pointer at the time the event occurred,
in the coordinate system of the sheet that received the event.  All pointer
events must implement a method for these generic functions.

\defgeneric {pointer-event-native-x} {pointer-event}
\Defgeneric {pointer-event-native-y} {pointer-event}

Returns the $x$ and $y$ position of the pointer at the time the event occurred,
in the pointer's native coordinate system.  All pointer events must implement a
method for these generic functions.

\Defgeneric {pointer-event-pointer} {pointer-event}

Returns the pointer object to which this event refers.

\Defgeneric {pointer-event-button} {pointer-event}

Returns the number of the pointer button that was pressed, which will be
one of \cl{+pointer-left-button+}, \cl{+pointer-middle-button+}, or
\cl{+pointer-right-button+}.

All pointer event classes must implement methods for \cl{pointer-event-x},
\cl{pointer-event-y}, \cl{pointer-event-native-x}, \cl{pointer-event-native-y},
\cl{pointer-event-pointer}, and \cl{pointer-event-button}.

\Defclass {pointer-button-event}
 
The class that corresponds to any sort of pointer button event.  This is a
subclass of \cl{pointer-event}.

\defclass {pointer-button-press-event}
\defclass {pointer-button-release-event}
\Defclass {pointer-button-hold-event}
 
The classes that correspond to a pointer button press, button release, and
click-and-hold events.  These are subclasses of \cl{pointer-button-event}.

\Defclass {pointer-motion-event}
 
The class that corresponds to any sort of pointer motion event.  This is a
subclass of \cl{pointer-event}.

\defclass {pointer-enter-event}
\Defclass {pointer-exit-event}

The classes that correspond to a pointer enter or exit event.  This is a
subclass of \cl{pointer-motion-event}.


\defclass {window-event}
\Definitarg {:region}

The class that corresponds to any sort of windowing event.  This is a subclass
of \cl{device-event}.

All subclasses of \cl{window-event} must take a \cl{:region} initarg, which is
used to specify the damage region associated with the event.

\Defgeneric {window-event-region} {window-event}

Returns the region of the sheet that is affected by a window event.

\Defgeneric {window-event-native-region} {window-event}

Returns the region of the sheet in native coordinates.

\Defgeneric {window-event-mirrored-sheet} {window-event}

Returns the mirrored sheet that is attached to the mirror on which the event
occurred.

All window event classes must implement methods for \cl{window-event-region},
\cl{window-event-native-region}, and \cl{window-event-mirrored-sheet}.

\Defclass {window-configuration-event}

The class that corresponds to a window changing its size or position.  This is
a subclass of \cl{window-event}.

\Defclass {window-repaint-event}

The class that corresponds to a request to repaint the window.  This is a
subclass of \cl{window-event}.


\Defclass {timer-event}

The class that corresponds to a timeout event.  This is a subclass of
\cl{event}.


\defconst {+pointer-left-button+}
\defconst {+pointer-middle-button+}
\Defconst {+pointer-right-button+}

Constants that correspond to the left, middle, and right button on a pointing
device.  \cl{pointer-event-button} will returns one of these three values.

\defconst {+shift-key+}
\defconst {+control-key+}
\defconst {+meta-key+}
\defconst {+super-key+}
\Defconst {+hyper-key+}

Constants that correspond to the shift, control, meta, super, and hyper modifier
keys being held down on the keyboard.  These constants must be powers of 2 so
that they can be combined with \cl{logior} and tested with \cl{logtest}.
\cl{event-modifier-key-state} will return some combination of these values.

Implementations must support at least shift, control, and meta modifiers.
Control and meta might correspond to the control and option or command shift
keys on a Macintosh keyboard, for example.

\Defmacro {key-modifier-state-match-p} {button modifier-state \body clauses}

This macro generates code that will check whether the modifier state
\arg{modifier-state} and the pointer button \arg{button} match all of the
clauses.  \arg{clauses} are implicitly grouped by \cl{and}.  Matching a button
or a modifier means that that the modifier state indicates that the button or
modifier is pressed.

A clause may be one of:

\begin{itemize}
\item A pointer button.  One of \cl{:left}, \cl{:middle} or \cl{:right}.

\item A modifier key.  One of \cl{:shift}, \cl{:control}, \cl{:meta},
\cl{:super} or \cl{:hyper}.

\item \cl{(and [\arg{clause}]+)}

\item \cl{(or [\arg{clause}]+)}

\item \cl{(not \arg{clause})}
\end{itemize}


\section {Output Protocol}

The output protocol is concerned with the appearance of displayed output on the
window associated with a sheet.

Sheets either participate fully in the output protocol or are mute for output.
If any functions in the output protocol are called on a sheet that is mute for
output, the \cl{sheet-is-mute-for-output} error will be signalled.


\subsection {Output Properties}

Each sheet retains some output state that logically describes how output is to
be rendered on its window.  Such information as the foreground and background
ink, line thickness, and transformation to be used during drawing are provided
by this state.  This state may be stored in a \concept{medium} associated with
the sheet itself, be derived from a parent, or may have some global default,
depending on the sheet itself.

If a sheet is mute for output, it is an error to set any of these values.

\Defprotoclass {medium}

The protocol class that corresponds to the output state for some kind of sheet.
There is no single advertised standard medium class.
\IfYouWantClass {a} {medium} {medium}

\Defun {mediump} {object}

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

The following generic functions comprise the basic medium protocol.  All mediums
must implement methods for these generic functions.  Often, a sheet class that
supports the output protocol will implement a ``trampoline'' method that passes
the operation on to \cl{sheet-medium} of the sheet.

\defgeneric {medium-foreground} {medium}
\Defgeneric {(setf medium-foreground)} {design medium}

Returns (and, with \cl{setf}, sets) the current foreground ink for the
\term{medium} \arg{medium}. This is described in detail in
Chapter~\ref{drawing-options}.

\defgeneric {medium-background} {medium}
\Defgeneric {(setf medium-background)} {design medium}

Returns (and, with \cl{setf}, sets) the current background ink for the
\term{medium} \arg{medium}.  This is described in detail in
Chapter~\ref{drawing-options}.


\defgeneric {medium-ink} {medium}
\Defgeneric {(setf medium-ink)} {design medium}

Returns (and, with \cl{setf}, sets) the current drawing ink for the
\term{medium} \arg{medium}.  This is described in detail in
Chapter~\ref{drawing-options}.


\defgeneric {medium-transformation} {medium}
\Defgeneric {(setf medium-transformation)} {transformation medium}

Returns (and, with \cl{setf}, sets) the ``user'' transformation that converts
the coordinates presented to the drawing functions by the programmer to the
\term{medium} \arg{medium}'s coordinate system. By default, it is the identity
transformation.  This is described in detail in Chapter~\ref{drawing-options}.


\defgeneric {medium-clipping-region} {medium}
\Defgeneric {(setf medium-clipping-region)} {region medium}

Returns (and, with \cl{setf}, sets) the clipping region that encloses all output
performed on the \term{medium} \arg{medium}.  It is returned and set in user
coordinates.  That is, to convert the user clipping region to medium
coordinates, it must be transformed by the value of \cl{medium-transformation}.
For example, the values returned by

\begin{verbatim}
(let (cr1 cr2)
  ;; Ensure that the sheet's clipping region and transformation will be reset:
  (with-drawing-options (sheet :transformation +identity-transformation+
                               :clipping-region +everywhere+)
    (setf (medium-clipping-region sheet) (make-rectangle* 0 0 10 10))
    (setf (medium-transformation sheet) (clim:make-scaling-transformation 2 2))
    (setf cr1 (medium-clipping-region sheet))
    (setf (medium-clipping-region sheet) (make-rectangle* 0 0 10 10))
    (setf (medium-transformation sheet) +identity-transformation+)
    (setf cr2 (medium-clipping-region sheet))
    (values cr1 cr2)))
\end{verbatim}

are two rectangles.  The first one has edges of (0,0,5,5), while the second one
has edges of (0,0,20,20).

By default, the user clipping region is the value of \cl{+everywhere+}.

\issue {SWM} {What are ``user coordinates''?  We need to define all of the
coordinate systems in one place: device, window, stream, etc.}


\defgeneric {medium-line-style} {medium}
\Defgeneric {(setf medium-line-style)} {line-style medium}

Returns (and, with \cl{setf}, sets) the current line style for the \term{medium}
\arg{medium}.  This is described in detail in Chapter~\ref{drawing-options} and
Section~\ref{line-styles}.


\defgeneric {medium-text-style} {medium}
\Defgeneric {(setf medium-text-style)} {text-style medium}

Returns (and, with \cl{setf}, sets) the current text style for the \term{medium}
\arg{medium} of any textual output that may be displayed on the window.  This is
described in detail in Chapter~\ref{drawing-options}.


\defgeneric {medium-default-text-style} {medium}
\Defgeneric {(setf medium-default-text-style)} {text-style medium}

Returns (and, with \cl{setf}, sets) the default text style for output on the
\term{medium} \arg{medium}.  This is described in detail in
Chapter~\ref{drawing-options}.


\Defgeneric {medium-merged-text-style} {medium}

Returns the actual text style used in rendering text on the \term{medium}
\arg{medium}.  It returns the result of

\begin{verbatim} 
(merge-text-styles (medium-text-style medium)
                   (medium-default-text-style medium))
\end{verbatim}

Thus, those components of the current text style that are not \cl{nil} will
replace the defaults from medium's default text style.  Unlike the preceding
text style function, \cl{medium-merged-text-style} is read-only.


\subsection {Output Protocol Functions} 

The output protocol functions on mediums (and sheets that support the
standard output protocol) include those functions described in
Section~\ref{graphics-protocols}.

\issue {SWM} {Need to do better here}


\subsection {Output Protocol Classes}

\issue {RSL} {To be written.}

\Defclass {standard-sheet-output-mixin}

\Defclass {primitive-sheet-output-mixin}

(No client transformation/clipping region, no foreground/background inks, no
text styles.)

\Defclass {mute-sheet-output-mixin}

\Defclass {permanent-medium-sheet-output-mixin}

\Defclass {temporary-medium-sheet-output-mixin}


\subsection {Associating a Medium with a Sheet}

Before a sheet may be used for output, it must be associated with a medium.
Some sheets are permanently associated with media for output efficiency; for
example, CLIM window stream sheets have a medium that is permanently allocated
to the window.

However, many kinds of sheets only perform output infrequently, and therefore do
not need to be associated with a medium except when output is actually required.
Sheets without a permanently associated medium can be much more lightweight than
they otherwise would be.  For example, in a program that creates a sheet for the
purpose of displaying a border for another sheet, the border sheet receives
output only when the window's shape is changed.

To associate a sheet with a medium, the macro \cl{with-sheet-medium} is used.

\Defmacro {with-sheet-medium} {(medium sheet) \body body}

Within the body, the variable \arg{medium} is bound to the sheet's medium.  If
the sheet does not have a medium permanently allocated, one will be allocated,
associated with the sheet for the duration of the body, and deallocated as the
when the body has been exited.  The values of the last form of the body are
returned as the values of \cl{with-sheet-medium}.

The \arg{medium} argument is not evaluated, and must be a symbol that is bound
to a medium.  \arg{body} may have zero or more declarations as its first forms.

\Defmacro {with-sheet-medium-bound} {(sheet medium) \body body}

\cl{with-sheet-medium-bound} is used to associate the specific medium
\arg{medium} with the sheet \arg{sheet} for the duration of the body \arg{body}.
Typically, a single medium will be allocated an passed to several different
sheets that can use the same medium.

If the sheet already has a medium allocated to it, the new medium will not be
given to the sheet.  If the value of \arg{medium} is \cl{nil},
\cl{with-sheet-medium-bound} is exactly equivalent to \cl{with-sheet-medium}.
The values of the last form of the body are returned as the values of
\cl{with-sheet-medium-bound}.

\arg{body} may have zero or more declarations as its first forms.

\Defgeneric {sheet-medium} {sheet}

Returns the medium associated with the \term{sheet} \arg{sheet}.  If \arg{sheet}
does not have a medium allocated to it, \cl{sheet-medium} returns \cl{nil}.


\section {Repaint Protocol}

The repaint protocol is the mechanism whereby a program keeps the display
up-to-date, reflecting the results of both synchronous and asynchronous events.
The repaint mechanism may be invoked by user programs each time through their
top-level command loop.  It may also be invoked directly or indirectly as a
result of events received from the display server host.  For example, if a
window is on display with another window overlapping it, and the second window
is buried, a ``damage notification'' event may be sent by the server; CLIM would
cause a repaint to be executed for the newly-exposed region.


\subsection {Repaint Protocol Functions}

\Defgeneric {dispatch-repaint} {sheet region}

Requests a repaint of the \term{region} \arg{region} within the \term{sheet}
\arg{sheet}.  The region is given in sheet coordinates.  Depending on the class
of the sheet, this may cause \cl{queue-repaint} or \cl{handle-repaint} to be
invoked.

All CLIM implementations must support repainting for regions that are rectangles
or region sets composed entirely of rectangles.

\Defgeneric {queue-repaint} {sheet region}

Requests that a repaint event for the \term{region} \arg{region} be placed in
the input queue of the \term{sheet} \arg{sheet}.  A program that reads events
out of the queue will be expected to call \cl{handle-event} for the repaint
region; the method for that generic function on repaint events will generally
call \cl{repaint-sheet}.

\Defgeneric {handle-repaint} {sheet medium region}

Recursively causes repainting of the \term{sheet} \arg{sheet} and any of its
children that overlap the \term{region} \arg{region}.  \arg{medium} is the
medium to use for the repainting; if it is \cl{nil}, \cl{handle-repaint} will
allocate a medium and associate it with the sheet.  \cl{handle-repaint} will
call \cl{repaint-sheet} on \arg{sheet}, and then call \cl{handle-repaint} on all
of the children of \arg{sheet}.

\Defgeneric {repaint-sheet} {sheet region}

Implements repainting for a given sheet class.  It may only be called on a sheet
that has an associated medium.  \term{sheet} and \arg{region} are as for
\cl{dispatch-repaint}.


\subsection {Repaint Protocol Classes}

\Defclass {standard-repainting-mixin}

Defines a \cl{dispatch-repaint} method that calls \cl{queue-repaint}.

\Defclass {immediate-repainting-mixin}

\issue {RSL} {Is this a good name?}

Defines a \cl{dispatch-repaint} method that calls \cl{handle-repaint}.

\Defclass {mute-repainting-mixin}

Defines a \cl{dispatch-repaint} method that calls \cl{queue-repaint}, and a
method on \cl{repaint-sheet} that does nothing.  This means that its children
will be recursively repainted when the repaint event is handled.


\section {Sheet Notification Protocol}

The notification protocol allows sheet clients to be notified when a sheet
hierarchy is changed.  Sheet clients can observe modification events by
providing \cl{:after} methods for functions defined by this protocol.

\subsection {Relationship to Window System Change Notifications}

\issue {RSL} {To be written.}

\defgeneric {note-sheet-grafted}   {sheet}
\defgeneric {note-sheet-degrafted} {sheet}
\defgeneric {note-sheet-adopted}   {sheet}
\defgeneric {note-sheet-disowned}  {sheet}
\defgeneric {note-sheet-enabled}   {sheet}
\Defgeneric {note-sheet-disabled}  {sheet}

These notification functions are invoked when the state change has been made to
the \term{sheet} \arg{sheet}.

\subsection {Geometry Notifications}

\issue {RSL} {To be written.}

\defgeneric {note-sheet-region-changed} {sheet}
\Defgeneric {note-sheet-transformation-changed} {sheet}

These notification functions are invoked when the region or transformation of
the \term{sheet}\arg{sheet} has been changed.  When the regions and
transformations of a sheet are changed directly, the client is required to call
\cl{note-sheet-region-changed} or \cl{note-sheet-transformation-changed}.


\chapter {Ports, Grafts, and Mirrored Sheets}
\label{ports-and-grafts}

\section {Introduction}

A sheet hierarchy must be attached to a display server so as to permit input
and output.  This is managed by the use of ports and grafts.

\section {Ports}

A \concept{port} is a logical connection to a display server.  It is responsible
for managing display output and server resources, and for handling incoming
input events.  Typically, the programmer will create a single port that will
manage all of the windows on the display.

A port is described with a \concept{server path}.  A server path is a list whose
first element is a keyword that selects the kind of port.  The remainder of the
server path is a list of alternating keywords and values whose interpretation is
port type-specific.

\Defun {find-port} {\key (server-path \cl{*default-server-path*})}

Finds a port that provides a connection to the window server addressed by
\arg{server-path}.  If no such connection exists, a new connection will be
constructed and returned.

The following server paths are currently supported:

\def\Defdp #1 #2 {\Dodocf {#1} {#2} {Server~Path}}

\Defdp {:x11} {\key host display-id screen-id}

Given this server path, \cl{find-port} finds a port for the X server on the
given \arg{host}, using the \arg{display-id} and \arg{screen-id}.

On a Unix host, if these values are not supplied, the defaults come from the
\cl{display} environment variable.  Each CLIM implementation must describe how
it uses such environment variables.

\Defdp {:genera} {\key screen}

\issue {RSL} {This is old and obsolete.  Ditto \cl{:coral}, or whatever we're
going to call it now.}


\Defvar {*default-server-path*}

This special variable is used by \cl{find-port} and its callers to default the
choice of a display service to locate.  Binding this variable in a dynamic
context will affect the defaulting of this argument to these functions.  This
variable will be defaulted according to the environment.  In the Unix
environment, for example, CLIM will attempt to set this variable based on the
value of the \cl{display} environment variable.

\Defgeneric {sheet-port} {sheet}

Returns the port associated with the \term{sheet} \arg{sheet}.  \cl{sheet-port}
is defined for all kinds of sheets (including grafts and streams that support
the CLIM graphics protocol) and mediums.  For degrafted sheets or other objects
that aren't currently associated with particular ports, \cl{sheet-port} will
return \cl{nil}.

\Defmacro {with-port-locked} {port \body body}

Executes \arg{body} after grabbing a lock associated with the \term{port}
\arg{port}, which may be a port or any object on which the function
\cl{sheet-port} works.  If \arg{object} currently has no port, \arg{body} will
be executed without locking.

\arg{body} may have zero or more declarations as its first forms.


\defgeneric {port-properties} {port indicator}
\Defgeneric {(setf port-properties)} {property port indicator}

These functions provide a port-based property list.  They are primarily intended
to support users of CLIM that may need to associate certain information with
ports.  For example, the implementor of a special graphics package may need to
maintain resource tables for each port on which it is used.

\Defun {map-over-ports} {function}

Invokes \arg{function} on each existing port.  Function is a function of one
argument, the port; it has dynamic extent.

\Defgeneric {restart-port} {port}

In a multi-process Lisp, \cl{restart-port} restarts the global input processing
loop associated with the \term{port} \arg{port}.  All pending input events are
discarded.  Server resources may or may not be released and reallocated during
or after this action.

\Defgeneric {destroy-port} {port}

Destroys the connection with the window server represented by the \term{port}
\arg{port}.  All sheet hierarchies that are associated with \arg{port} are
forcibly degrafted by disowning the children of grafts on \arg{port} using
\arg{sheet-disown-child}.  All server resources utilized by such hierarchies or
by any graphics objects on \arg{port} are released as part of the connection
shutdown.

\defgeneric {add-watcher} {port watcher}
\defgeneric {delete-watcher} {port watcher}
\Defgeneric {reset-watcher} {watcher how}

Watchers are a mechanism for clients to be notified when the port is destroyed
or restarted.  \cl{add-watcher} and \cl{delete-watcher} provide an interface for
adding and removing \arg{watcher} to the list of watchers that the \term{port}
\arg{port} maintains.  \cl{destroy-port} and \cl{restart-port} invoke
\cl{reset-watcher} on each of these watchers with \cl{:destroy} and
\cl{:restart} being passed in as \arg{how}, respectively.

\issue {SWM} {What exactly is a watcher?  The above is not specific enough.}


\section {Grafts}

A graft is a special sheet that is directly connected to a display server.
Typically, a graft is the CLIM sheet that represents the root window of the
display.  There may be several grafts that are all attached to the same root
window; these grafts may have differing coordinate systems.  

To display a sheet on a display, it must have a graft for an ancestor.  In
addition, the sheet and all of its ancestors must be enabled, including the
graft.  In general, a sheet becomes grafted when it (or one of its ancestors) is
adopted by a graft.

\Defgeneric {sheet-grafted-p} {sheet}

Returns \term{true} if any of the sheet's ancestors is a graft, otherwise
returns \term{false}.


\Defun {find-graft} {\key (port \cl{(find-port)}) (server-path \cl{*default-server-path*})
			  (orientation \cl{:default}) (units \cl{:device})}

Finds a graft that represents the display device on the port \arg{port} that
also matches the other supplied parameters.  If no such graft exists, a new
graft is constructed and returned.

If \arg{server-path} is supplied, \cl{find-graft} finds a graft whose port
provides a connection to the window server addressed by \arg{server-path}.

It is an error to provide both \arg{port} and \arg{server-path} in a call to
\cl{find-graft}.

\arg{orientation} specifies the orientation of the graft's coordinate
system.  Supported values are \cl{:default} and \cl{:graphics}, which have the
meanings describe below:

\begin{itemize}
\item \cl{:default}---a coordinate system with its origin is in the upper left
hand corner of the display device with $y$ increasing from top to bottom and $x$
increasing from left to right.

\item \cl{:graphics}---a coordinate system with its origin in the lower left
hand corner of the display device with $y$ increasing from bottom to top and $x$
increasing from left to right.
\end{itemize}

\arg{units} specifies the units of the coordinate system and defaults to
\cl{:device}, which means the device units of the host window system (such as
pixels).  Other supported values include \cl{:inches}, \cl{:millimeters}, and
\cl{:screen-sized}, which means that one unit in each direction is the width and
height of the display device.

\issue {RSL} {I don't know how much of this is obsolete.}

\Defgeneric {sheet-graft} {sheet}

Returns the graft currently associated with the \term{sheet} \arg{sheet}.
\cl{sheet-graft} is defined for all kinds of sheets (including streams that
support the CLIM graphics protocol) and mediums.  For degrafted sheets or other
objects that aren't currently associated with a particular graft,
\cl{sheet-graft} will return \cl{nil}.

\Defun {map-over-grafts} {function port}

Invokes \arg{function} on each existing graft associated with the \term{port}
\arg{port}.  \arg{function} is a function of one argument, the graft; it has
dynamic extent.

\Defmacro {with-graft-locked} {graft \body body}

Executes \arg{body} after grabbing a lock associated with the \term{graft}
\arg{graft}, which may be a graft or any object on which the function
\cl{sheet-graft} works.  If \arg{object} currently has no graft, \arg{body} will
be executed without locking.

\arg{body} may have zero or more declarations as its first forms.


\Defgeneric {graft-orientation} {graft}

Returns the orientation of the \term{graft} \arg{graft}'s coordinate system.
The returned value will be either \cl{:default} or \cl{:graphics}.  The meanings
of these values are the same as described for the orientation argument to
\cl{find-graft}.

\Defgeneric {graft-units} {graft}

Returns the units of the \term{graft} \arg{graft}'s coordinate system.  The
returned value will be one of \cl{:device}, \cl{:inches}, \cl{:millimeters}, or
\cl{:screen-sized}.  The meanings of these values are the same as described for
the units argument to \cl{find-graft}.

\defgeneric {graft-width} {graft \key (units \cl{:device})}
\Defgeneric {graft-height} {graft \key (units \cl{:device})}

Returns the width and height of the \term{graft} \arg{graft} (and by extension
the associated host window) in the units indicated.  \arg{Units} may be any of
\cl{:device}, \cl{:inches}, \cl{:millimeters}, or \cl{:screen-sized}.  The
meanings of these values are the same as described for the units argument to
\cl{find-graft}.  Note if a \arg{unit} of \cl{:screen-sized} is specified, both
of these functions will return a value of \cl{1}.

\defun {graft-pixels-per-millimeter} {graft}
\Defun {graft-pixels-per-inch} {graft}

Returns the number of pixels per millimeter or inch of the \term{graft}
\arg{graft}.  These functions are provided as a convenience to programmers and
can be easily written in terms of \cl{graft-width} or \cl{graft-height}.

\issue {Rao} {Do we want to support non-square pixels?  If so, these functions
aren't sufficient.}


\section {Mirrors and Mirrored Sheets}

A \concept{mirrored sheet} is a special class of sheet that is attached directly
to a window on a display server.  Grafts, for example, are always mirrored
sheets.  However, any sheet anywhere in a sheet hierarchy may be a mirrored
sheet.  A mirrored sheet will usually contain a reference to a window system
object, called a mirror.  For example, a mirrored sheet attached to an X11
server might have an X window system object stored in one of its slots.
Allowing mirrored sheets at any point in the hierarchy enables the adaptive
toolkit facilities.

Since not all sheets in the hierarchy have mirrors, there is no direct
correspondence between the sheet hierarchy and the mirror hierarchy.  However,
on those display servers that support hierarchical windows, the hierarchies must
be parallel.  If a mirrored sheet is an ancestor of another mirrored sheet,
their corresponding mirrors must have a similar ancestor/descendant
relationship.

CLIM interacts with mirrors when it must display output or process events.
On output, the mirrored sheet closest in ancestry to the sheet on which we wish
to draw provides the mirror on which to draw.  The mirror's drawing clipping
region is set up to be the intersection of the user's clipping region and the
sheet's region (both transformed to the appropriate coordinate system) for the
duration of the output.  On input, events are delivered from mirrors to the
sheet hierarchy.  The CLIM port must determine which sheet shall receive events
based on information such as the location of the pointer.

In both of these cases, we must have a coordinate transformation that converts
coordinates in the mirror (so-called ``native'' coordinates) into coordinates
in the sheet and vice-versa.


\subsection {Mirror Functions}

\Defgeneric {sheet-direct-mirror} {sheet}

Returns the mirror of the \term{sheet} \arg{sheet}.  If the sheet is not
mirrored (or does not currently have a mirror), \cl{sheet-mirror} returns
\cl{nil}.

\Defgeneric {sheet-mirrored-ancestor} {sheet}

Returns the nearest mirrored ancestor of the \term{sheet} \arg{sheet}.

\Defgeneric {sheet-mirror} {sheet}

Returns the mirror of the \term{sheet} \arg{sheet}.  If the sheet is not itself
mirrored, \cl{sheet-mirror} returns the direct mirror of its nearest mirrored
ancestor.  \cl{sheet-mirror} could be implemented as:

\begin{verbatim}
(defun sheet-mirror (sheet)
  (sheet-direct-mirror (sheet-mirrored-ancestor sheet)))
\end{verbatim}

\Defgeneric {realize-mirror} {port mirrored-sheet}

Creates a mirror for the \term{sheet} \arg{mirrored-sheet} on the \term{port}
\arg{port}, if it does not already have one.  The returned value is the sheet's
mirror.


\subsection {Internal Interfaces for Native Coordinates}

\Defgeneric {sheet-native-transformation} {sheet}

Returns the transformation for the \term{sheet} \arg{sheet} that converts sheet
coordinates into native coordinates.  The object returned by this function is
volatile, so programmers must not depend on the components of the object
remaining constant.

\Defgeneric {sheet-native-region} {sheet}

Returns the region for the \term{sheet} \arg{sheet} in native coordinates.  The
object returned by this function is volatile, so programmers must not depend on
the components of the object remaining constant.

\issue {RSL} {These used to be called \cl{fetch-mirrored-sheet},
\cl{fetch-native-transformation}, and \cl{fetch-native-clipping-region}.}


\Defgeneric {sheet-device-transformation} {sheet}

Returns the transformation used by the graphics output routines when drawing on
the mirror.  This is the composition of the sheet's native transformation and
the user transformation.  The object returned by this function is volatile, so
programmers must not depend on the components of the object remaining constant.

\Defgeneric {sheet-device-region} {sheet}

Returns the actual clipping region to be used when drawing on the mirror.  This
is the intersection of the user's clipping region (transformed by the device
transformation) with the sheet's native region.  The object returned by this
function is volatile, so programmers must not depend on the components of the
object remaining constant.

\Defgeneric {invalidate-cached-transformations} {sheet}

\cl{sheet-native-transformation} and \cl{sheet-device-transformation} typically
cache the transformations for performance reasons.
\cl{invalidate-cached-transformations} clears the cached native and device
values for the \term{sheet} \arg{sheet}'s transformation and clipping region.
It is invoked when a sheet's native transformation changes, which happens when a
sheet's transformation is changed or when \cl{invalidate-cached-transformations}
is called on any of its ancestors.

\Defgeneric {invalidate-cached-regions} {sheet}

\cl{sheet-native-region} and \cl{sheet-device-region} typically cache the
regions for performance reasons.  \cl{invalidate-cached-regions} clears the
cached native and device values for the \term{sheet} \arg{sheet}'s native
clipping region.  It is invoked when a sheet's native clipping region changes,
which happens when the clipping region changes or when
\cl{invalidate-cached-regions} is called on any of its ancestors.


\comment {Here is stuff from the old Silica chapters that should perhaps
be incorporated into the above:

\Defgeneric {fetch-clipping-region} {child ancestor}

Returns the clipping region of \arg{child} with respect to \arg{ancestor} in
\arg{ancestor}'s coordinate system.  This region is the subregion of ancestor
that is occupied by child.  Note that this calculation takes into account the
ordering of children if they intersect in the chain of windowing relationships
between child and ancestor.  Specifying an \arg{ancestor} of \cl{nil} is the
same as specifying the greatest ancestor of \arg{child} (a graft if child is
grafted).  An error is signalled if \arg{ancestor} is not an ancestor of
\arg{child}.  It is an error to modify the region returned by this function.

\issue {Rao} {Need a much better definition of clipping region.}


\section {Standard Input Contract}

Silica separates input processing into two phases:  \concept{distribution}
(determining the appropriate sheet to receive the input) and
\concept{dispatching} (translating the port-specific event representation into a
suitable representation and delivering the event to the client of the recipient
sheet).  Since input is received from the host window server and distribution is
inherently affected by the properties of many and possibly distant sheets in a
hierarchy, distribution is controlled by the port and an associated object
called distribution contract or distributors for short.  The details of how
distribution is handled by a port and its distributor aren't important to most
users of standard input.  Hence, they are covered in
Section~ref{event-distribution}.

A sheet's input contract is responsible for dispatching events that are
distributed to the sheet (which, as described above, includes both translating
the port event and delivering it to the sheet's client).  The standard input
contract translates the port-specific event into the standard event
representation (which is described in Chapter~\arg{events}) and delivers it to
the client by queueing on an event queue associated with the sheet.  In
addition, this queueing interface is also used by the other standard contracts
to queue their non-input-device-generated (such as windowing and repaint events)
events.

A sheet's input contract is also responsible for providing other input services
to the sheet including control of the pointer's appearance, polling for current
pointer and keyboard state, and interactions with the port's distributor.  The
standard input contract provides a standard interface to each of these services.

\section {Standard Output}

A sheet's output contract is responsible for 1) providing a means of doing
output to a sheet and 2) delivering repaints requests to the sheet's client.
The standard output contract supports the use of the CLIM output facilities
describe in Part~\ref{output-facilities}.  A standard output sheet is provided
with its own medium object that can be used to draw on the sheet using the CLIM
graphics functions.  In addition, these functions can be called directly on the
sheet.

\section {Standard Windowing}

The standard windowing contract supports multiple overlapping children in a
windowing relationship that can dynamically be adopted and disowned. The
children are ordered in top to bottom order.  All the sheet protocols documented
in Chapter~\ref{sheet-protocols} are supported.

Standard windowing allows its children's region and transformations to be of any
region or transformation type respectively.  Programmers will generally use
rectangles and rectilinear transformations.  More complex region or
transformation types are not necessarily supported by all CLIM implementation on
all display servers.

\chapter {Non-standard Sheet Types}
\label {sheet-types}

In the last section, standard sheets that have roughly the functionality of the
lightweight windows of X were described.  This section provides a more detailed
account of how sheet types are implemented, so that programmers can implement
their own types (either to support new types of window-like surfaces or to build
toolkits objects like buttons, scrollbars, and grapher nodes).

In addition to the basic properties of sheets describe above, sheets also have
the following four properties called contracts: input contract, output contract,
adult windowing contract, youth windowing contract.  These contracts specify and
implement the input, output, or windowing functionality of the sheet.  The input
contract defines the input interface of a sheet, specifically how input gestures
are delivered to client of a sheet.  The output contract define the output
interface, specifically how the client of the sheet can draw images on the
sheet's surface and how the client is expected to repaint the sheet.

Windowing contracts provide support for maintaining windowing relationships.  A
sheet can participate in one windowing relationship as a parent as well as in
another as child.  The windowing contract in which the sheet is a parent is
called its adult contract; similarly the one in which the sheet is a child is
called its youth contract.

\section {Sheet Types and Contracts}

Contracts can be thought of as delegates of the sheet that handle certain
functions for the sheet, however the CLIM implementation of this framework
avoids excessive object allocation and method trampolining overhead, by using
inheritance.  In particular, contracts objects do not exist separately from the
sheets that use them, but rather the class of such sheets includes its
contracts' implementing classes as superclasses.

Input and output contract classes are simply inherited from by sheet classes.
The situation with windowing contracts is slightly more complex.  Windowing
contracts are implemented as two part classes, one to be mixed into sheets that
are to be a parent in the windowing relationship and the other to be mixed into
those that are to be children.  In addition, a windowing contract class is
defined, though it not be instantiated.  This class exists primarily as a handle
for functionality that manipulates windowing contracts (for example,
\cl{change-windowing-contract}).  However, the implementor of the windowing
contract can decide whether the child and parent parts are sufficient or whether
a separate neutral object is needed for its purposes.

To be specific, a sheet is an instance of a \concept{sheet class}.  Sheet classes
are constructed based on the input, output, and windowing functionality selected
by the client of the sheet.  Additionally, clients can add their own mixins to
the sheet that supply client specific methods.  So, in summary, sheet classes
inherit from the following classes:

\begin{itemize}
\item \cl{sheet}

\item A parent part class (part of adult windowing contract)

\item A child part class (part of youth windowing contract)

\item An output contract class

\item An input contract class

\item An arbitrary number of client supplied classes.
\end{itemize}

\issue {SWM} {The inheritance stuff above is wrong, now that we are trying to
get rid of the contract classes.  Flush all discussions of contracts.}

There are two ways to construct sheet classes and instantiate them.  One way is
to invoke \cl{make-sheet}, which dynamically constructs a sheet class according
to arguments passed in by the caller.  These dynamically constructed classes are
cached, so that construction overhead is incurred only once.  Subsequent
attempts to use the same sheet class only incur lookup overhead.

The second way is to statically define a sheet type using
\cl{define-sheet-class} and to instantiated it using \cl{make-instance} or a
client defined constructor.  Make-standard-sheet is a constructor that uses a
statically defined sheet class, namely \cl{standard-sheet}.

\Defun {make-sheet} {\rest args
                     \key youth-contract-class adult-contract-class 
                          input-contract-class output-contract-class
                          supers region parent transformation \allow}
        
The \arg{class arguments} and \arg{supers} are ordered as listed above to
generate a specification for a sheet class.  This specification is used to
locate a dynamically constructed sheet class.  The class arguments can be
symbols or classes and supers is a list of symbols or classes.  This class is
instantiated and initialized with \arg{args}.  Which args are applicable depends
on the initialization options defined by the contracts and the client supplied
supers.

If \arg{parent} is supplied, \cl{sheet-adopt-child} is invoked on the sheet and
\arg{parent}.  \arg{region} and \arg{transformation} initialize the sheet
according to the specification of the windowing contracts of the sheet.

\Defmacro {define-sheet-class} {class supers slots \rest options}

This macro allows you to statically define a sheet class.  Its syntax is the
same as \cl{defclass} with the addition of the following extra \arg{options}:
\cl{:youth-contract-class}, \cl{:adult-contract-class},
\cl{:input-contract-class}, or \cl{:output-contract-class}.  These extra options
take the names of contract classes as arguments.

\issue {SWM} {The contract stuff below is now wrong.}

\begin{verbatim}
(define-sheet-class standard-sheet ()
    ()
  (:youth-contract-class standard-windowing-contract)
  (:adult-contract-class standard-windowing-contract)
  (:input-contract-class standard-input-contract)
  (:output-contract-class standard-output-contract))
\end{verbatim}

\section {Dynamic Output Contract}

The \cl{dynamic-output-contract} class allows for the dynamic selection and use
of properly incorporated graphics package.  Graphics packages are incorporated
into the Silica framework (provided to clients of dynamic output) by
implementing a \cl{display medium} class.  A display medium combines state about
the target sheet, imaging parameters and options supported by the medium, and
port specific implementation data.  The implementation of a display medium type
is discussed in Section~\ref{display-medium}.

A client can get a display medium for a dynamic output sheet in one of two ways:

\begin{enumerate}
\item A medium may be allocated to the sheet by passing in the \cl{:medium-type}
initarg (for example, \cl{:clim} gets a CLIM graphics medium) at sheet creation.

\item A programmer can use \cl{using-display-medium} to temporary allocate a
medium that uses the sheet as its target.
\end{enumerate}

\Definitarg {:medium-type}

This initarg can be used with dynamic output contract.  If this initarg is used,
than a medium will be allocated for the sheet when it is grafted.  \cl{:clim} is
the only value guaranteed to be implemented across all ports.

\Defgeneric {sheet-medium} {sheet}

Returns the medium allocated for a particular sheet.  Returns \cl{nil} when the
sheet is not grafted and also if no medium-type was selected for the sheet at
sheet creation time.

\Defmacro {using-display-medium} {(dm medium-type output-contract) \body forms}

This wrapping form temporarily allocates a display medium of \arg{medium-type}
and releases it on exit.

\section {Providing a Display Medium Type}

The graphics package independence of \cl{standard-output-contract} is based on
the concept of display media.  Display media provide a context that allows the
window system to control output performed by clients.  In addition, display
media may provide auxiliary state for managing client imaging parameters.
Graphics packages are incorporated into Silica (that is, made usable by users of
standard output) by implementing a \concept{display medium} class.

A medium is an implementation or incorporation of a graphics package into the
Silica framework.  This section defines the protocols for implementing a medium
type and in particular a display medium type.

\Defclass {display-medium}

Display mediums are subclasses of standard output that incorporate a graphics
package into the Silica framework.
  
A display medium class must implement two protocol: a client interface to the
graphics package (which is completely defined by the graphics package being
incorporated), and an interface required by Silica.  The client interface is
generally the same as the client interface to the graphics package (that's the
point of providing that graphics package) though slight additions may be made to
improve performance.  The \cl{standard-output-contract} requirements are
sufficient to allow using the graphics package on a sheet.  They consist of the
following areas:

\begin{itemize}
\item {\bf View Control}.  Generic functions for setting the clipping region and
output transformation as required by windowing policies.  These routines must
not interfere with the use of clipping and transformations by the client, if the
client interface allows these things.

\item {\bf Output Protection}.  This includes validating that proper clipping
regions and transformation are being used, and locking out changes that might
influence these.  Protection granularity depends significantly on the graphics
package and on what kind of client interface to graphics routines are provided.

\item {\bf Integration of Types}. The region and transformation types used by
the graphics package should be integrated into the kernel or coerced at
appropriate interfaces, so that clients don't have to use different kinds of
regions to talk to windowing functionality and output functionality.
\end{itemize}

\defgeneric {(setf silica-clipping-region)} {display-medium}
\Defgeneric {(setf silica-medium-transformation)} {display-medium}

A display medium must clip and transform all output according to the values
returned by these functions.  A display medium class can provide methods on the
setf generic functions to update state or to mark the need to update state or
whatever.

\defgeneric {device-clipping-region} {display-medium} 
\Defgeneric {device-transformation} {display-medium}

\Defmacro {with-output-protection} {(dm) \body body}

All graphics routines provided by the display medium must insure that imaging
happens with a protected context using this macro.  This allows the window
system to insure that the display medium clipping regions and transformations
will not changed during the scope of the imaging operation.

\chapter {Input Processing}

Silica provides an input architecture and standard functionality for notifying
clients of input that is distributed to their sheets.  Input includes the
pointer entering and exiting sheets, pointer motion as allowed by performance,
and mouse button and keyboard events.

Programmers who would like to design specialized input machinery need to
understand the details of Silica's input distribution architecture.  This
section covers that topic.  Most users of higher levels of CLIM need not
concern themselves with the details presented here.

Silica separates device input processing into two phases:  distribution
(determining which sheet should receive the input), and delivery (translating
the raw input into a representation suitable to the client of the recipient
sheet).  The design goals for the input architecture include allowing flexible
selection of both distribution and delivery policies as well as providing
standard policies that are portable across a wide variety of host window servers
and sufficient for most applications.  This input architecture supports both
event-oriented and stream-oriented input interfaces; and both single and
multiple process environments.

The flow of input processing proceeds as follows.  Device events come in from a
port in a window server specific way.  Each device event is directed to an event
distributor that is responsible for determining the recipient of the input, and
possibly also for generating crossing events on mouse motion.  A standard
distributor is provided and chosen by default for most ports.

After a recipient is found for a device event, the device event is passed to the
input contract of the sheet.  The input contract translates and delivers the
event to the sheet's client.  This means that an input contract must define a
method for converting and delivery the device event of each port type that it
supports.  This approach allows delayed representation of input based on the
final recipient of the input.  The standard input contracts are described below.

Each port has a event processor that processes all of the
implementation-specific device events.  This port event processor may run in a
separate per-port process or can be invoked directly by higher levels in a
single-process environment.  For example, in a multiprocess environment a port
event handler would run code similar to the following:

\begin{verbatim}
   (loop (process-next-event display))
\end{verbatim}

\Defgeneric {process-next-event} {port \key timeout}

This function provides a standard interface for one pass through a port's event
processing loop.  It returns \term{true} if an event was processed, otherwise it
returns \term{false} (meaning that the function timed out).  A port
implementation must provide a method for this function that reads the next
window server specific device event (blocking if necessary) and then invokes the
port's event distributor via a call to \cl{distribute-device-event}.  This
method is required to pass along some necessary keyword arguments along with any
port specific keyword args that will eventually be parsed by port-specific
methods defined on the input contract of the recipient sheet.

\Defgeneric {distribute-device-event} {distributor port source \key \allow}

A distributor implementation must provide a method for this function.
\arg{Source} indicates the sheet that corresponds to the host window that the
event was delivered to by the window server.  This method is responsible for
invoking \cl{dispatch-device-event} or \cl{dispatch-crossing-event} on input
contract of sheet's.

\Defclass {standard-event-distributor} 

This class implements the standard distribution policy supported by Silica.
Pointer button and motion events are distributed to deepest sheet in the
hierarchy that contains the pointer at the time that the event is generated.
Keyboard events can be distributed either to a particular sheet or to the same
sheet that would receive pointer events.

\defgeneric {dispatch-device-event} {port input-contract \key sheet \allow}
\Defgeneric {dispatch-crossing-event} {port input-contract \key sheet \allow}

These functions are invoked by an event distributor.  Typically the
input-contract is the same object as the sheet and some generic as well as some
port-specific keywords arguments indicating the device event are passed in.
Input contract implementations provide methods specialized on each of the ports
that the input contract is supported on.  These methods are responsible for
parsing the keyword arguments and delivering the event to the client of the
sheet.


%\Defgeneric {port-event-distributor} {port}

%\Defgeneric {port-cursor} {port}

\section {Input Contracts}

Standard event delivery is implemented by the \cl{standard-input-contract}
class.  This input contract type provides methods for the appropriate generic
functions of the Event Distribution protocol that invoke \cl{queue-event} on the
recipient sheet and the event.  Clients can pass in an event queue when a
standard input contract is initialized or change the queue associated with the
sheet later.

\keepout{This input contract type provides event delivery methods that converts
the port-specific event keywords into the standard event representation and
then invokes \cl{queue-event} on the recipient sheet and the event.}

\Defclass {standard-input-contract}

In addition to the standard input contract, two other contracts are provided:
\cl{mute-input-contract} and \cl{invoking-input-contract}.  In addition, the
\cl{bursting-input-queuer} mixin is provided as a convenient addition to the
protocol implemented by \cl{invoking-input-contract}.

\Defclass {mute-input-contract}

This class supports sheets that do not wish to receive input.

\Defclass {invoking-input-contract}

The \cl{invoking-input-contract} is different from the standard input contract
in at least two significant ways.  First, it converts the host-specific event
into a set of keyword arguments and invokes \cl{handle-input} on the recipient
sheet and these arguments (as opposed to queuing a structured event).  And
second, the client is expected to do its input handling synchronously within the
port's event handling process.  (In single process environments, the difference
is that the input is done during queue-input, rather than at a some other place
in the application input loop).
        
\Defgeneric {queue-input} {client \key type sheet state x y time \allow} 

This function is invoked by the invoking input contract.  \arg{client} is
typically the recipient sheet itself, since the creator of the sheet will have
additional super classes added to the sheet's sheet class.

\Defclass {bursting-input-queuer}

This class provides standard methods for \cl{queue-input}.  The method for
\cl{queue-input} provided by input handler examines the \arg{type} and
dispatches to one of the event handling function described below.

\Defgeneric {enter-region} {client \key \allow}
\Defgeneric {exit-region} {client \key \allow}

These generic functions are invoked by \cl{deliver-event} when the cursor enters or
exits an active region

\issue {SWM} {What is \cl{deliver-event}?  Why do these allow other keywords?}

\chapter {Other Input Facilities}

\section {Standard Polling Interfaces}

\Defgeneric {poll-pointer} {sheet}

This function provides polling support.  Returns X, Y, and state.  This function
can be used to obtain the location of the pointer device and the state of mouse
buttons and modifier keys.

} %% end of long comment
