% -*- 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