
("     " (:PAR) "  " (:PAR) " " (:PAR) (:PAR) (:PAR) " " (:PAR) (:PAR) "  " (:PAR) " " (:PAR) "           " (:PAR)
 "    " (:PAR) (:PAR) "   " (:PAR) " " (:PAR) (:PAR) " " (:PAR) " " (:PAR) (:PAR) "                  " (:PAR) (:PAR)
 "          " (:PAR) " " (:PAR) " " (:PAR) "   " (:PAR) " " (:PAR) " " (:PAR) (:PAR) (:PAR) (:PAR) (:PAR) (:PAR) (:PAR)
 (:PAR) (:PAR) (:PAR) (:PAR) (:PAR) "    " (:PAR)
 (:DOCUMENT :KIND :DOCUMENT :TITLE ("Common Lisp Interface Manager " (:BR) "  CLIM II Specification") (:PAR) (:PAR) " "
  (:PAR) (:PAR) " " (:TABLEOFCONTENTS) (:PAR) " " "  " (:GROUP (:FONT :FACE :HUGE) (:FONT :FACE :B) "Acknowledgments")
  (:PAR) " " (:PAR)
  "The process of designing and implementing CLIM and writing the CLIM specification has been a long and sometimes bumpy one. The first thanks have to go to the people and organizations who allowed the people working on CLIM to continue to do so, despite the obstacles. In particular, Mark Son-Bell of ILA; Bob Laddaga and Saiid Zarrabian at Symbolics (and before or with them, Ken Sinclair, Rick Karash, and Mark Graffam); and Jim Vietch and Hanoch Eiron of Franz, Inc. have struggled with various and sometimes conflicting business interests through the whole process."
  (:PAR)
  "The attendees of the CLIM coalition meetings and those who contributed to CLIM along the way include all of those listed on the title page, but also include Bob Kerns, John Irwin, Paul Weineke and JonL White, and Kevin Males. Other contributors include Mike McMahon, Paul Robertson, John Hotchkiss, Dave Lowry, Mike Greenwald, Dave Schatsky, and Glenn Adams. Barry Margolin and Richard Billington, acting for the ALU, contributed useful comments as well."
  (:PAR)
  "Sonya Keene, Ann Hathaway, and Ellen Golden all deserve credit for improving the quality of this specification (in part by authoring the original CLIM documentation), as does Mark Nahabedian."
  (:PAR)
  "Kent Pitman provided much useful advice on the mechanics of writing a specification, and this document improved significantly because of that."
  (:PAR)
  "Last but not least are the people who have continued to use CLIM for the duration of this lengthy process. The people at BBN (Bruce Roberts and his group) have been a continuing source of valuable information and suggestions. Also, Markus Fischer of Symbolics GmbH had to deal with more than his fair share of problems, the result of using CLIM in novel ways."
  (:PAR) (:PAR) "  " (:PAR)
  (:SECTION :KIND :PART :TITLE ("Part I: " "Overview and Conventions") :NAME (10) " " " "
   (:SECTION :TITLE ("1 " "Overview of CLIM") :KIND :CHAPTER :NAME (2 10) " " (:LABEL :NAME "clim-overview") (:PAR)
    "The Common Lisp Interface Manager (CLIM) is a powerful Lisp-based programming interface that provides a layered set of portable facilities for constructing user interfaces. These include basic windowing, input, output, and graphics services; stream-oriented input and output extended with facilities such as output recording, presentations, and context sensitive input; high level \"formatted output\" facilities; application building facilities; command processing; and a compositional toolkit similar to those found in the X world that supports look and feel independence."
    (:PAR)
    "CLIM provides an API (applications programmer interface) to user interface facilities for the Lisp application programmer. CLIM does not compete with the window system or toolkits of the host machine (such as Motif or OpenLook), but rather uses their services (to the extent that it makes sense) to integrate Lisp applications into the host's window environment. For example, CLIM \"windows\" are mapped onto one or more host windows, and input and output operations performed on the CLIM window are ultimately carried out by the host window system. CLIM will support a large number of host environments including Genera, Motif, OpenLook, the Macintosh, CLOE-386/486, and the Next machine."
    (:PAR)
    "The programmer using CLIM is insulated from most of the complexities of portability, since the Lisp-based application need only deal with CLIM objects and functions regardless of their operating platform (that is, the combination of Lisp system, host computer, and host window environment). CLIM abstracts out many of the concepts common to all window environments. The programmer is encouraged to think in terms of these abstractions, rather than in the specific capabilities of a particular host system. For example, using CLIM, the programmer can specify the appearance of output in high-level terms and those high-level descriptions are turned into the appropriate appearance for the given host. Thus, the application has the same fundamental interface across multiple environments, although the details will differ from system to system."
    (:PAR)
    "Another important goal in the design and organization of CLIM is to provide a spectrum of user interface building options, all the way from detailed, low-level specification of \"what goes where\", to high-level user interface specification where the programmer leaves all of the details up to CLIM. This allows CLIM to balance the ease of use on one hand, and versatility on the other. By using high level facilities, a programmer can build portable user interfaces quickly, whereas by recombining lower level facilities he can build his own programming and user interfaces according to his specific needs or requirements. For example, CLIM supports the development of applications independent of look and feel, as well as the portable development of toolkit libraries that define and implement a particular look and feel."
    (:PAR)
    "In addition, CLIM's layered design allows application programs to exclude facilities that they do not use, or reimplement or extend any part of the substrate. To these ends, CLIM is specified and implemented in a layered, modular fashion based on protocols. Each facility documented in this specification has several layers of interface, and each facility is independently specified and has a documented external interface."
    (:PAR) "The facilities provided by CLIM include:" (:PAR)
    (:DL (:DT "Geometry")
     (:DD
      "CLIM provides provides geometric objects like point, rectangle, and transformations and functions for manipulating them."
      (:PAR))
     (:DT "Graphics")
     (:DD
      "CLIM provides a rich set of drawing functions, including ones for drawing complex geometric shapes, a wide variety of drawing options (such as line thickness), a sophisticated inking model, and color. CLIM provides full affine transforms, so that a drawing may be arbitrarily translated, rotated, and scaled (to the extent that the underlying window system supports the rendering of such objects)."
      (:PAR))
     (:DT "Windowing")
     (:DD "CLIM provides a portable layer for implementing " (:TERM "sheet")
      " classes (types of window-like objects) that are suited to support particular high level facilities or interfaces. The windowing module of CLIM defines a uniform interface for creating and managing hierarchies of these objects regardless of their sheet class. This layer also provides event management."
      (:PAR))
     (:DT "Output Recording")
     (:DD
      "CLIM provides a facility for capturing all output done to a window. This facility provides the support for arbitrarily scrollable windows. In addition, this facility serves as the root for a variety of interesting high-level tools."
      (:PAR))
     (:DT "Formatted Output")
     (:DD
      "CLIM provides a set of macros and functions that enable programs to produce neatly formatted tabular and graphical displays with very little effort."
      (:PAR))
     (:DT "Context Sensitive Input")
     (:DD "The " (:TERM "presentation type")
      " facility of CLIM provides the ability to associate semantics with output, such that objects may be retrieved later by selecting their displayed representation with the pointer. This "
      (:TERM "sensitivity")
      " comes along automatically and is integrated with the Common Lisp type system. A mechanism for type coercion is also included, providing the basis for powerful user interfaces."
      (:PAR))
     (:DT "Application Building")
     (:DD
      "CLIM provides a set of tools for organizing an application's top-level user interface and command processing loops centered on objects called frames. CLIM provides functionality for laying out frames under arbitrary constraints, managing command menus and/or menu bars, and associating user interface gestures with application commands. Using these tools, application writers can easily and quickly construct user interfaces that can grow flexibly from prototype to delivery."
      (:PAR))
     (:DT "Adaptive Toolkit")
     (:DD
      "CLIM provides a uniform interface to the standard compositional toolkits available in many environments. CLIM defines abstract panes that are analogous to the gadgets or widgets of a toolkit like Motif or OpenLook. CLIM fosters look and feel independence by specifying the interface of these abstract panes in terms of their function and not in terms of the details of their appearance or operation. If an application uses these interfaces, its user interface will adapt to use whatever toolkit is available in the host environment. By using this facility, application programmers can easily construct applications that will automatically conform to a variety of user interface standards. In addition, a portable Lisp-based implementation of the abstract panes is provided."
      (:PAR)))
    (:PAR))
   " "
   (:SECTION :TITLE ("2 " "Conventions") :KIND :CHAPTER :NAME (2 10) " " (:LABEL :NAME "conventions") (:PAR)
    "This chapter describes the conventions used in this specification and in the CLIM software itself." (:PAR) " "
    (:SECTION :TITLE ("2.1 " "Audience, Goals, and Purpose") :KIND :SECTION :NAME (10 2 10) (:PAR)
     "This document, the " (:GROUP (:FONT :FACE :B) "CLIM Release 2 Specification")
     ", is intended for vendors. While it does define the Application Programmer's Interface (API), that is, the functionality that a customer/consumer would use to write an application, it also defines the names and functionality of some internal parts of CLIM. These \"portals\" in implementation space allow one vendor to extend, for example, the output record mechanism and have it work with another vendor's implementation of incremental redisplay. We have attempted to carefully identify the appropriate \"portals\" so that the API can be implemented efficiently, but we have also tried not to overconstrain the specification so that it restricts creativity of implementation or the possibility for extension. This also affects the more sophisticated application writers who want to go a little below the published API but still want portable applications. This document defines which functionality is part of the advertised API, and which is part of the internal protocols."
     (:PAR) "In this document, we refer to three different audiences. A CLIM " (:CONCEPT "user")
     " is a person who uses an application program that was written using CLIM. A CLIM " (:CONCEPT "programmer")
     " is a person who writes application programs using CLIM. A CLIM " (:CONCEPT "implementor")
     " is a programmer who implements CLIM or extends it in some non-trivial way." (:PAR) " ")
    (:SECTION :TITLE ("2.2 " "Package Structure") :KIND :SECTION :NAME (10 2 10) (:PAR)
     "CLIM defines a variety of packages in order to provide its functionality. In general, no symbols except for the symbols in this specification should be added to those packages."
     (:PAR) "The " (:CL "clim-lisp")
     " package is intended to implement as much of the draft X3J13 Common Lisp as possible, independent of the conformance of individual vendors. (When all Lisp vendors implement X3J13 Common Lisp, the "
     (:CL "clim-lisp") " package could be eliminated.) " (:CL "clim-lisp")
     " is the version of Common Lisp in which CLIM is implemented and which the " (:CL "clim-user")
     " package uses instead of " (:CL "common-lisp") ". " (:CL "clim-lisp")
     " contains only exported symbols, and is locked in those implementations that allow package locking." (:PAR)
     (:CL "clim")
     " is the package where the symbols specified in this specification live. It contains only exported symbols and is locked in those implementations that allow package locking."
     (:PAR) (:CL "clim-sys")
     " is the package where useful \"system-like\" functionality lives, including such things as resources and multi-processing primitives. It contains functionality that is not part of Common Lisp, but which is not conceptually the province of CLIM itself. It contains only exported symbols and is locked in those implementations that allow package locking."
     (:PAR)
     "No code is written in any of the above packages, but rather code is written for symbols in the above packages. None of the above use any other packages (in the sense of the "
     (:CL ":use") " option to " (:CL "defpackage") "). A CLIM implementation might define a " (:CL "clim-internals")
     " package that uses each of the above packages, thus getting the definition of Lisp from " (:CL "clim-lisp")
     ". It would then implement the functionality of the symbols in " (:CL "clim") " and " (:CL "clim-sys") " in the "
     (:CL "clim-internals") " package." (:PAR) (:CL "clim-user")
     " is a package that programmers can use if they don't wish to create their own package. It is the CLIM analog of "
     (:CL "common-lisp-user") "." (:PAR) " ")
    (:SECTION :TITLE ("2.3 " "\"Spread\" Point Arguments to Functions " (:LABEL :NAME "spread-vs-point")) :KIND
     :SECTION :NAME (10 2 10) (:PAR) "Many functions that take point arguments come in two forms: "
     (:CONCEPT "structured") " and " (:CONCEPT "spread")
     ". Functions that take structured point arguments take the argument as a single " (:CL "point")
     " object. Functions that take spread point arguments take a pair of arguments that correspond to the " (:MATH "x")
     " and " (:MATH "y") " coordinates of the point." (:PAR)
     "Functions that take spread point arguments, or return spread point values have an asterisk in their name, for example, "
     (:CL "draw-line*") "." (:PAR) " ")
    (:SECTION :TITLE ("2.4 " "Immutability of Objects") :KIND :SECTION :NAME (10 2 10) (:PAR) "Most CLIM objects are "
     (:CONCEPT "immutable")
     ", that is, at the protocol level none of their components can be modified once the object is created. Examples of immutable objects include all of the members of the "
     (:CL "region")
     " classes, colors and opacities, text styles, and line styles. Since immutable objects by definition never change, functions in the CLIM API can safely capture immutable objects without first copying them. This also allows CLIM to cache immutable objects. Constructor functions that return immutable objects are free to either create and return a new object, or return an already existing object."
     (:PAR) "A few CLIM objects are " (:CONCEPT "mutable")
     ". Examples of mutable objects include streams and output records. Some components of mutable objects can be modified once the object has been created, usually via "
     (:CL "setf") " accessors." (:PAR)
     "In CLIM, object immutability is maintained at the class level. Throughout this specification, the immutability or mutability of a class will be explicitly specified."
     (:PAR) "Some immutable classes also allow " (:CONCEPT "interning")
     ". A class is said to be interning if it guarantees that two instances that are equivalent will always be "
     (:CL "eq") ". For example, if the class " (:CL "color") " were interning, calling " (:CL "make-rgb-color")
     " twice with the same arguments would return " (:CL "eq")
     " values. CLIM does not specify that any class is interning, however all immutable classes are allowed to be interning at the discretion of the implementation."
     (:PAR)
     "In some rare cases, CLIM will modify objects that are members of immutable classes. Such objects are referred to as being "
     (:CONCEPT "volatile")
     ". Extreme care must be take with volatile objects. This specification will note whenever some object that is part of the API is volatile."
     (:PAR) " "
     (:SECTION :TITLE ("2.4.1 " "Behavior of Interfaces") :KIND :SUBSECTION :NAME (1 10 2 10) (:PAR)
      "In this specification, any interfaces that take or return mutable objects can be classified in a few different ways."
      (:PAR) "Most functions " (:CONCEPT "do not capture")
      " their mutable input objects, that is, these functions will either not store the objects at all, or will copy any mutable objects before storing them, or perhaps store only some of the components of the objects. Later modifications to those objects will not affect the internal state of CLIM."
      (:PAR) "Some functions " (:CONCEPT "may capture")
      " their mutable input objects. That is, it is unspecified as to whether a CLIM implementation will or will not capture the mutable inputs to some function. For such functions, programmers should assume that these objects will be captured and must not modify these objects capriciously. Furthermore, it is unspecifed what will happen if these objects are later modified."
      (:PAR)
      "Some programmers might choose to create a mutable subclass of an immutable class. If CLIM captures an object that is a member of such a class, it is unspecified what will happen if the programmer later modifies that object. If a programmer passes such an object to a CLIM function that may capture its inputs, he is responsible for either first copying the object or ensuring that the object does not change later."
      (:PAR) "Some functions that return mutable objects are guaranteed to create " (:CONCEPT "fresh outputs")
      ". These objects can be modified without affecting the internal state of CLIM." (:PAR)
      "Functions that return mutable objects that are not fresh objects fall into two categories: those that return "
      (:CONCEPT "read-only state") ", and those that return " (:CONCEPT "read/write state")
      ". If a function returns read-only state, programmers must not modify that object; doing so might corrupt the state of CLIM. If a function returns read/write state, the modification of that object is part of CLIM's interface, and programmers are free to modify the object in ways that \"make sense\"."
      (:PAR) " "))
    (:SECTION :TITLE ("2.5 " "Protocol Classes and Predicates") :KIND :SECTION :NAME (10 2 10) (:PAR)
     "CLIM supplies a set of predicates that can be called on an object to determine whether or not that object satisfies a certain protocol. These predicates can be implemented in one of two ways."
     (:PAR) "The first way is that a class implementing a particular protocol will inherit from a "
     (:CONCEPT "protocol class")
     " that corresponds to that protocol. A protocol class is an \"abstract\" class with no slots and no methods (except perhaps for some default methods), and exists only to indicate that some subclass obeys the protocol. In the case when a class inherits from a protocol class, the predicate could be implemented using "
     (:CL "typep")
     ". All of the CLIM region, design, sheet, and output record classes use this convention. For example, the presentation protocol class and predicate could be implemented in this way:"
     (:PAR)
     (:PRE "
(defclass presentation () ())

(defun presentationp (object)
  (typep object 'presentation))
")
     (:PAR) "Note that in some implementations, it may be more efficient not to use " (:CL "typep")
     ", and instead use a generic function for the predicate. However, simply implementing a method for the predicate that returns "
     (:TERM "true")
     " is not necessarily enough to assert that a class supports that protocol; the class must include the protocol class as a superclass."
     (:PAR) "CLIM always provides at least one \"standard\" instantiable class that implements each protocol." (:PAR)
     "The second way is that a class implementing a particular protocol must simply implement a method for a predicate generic function that returns "
     (:TERM "true") " if and only if that class supports the protocol (otherwise, it returns " (:TERM "false")
     "). Most of the CLIM stream classes use this convention. Protocol classes are not used in these cases because, as in the case of some of the stream classes, the underlying Lisp implementation may not be arranged so as to permit it. For example, the extended input stream protocol might be implemented in this way:"
     (:PAR)
     (:PRE "
(defgeneric extended-input-stream-p (object))

(defmethod extended-input-stream-p ((object t)) nil)

(defmethod extended-input-stream-p ((object basic-extended-input-protocol)) t)

(defmethod extended-input-stream-p
           ((encapsulating-stream standard-encapsulating-stream))
  (with-slots (stream) encapsulating-stream
    (extended-input-stream-p stream)))
")
     (:PAR) "Whenever a class inherits from a protocol class or returns " (:TERM "true")
     " from the protocol predicate, the class must implement methods for all of the generic functions that make up the protocol."
     (:PAR) " ")
    (:SECTION :TITLE ("2.6 " "Specialized Arguments to Generic Functions") :KIND :SECTION :NAME (10 2 10) (:PAR)
     "Unless otherwise stated, this specification uses the following convention for specifying which arguments to generic functions are specialized:"
     (:PAR)
     (:UL
      (:LI "If the generic function is a " (:CL "setf")
       " function, the second argument is the one that is intended to be specialized." (:PAR))
      (:LI "If the generic function is a \"mapping\" function (such as " (:CL "map-over-region-set-regions")
       "), the second argument (the object that specifies what is being mapped over) is the one that is specialized. The first argument (the functional argument) is not intended to be specialized."
       (:PAR))
      (:LI "Otherwise, the first argument is the one that is intended to be specialized. "))
     (:PAR) " ")
    (:SECTION :TITLE ("2.7 " "Multiple Value " (:GROUP (:FONT :FACE :TT) "setf")) :KIND :SECTION :NAME (10 2 10) (:PAR)
     "Some functions in CLIM that return multiple values have " (:CL "setf")
     " functions associated with them. For example, " (:CL "output-record-position")
     " returns the position of an output record as two values that correspond to the " (:MATH "x") " and " (:MATH "y")
     " coordinates. In order to change the position of an output record, the programmer would like to invoke "
     (:CL "(setf output-record-position)") ". Normally however, " (:CL "setf")
     " only takes a single value with which to modify the specified place. CLIM provides a \"multiple value\" version of "
     (:CL "setf")
     " that allows an expression that returns multiple values to be used in updating the specified place. In this specification, this facility will be referred to as "
     (:CL "setf*") " in the guise of function names such as " (:CL "(setf* output-record-position)") ", even though "
     (:CL "setf*") " is not actually a defined form." (:PAR) "For example, the modifying function for "
     (:CL "output-record-position") " might be called in either of the following two ways:" (:PAR)
     (:PRE "
(setf (output-record-position record) (values nx ny))

(setf (output-record-position record1) (output-record-position record2))
")
     (:PAR) "The second form works because " (:CL "output-record-position") " itself returns two values." (:PAR)
     "Some CLIM implementations may not support " (:CL "setf*")
     " due to restrictions imposed by the underlying Lisp implementation. In this case, programmers may use special \"setter\" function instead. In the above example, "
     (:CL "output-record-set-position") " is the \"setter\" function." (:PAR) " ")
    (:SECTION :TITLE ("2.8 " "Sheet, Stream, or Medium Arguments to Macros") :KIND :SECTION :NAME (10 2 10) (:PAR)
     "There are many macros that take a sheet, stream, or medium as one of the arguments, for example, "
     (:CL "with-new-output-record") " and " (:CL "formatting-table")
     ". In CLIM, this argument must be a variable bound to a sheet, stream, or medium; it may not be an arbitrary form that evaluates to a sheet, stream, or medium. "
     (:CL "t") " and sometimes " (:CL "nil")
     " are usually allowed as special cases; this causes the variable to be interpreted as a reference to another stream variable (usually "
     (:CL "*standard-output*") " for output macros, or " (:CL "*standard-input*")
     " for input macros). Note that, while the variable outside the macro form and the variable inside the body share the same name, they cannot be assumed to be the same reference. That is, the macro is free to create a new binding for the variable. Thus, the following code fragment will not necessarily affect the value of "
     (:GROUP (:FONT :FACE :I) "stream") " outside the " (:CL "formatting-table") " form:" (:PAR)
     (:PRE "
(formatting-table (stream)
  (setq stream some-other-stream)
  ...)
")
     (:PAR)
     "Furthermore, for the macros that take a sheet, stream, or medium argument, the position of that variable is always before any forms or other \"inputs\"."
     (:PAR) " ")
    (:SECTION :TITLE ("2.9 " "Macros that Expand into Calls to Advertised Functions") :KIND :SECTION :NAME (10 2 10)
     (:PAR)
     "Some macros that take a \"body\" argument expand into a call to an advertised function that takes a functional argument. This functional argument will execute the suppled body. For a macro named \""
     (:GROUP (:FONT :FACE :I) (:CL "with-") "environment") "\", the function is generally named \""
     (:GROUP (:FONT :FACE :I) (:CL "invoke-with-") "environment") "\". For example, " (:CL "with-drawing-options")
     " might be defined as follows:" (:PAR)
     (:PRE "
(defgeneric invoke-with-drawing-options (medium continuation &key)
  (declare (dynamic-extent continuation)))

(defmacro with-drawing-options ((medium &rest drawing-options) &body body)
  `(flet ((with-drawing-options-body (,medium) ,@body))
     (declare (dynamic-extent #'with-drawing-options-body))
     (invoke-with-drawing-options
       ,medium #'with-drawing-options-body ,@drawing-options)))

(defmethod invoke-with-drawing-options 
           ((medium clx-display-medium) continuation &rest drawing-options)
  (with-drawing-options-merged-into-medium (medium drawing-options)
    (funcall continuation medium)))
")
     (:PAR) " ")
    (:SECTION :TITLE ("2.10 " "Terminology Pertaining to Error Conditions") :KIND :SECTION :NAME (10 2 10) (:PAR)
     "When this specification specifies that it \"is an error\" for some situation to occur, this means that:" (:PAR)
     (:UL (:LI "No valid CLIM program should cause this situation to occur." (:PAR))
      (:LI
       "If this situation does occur, the effects and results are undefined as far as adherence to the CLIM specification is concerned."
       (:PAR))
      (:LI
       "CLIM implementations are not required to detect such an error, although implementations are encouraged to provide such error detection whenever it is reasonable to do so. "))
     (:PAR) "When this specification specifies that some argument \"must be a " (:TERM "type")
     "\" or uses the phrase \"the " (:TERM "type") " " (:GROUP (:FONT :FACE :I) "argument")
     "\", this means that it is an error if the argument is not of the specified type. CLIM implementations are encouraged, but not required, to generate an argument type error for these situations."
     (:PAR) "When this specification says that \"an error is signalled\" in some situation, this means that:" (:PAR)
     (:UL
      (:LI "If the situation occurs, an error will be signalled using either " (:CL "error") " or " (:CL "cerror") "."
       (:PAR))
      (:LI "Valid CLIM programs may rely on the fact that an error will be signalled." (:PAR))
      (:LI "Every CLIM implementation is required to detect such an error. "))
     (:PAR)
     "When this specification says that \"a condition is signalled\" in some situation, this is just like \"an error is signalled\" with the exception that the condition will be signalled using "
     (:CL "signal") " instead of " (:CL "error") "." (:PAR)))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part II: " "Geometry Substrate") :NAME (10) " " " "
   (:SECTION :TITLE ("3 " "Regions") :KIND :CHAPTER :NAME (3 10) " " (:LABEL :NAME "regions") (:PAR)
    "CLIM provides definitions for a variety of geometric objects, including points, lines, elliptical arcs, regions, and transformations. Both the graphics and windowing modules use the same set of geometric objects and functions. In this section, we describe regions, points, and the basic region classes. Transformations will be described in Chapter "
    (:REF :NAME "transforms") "." (:PAR)
    "Most of these objects are described as if they are implemented using standard classes. However, this need not be the case. In particular, they may be implemented using structure classes, and some classes may exist only to name a place in the hierarchy---all members of such a class will be instances of that class's subclasses. The most important concern is that these classes must allow specializing generic functions."
    (:PAR)
    "The coordinate system in which the geometric objects reside is an abstract, continuous coordinate system. This abstract coordinate system is converted into \"real world\" coordinates only during operations such as rendering one of the objects on a display device."
    (:PAR)
    "Angles are measured in radians. Following standard conventions, when an angle is measured relative to a given line, a positive angle indicates an angle counter-clockwise from the line in the plane. When the angle from the positive "
    (:MATH "x") " axis to the positive " (:MATH "y") " axis is positive (that is, the positive " (:MATH "y")
    " axis is counter-clockwise from the positive " (:MATH "x") " axis), the coordinate system is said to be "
    (:CONCEPT "right-handed") ". When this angle is negative, the coordinate system is said to be "
    (:CONCEPT "left-handed") ". Thus, the cartesian coordinate system with " (:MATH "x")
    " increasing to the right and " (:MATH "y") " increasing upward is right-handed. A coordinate system with "
    (:MATH "y")
    " increasing down is left-handed. (By default, CLIM streams are left handed, but no such default exists for sheets in general.)"
    (:PAR) " "
    (:SECTION :TITLE ("3.1 " "General Regions") :KIND :SECTION :NAME (2 3 10) (:PAR) "A " (:CONCEPT "region")
     " is an object that denotes a set of mathematical points in the plane. Regions include their boundaries, that is, they are closed. Regions have infinite resolution."
     (:PAR) "A " (:CONCEPT "bounded region")
     " is a region that contains at least one point and for which there exists a number, " (:MATH "d")
     ", called the region's diameter, such that if " (:MATH "p" (:RM "1")) " and " (:MATH "p" (:RM "2"))
     " are points in the region, the distance between " (:MATH "p" (:RM "1")) " and " (:MATH "p" (:RM "2"))
     " is always less than or equal to " (:MATH "d") "." (:PAR) "An " (:CONCEPT "unbounded region")
     " either contains no points or contains points arbitrarily far apart." (:PAR)
     "Another way to describe a region is that it maps every " (:MATH "(x,y)") " pair into either " (:TERM "true")
     " or " (:TERM "false") " (meaning member or not a member, respectively, of the region). Later, in Chapter "
     (:REF :NAME "designs") ", we will generalize a region to something called a " (:CONCEPT "design")
     " that maps every point " (:MATH "(x,y)") " into color and opacity values." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "region")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a set of points. This includes both bounded and unbounded regions. This is a subclass of "
      (:CL "design") " (see Chapter " (:REF :NAME "color") ")." (:PAR)
      "If you want to create a new class that behaves like a region, it should be a subclass of " (:CL "region")
      ". All instantiable subclasses of " (:CL "region") " must obey the region protocol. " (:PAR)
      "There is no general constructor called " (:CL "make-region")
      " because of the impossibility of a uniform way to specify the arguments to such a function." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "regionp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "region")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "path")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR) "The protocol class "
      (:CL "path") " denotes bounded regions that have " (:CONCEPT "dimensionality")
      " 1 (that is, have length). It is a subclass of " (:CL "region") " and " (:CL "bounding-rectangle")
      ". If you want to create a new class that behaves like a path, it should be a subclass of " (:CL "path")
      ". All instantiable subclasses of " (:CL "path") " must obey the path protocol. " (:PAR) "Constructing a "
      (:CL "path") " object with no length (via " (:CL "make-line*") ", for example) may canonicalize it to "
      (:CL "+nowhere+") "." (:PAR)
      "Some rendering models support the constructing of areas by filling a closed path. In this case, the path needs a direction associated with it. Since CLIM does not currently support the path-filling model, paths are directionless."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pathp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "path") ", otherwise returns "
      (:TERM "false") "." (:PAR) "Note that constructing a " (:CL "path") " object with no length (such as calling "
      (:CL "make-line") " with two coincident points), for example) may canonicalize it to " (:CL "+nowhere+") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "area")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR) "The protocol class "
      (:CL "area") " denotes bounded regions that have dimensionality 2 (that is, have area). It is a subclass of "
      (:CL "region") " and " (:CL "bounding-rectangle")
      ". If you want to create a new class that behaves like an area, it should be a subclass of " (:CL "area")
      ". All instantiable subclasses of " (:CL "area") " must obey the area protocol. " (:PAR)
      "Note that constructing an " (:CL "area") " object with no area (such as calling " (:CL "make-rectangle")
      " with two coincident points), for example) may canonicalize it to " (:CL "+nowhere+") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "areap")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an " (:TERM "area") ", otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "coordinate")) :PARAMS ((:I)) :KIND ("Type")) (:PAR)
      "The type that represents a coordinate. This must either be " (:CL "t") ", or a subtype of " (:CL "real")
      ". CLIM implementations may use a more specific subtype of " (:CL "real") ", such as " (:CL "single-float")
      ", for reasons of efficiency." (:PAR) "All of the specific region classes and subclasses of "
      (:CL "bounding-rectangle")
      " will use this type to store their coordinates. However, the constructor functions for the region classes and for bounding rectangles must accept numbers of any type and coerce them to "
      (:CL "coordinate") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "coordinate")) :PARAMS ((:I "n")) :KIND ("Function")) (:PAR) "Coerces the number "
      (:GROUP (:FONT :FACE :I) "n") " to be a coordinate." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "+everywhere+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+nowhere+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR) (:CL "+everywhere+")
      " is the region that includes all the points on the two-dimensional infinite drawing plane. " (:CL "+nowhere+")
      " is the empty region, the opposite of " (:CL "+everywhere+") "." (:PAR) " ")
     (:SECTION :TITLE ("3.1.1 " "The Region Predicate Protocol") :KIND :SUBSECTION :NAME (2 2 3 10) (:PAR)
      "The following generic functions comprise the region predicate protocol. All classes that are subclasses of "
      (:CL "region") " must either inherit or implement methods for these generic functions." (:PAR) "The methods for "
      (:CL "region-equal") ", " (:CL "region-contains-region-p") ", and " (:CL "region-intersects-region-p")
      " will typically specialize both the " (:GROUP (:FONT :FACE :I) "region1") " and "
      (:GROUP (:FONT :FACE :I) "region2") " arguments." (:PAR) " "
      (:DEFUN (:SIGNATURE :NAME ((:CL "region-equal")) :PARAMS ((:I "region1 region2")) :KIND ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the two " (:TERM "regions") " " (:GROUP (:FONT :FACE :I) "region1")
       " and " (:GROUP (:FONT :FACE :I) "region2") " contain exactly the same set of points, otherwise returns "
       (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "region-contains-region-p")) :PARAMS ((:I "region1 region2")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if all points in the " (:TERM "region") " "
       (:GROUP (:FONT :FACE :I) "region2") " are members of the " (:TERM "region") " "
       (:GROUP (:FONT :FACE :I) "region1") ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "region-contains-position-p")) :PARAMS ((:I "region x y")) :KIND ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the point at " (:MATH "(x,y)") " is contained in the " (:TERM "region")
       " " (:GROUP (:FONT :FACE :I) "region") ", otherwise returns " (:TERM "false")
       ". Since regions in CLIM are closed, this must return " (:TERM "true") " if the point at " (:MATH "(x,y)")
       " is on the region's boundary. CLIM implementations are permitted to return different non-" (:CL "nil")
       " values depending on whether the point is completely inside the region or is on the border." (:PAR)
       (:CL "region-contains-position-p") " is a special case of " (:CL "region-contains-region-p")
       " in which the region is the point " (:MATH "(x,y)") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "region-intersects-region-p")) :PARAMS ((:I "region1 region2")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "false") " if " (:CL "region-intersection") " of the two " (:TERM "regions") " "
       (:GROUP (:FONT :FACE :I) "region1") " and " (:GROUP (:FONT :FACE :I) "region2") " would be " (:CL "+nowhere+")
       ", otherwise returns " (:TERM "true") "." (:PAR) " "))
     (:SECTION :TITLE ("3.1.2 " "Region Composition Protocol") :KIND :SUBSECTION :NAME (2 2 3 10) (:PAR)
      "Region composition is not always equivalent to simple set operations. Instead, composition attempts to return an object that has the same dimensionality as one of its arguments. If this is not possible, then the result is defined to be an empty region, which is canonicalized to "
      (:CL "+nowhere+") ". (The exact details of this are specified with each function.)" (:PAR)
      "Sometimes, composition of regions can produce a result that is not a simple contiguous region. For example, "
      (:CL "region-union")
      " of two rectangular regions might not be a single rectangle. In order to support cases like this, CLIM has the concept of a "
      (:CONCEPT "region set") ", which is an object that represents one or more " (:CL "region")
      " objects related by some region operation, usually a union. CLIM provides standard classes to cover the cases of region union, intersection, and difference."
      (:PAR)
      "Some CLIM implementations might only implement a subset of full region composition. Because of the importance of rectangular regions and region sets that are the union of rectangular regions, every CLIM implementation is required to fully support all functions that use regions for those cases. (For example, CLIM implementations must be able do clipping and repainting on region sets composed entirely of axis-aligned rectangles.) If a CLIM implementation does not support some functions on non-rectangular region sets (for example, clipping), it must signal an error when an unsupported case is encountered; the exact details of this depend on the particular CLIM implementation."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "region-set")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that represents a region set; a subclass of " (:CL "region") " and "
       (:CL "bounding-rectangle") "." (:PAR)
       "In addition to the three classes below, there may be other instantiable subclasses of " (:CL "region-set")
       " that represent special cases, for instance, some implementations might have a " (:CL "standard-rectangle-set")
       " class that represents the union of several axis-aligned rectangles." (:PAR)
       "Members of this class are immutable. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "region-set-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "region set")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-region-union")) :PARAMS ((:I)) :KIND ("Class"))
       (:SIGNATURE :NAME ((:CL "standard-region-intersection")) :PARAMS ((:I)) :KIND ("Class"))
       (:SIGNATURE :NAME ((:CL "standard-region-difference")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "These three instantiable classes respectively implement the union, intersection, and differences of regions. Implementations may, but are not required to, take advantage of the commutativity and associativity of union and intersection in order to \"collapse\" complicated region sets into simpler ones."
       (:PAR)
       "Region sets that are composed entirely of axis-aligned rectangles must be canonicalized into either a single rectangle or a union of rectangles. Furthermore, the rectangles in the union must not overlap each other."
       (:PAR)
       " The following generic functions comprise the region composition protocol. All classes that are subclasses of "
       (:CL "region") " must implement methods for these generic functions." (:PAR) "The methods for "
       (:CL "region-union") ", " (:CL "region-intersection") ", and " (:CL "region-difference")
       " will typically specialize both the " (:GROUP (:FONT :FACE :I) "region1") " and "
       (:GROUP (:FONT :FACE :I) "region2") " arguments." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "region-set-regions")) :PARAMS
        ((:I "region " (:GROUP (:FONT :FACE :TT) "&key ") "normalize")) :KIND ("Generic Function"))
       (:PAR) "Returns a sequence of the regions in the " (:TERM "region set") " " (:GROUP (:FONT :FACE :I) "region")
       ". " (:GROUP (:FONT :FACE :I) "region") " can be either a " (:TERM "region set")
       " or a \"simple\" region, in which case the result is simply a sequence of one element: "
       (:GROUP (:FONT :FACE :I) "region")
       ". This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR)
       "For the case of region sets that are unions of axis-aligned rectangles, the rectangles returned by "
       (:CL "region-set-regions") " are guaranteed not to overlap." (:PAR) "If " (:GROUP (:FONT :FACE :I) "normalize")
       " is supplied, it must be either " (:CL ":x-banding") " or " (:CL ":y-banding") ". If it is " (:CL ":x-banding")
       " and all the regions in " (:GROUP (:FONT :FACE :I) "region")
       " are axis-aligned rectangles, the result is normalized by merging adjacent rectangles with banding done in the "
       (:MATH "x") " direction. If it is " (:CL ":y-banding") " and all the regions in "
       (:GROUP (:FONT :FACE :I) "region") " are rectangles, the result is normalized with banding done in the "
       (:MATH "y")
       " direction. Normalizing a region set that is not composed entirely of axis-aligned rectangles using x- or y-banding causes CLIM to signal the "
       (:CL "region-set-not-rectangular") " error." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-region-set-regions")) :PARAMS
        ((:I "function region " (:GROUP (:FONT :FACE :TT) "&key ") "normalize")) :KIND ("Generic Function"))
       (:PAR) "Calls " (:GROUP (:FONT :FACE :I) "function") " on each region in the " (:TERM "region set") " "
       (:GROUP (:FONT :FACE :I) "region") ". This is often more efficient than calling " (:CL "region-set-regions")
       ". " (:GROUP (:FONT :FACE :I) "function") " is a function of one argument, a region; it has dynamic extent. "
       (:GROUP (:FONT :FACE :I) "region") " can be either a " (:TERM "region set")
       " or a \"simple\" region, in which case " (:GROUP (:FONT :FACE :I) "function") " is called once on "
       (:GROUP (:FONT :FACE :I) "region") " itself. " (:GROUP (:FONT :FACE :I) "normalize") " is as for "
       (:CL "region-set-regions") "." (:PAR) " "
       (:FIGURE :NUMBER "3.1" :CAPTION ("Normalization of rectangular region sets.") " "
        (:CENTER (:IMG :SRC "region-normalization.png")) "  ")
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "region-union")) :PARAMS ((:I "region1 region2")) :KIND ("Generic Function"))
       (:PAR) "Returns a region that contains all points that are in either of the " (:TERM "regions") " "
       (:GROUP (:FONT :FACE :I) "region1") " or " (:GROUP (:FONT :FACE :I) "region2")
       " (possibly with some points removed in order to satisfy the dimensionality rule). The result of "
       (:CL "region-union") " always has dimensionality that is the maximum dimensionality of "
       (:GROUP (:FONT :FACE :I) "region1") " and " (:GROUP (:FONT :FACE :I) "region2")
       ". For example, the union of a path and an area produces an area; the union of two paths is a path." (:PAR)
       (:CL "region-union") " will return either a simple region, a region set, or a member of the class "
       (:CL "standard-region-union") "." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "region-intersection")) :PARAMS ((:I "region1 region2")) :KIND ("Generic Function"))
       (:PAR) "Returns a region that contains all points that are in both of the " (:TERM "regions") " "
       (:GROUP (:FONT :FACE :I) "region1") " and " (:GROUP (:FONT :FACE :I) "region2")
       " (possibly with some points removed in order to satisfy the dimensionality rule). The result of "
       (:CL "region-intersection") " has dimensionality that is the minimum dimensionality of "
       (:GROUP (:FONT :FACE :I) "region1") " and " (:GROUP (:FONT :FACE :I) "region2") ", or is " (:CL "+nowhere+")
       ". For example, the intersection of two areas is either another area or " (:CL "+nowhere+")
       "; the intersection of two paths is either another path or " (:CL "+nowhere+")
       "; the intersection of a path and an area produces the path clipped to stay inside of the area." (:PAR)
       (:CL "region-intersection") " will return either a simple region or a member of the class "
       (:CL "standard-region-intersection") "." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "region-difference")) :PARAMS ((:I "region1 region2")) :KIND ("Generic Function"))
       (:PAR) "Returns a region that contains all points in the " (:TERM "region") " "
       (:GROUP (:FONT :FACE :I) "region1") " that are not in the " (:TERM "region") " "
       (:GROUP (:FONT :FACE :I) "region2")
       " (possibly plus additional boundary points to make the result closed). The result of "
       (:CL "region-difference") " has the same dimensionality as " (:GROUP (:FONT :FACE :I) "region1") ", or is "
       (:CL "+nowhere+")
       ". For example, the difference of an area and a path produces the same area; the difference of a path and an area produces the path clipped to stay outside of the area."
       (:PAR) (:CL "region-difference") " will return either a simple region, a region set, or a member of the class "
       (:CL "standard-region-difference") "." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR) " "
       (:FIGURE :NUMBER "3.2" :CAPTION ("Examples of region union, intersection, and difference.") " "
        (:CENTER (:IMG :SRC "region-composition.png")) "  ")
       (:PAR) " ")))
    (:SECTION :TITLE ("3.2 " "Other Region Types") :KIND :SECTION :NAME (2 3 10) (:PAR)
     "The other types of regions are points, polylines, polygons, elliptical arcs, and ellipses. All of these region types are closed under affine transformations."
     (:PAR) (:GROUP (:FONT :FACE :B) "Major issue: ") " "
     (:GROUP (:FONT :FACE :SL) "There is a proposal to remove the " (:CL "polygon") ", " (:CL "polyline") ", "
      (:CL "line") ", " (:CL "ellipse") ", and " (:CL "elliptical-arc")
      " classes, since they are only of limited utility, and CLIM itself doesn't use the classes at all. The advantage of removing these classes is that both the spec and CLIM itself become a little simpler, and there are fewer cases of the region protocol to implement. However, removing these classes results in a geometric model that is no longer closed (in the mathematical sense). This lack of closure makes it difficult to specify the design-based drawing model. Furthermore, these are intuitive objects that are used by a small, but important, class of applications, and some people feel that CLIM should relieve programmers from having to implement these classes for himself or herself."
      (:PAR)
      "The advocates of of removing these classes also propose removing the design-based drawing model. In this case, a more consistent proposal is to remove all of the geometric classes, including "
      (:CL "point") " and " (:CL "rectangle") "." (:PAR)
      "Again, the opposing point of view believes that the power and flexibility of the design-based drawing model does not justify the removal of any of these classes. One counter-proposal is to require CLIM not to use any of the extended region classes internally, and to move the implementation of the extended region classes to a separately loadable module (via "
      (:CL "provide") " and " (:CL "require") "). --- SWM, York")
     (:PAR)
     (:FIGURE :NUMBER "3.3" :CAPTION ("The class structure for all regions.") " "
      (:CENTER (:IMG :SRC "region-structure.png")) "  ")
     (:PAR) " "
     (:SECTION :TITLE ("3.2.1 " "Points") :KIND :SUBSECTION :NAME (5 2 3 10) (:PAR) "A " (:CONCEPT "point")
      " is a mathematical point in the plane, designated by its coordinates, which are a pair of real numbers (where a real number is defined as either an integer, a ratio, or a floating point number). Points have neither area nor length (that is, they have dimensionality 0)."
      (:PAR) "Note well that a point is " (:GROUP (:FONT :FACE :SL) "not")
      " a pixel; CLIM models a drawing plane with continuous coordinates. This is discussed in more detail in Chapter "
      (:REF :NAME "graphics") "." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "point")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to a mathematical point. This is a subclass of " (:CL "region") " and "
       (:CL "bounding-rectangle")
       ". If you want to create a new class that behaves like a point, it should be a subclass of " (:CL "point")
       ". All instantiable subclasses of " (:CL "point") " must obey the point protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "pointp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "point")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-point")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "An instantiable class that implements a point. This is a subclass of " (:CL "point")
       ". This is the class that " (:CL "make-point") " instantiates. Members of this class are immutable. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "make-point")) :PARAMS ((:I "x y")) :KIND ("Function")) (:PAR)
       "Returns an object of class " (:CL "standard-point") " whose coordinates are " (:GROUP (:FONT :FACE :I) "x")
       " and " (:GROUP (:FONT :FACE :I) "y") ". " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       " must be real numbers." (:PAR) " ")
      (:SECTION :TITLE ("3.2.1.1 " "The Point Protocol") :KIND :SUBSUBSECTION :NAME (1 5 2 3 10) (:PAR)
       "The following generic functions comprise the point API. Only " (:CL "point-position")
       " is in the point protocol, that is, all classes that are subclasses of " (:CL "point")
       " must implement methods for " (:CL "point-position") ", but need not implement methods for " (:CL "point-x")
       " and " (:CL "point-y") "." (:PAR)
       (:DEFUN (:SIGNATURE :NAME ((:CL "point-position")) :PARAMS ((:I "point")) :KIND ("Generic Function")) (:PAR)
        "Returns both the " (:MATH "x") " and " (:MATH "y") " coordinates of the point "
        (:GROUP (:FONT :FACE :I) "point") " as two values." (:PAR))
       (:DEFUN (:SIGNATURE :NAME ((:CL "point-x")) :PARAMS ((:I "point")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "point-y")) :PARAMS ((:I "point")) :KIND ("Generic Function")) (:PAR) "Returns the "
        (:MATH "x") " or " (:MATH "y") " coordinate of the " (:TERM "point") " " (:GROUP (:FONT :FACE :I) "point")
        ", respectively. CLIM will supply default methods for " (:CL "point-x") " and " (:CL "point-y")
        " on the protocol class " (:CL "point") " that are implemented by calling " (:CL "point-position") "." (:PAR)
        " ")))
     (:SECTION :TITLE ("3.2.2 " "Polygons and Polylines") :KIND :SUBSECTION :NAME (5 2 3 10) (:PAR) "A "
      (:CONCEPT "polyline")
      " is a path that consists of one or more line segments joined consecutively at their end-points." (:PAR)
      "Polylines that have the end-point of their last line segment coincident with the start-point of their first line segment are called "
      (:CONCEPT "closed") "; this use of the term \"closed\" should not be confused with closed sets of points." (:PAR)
      "A " (:CONCEPT "polygon") " is an area bounded by a closed polyline." (:PAR)
      "If the boundary of a polygon intersects itself, the odd-even winding-rule defines the polygon: a point is inside the polygon if a ray from the point to infinity crosses the boundary an odd number of times."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "polyline")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to a polyline. This is a subclass of " (:CL "path")
       ". If you want to create a new class that behaves like a polyline, it should be a subclass of " (:CL "polyline")
       ". All instantiable subclasses of " (:CL "polyline") " must obey the polyline protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "polylinep")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "polyline")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-polyline")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "An instantiable class that implements a polyline. This is a subclass of " (:CL "polyline")
       ". This is the class that " (:CL "make-polyline") " and " (:CL "make-polyline*")
       " instantiate. Members of this class are immutable. " (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-polyline")) :PARAMS
        ((:I "point-seq " (:GROUP (:FONT :FACE :TT) "&key ") "closed")) :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "make-polyline*")) :PARAMS
        ((:I "coord-seq " (:GROUP (:FONT :FACE :TT) "&key ") "closed")) :KIND ("Function"))
       (:PAR) "Returns an object of class " (:CL "standard-polyline")
       " consisting of the segments connecting each of the points in " (:GROUP (:FONT :FACE :I) "point-seq")
       " (or the points represented by the coordinate pairs in " (:GROUP (:FONT :FACE :I) "coord-seq") "). "
       (:GROUP (:FONT :FACE :I) "point-seq") " is a sequence of " (:TERM "points") "; "
       (:GROUP (:FONT :FACE :I) "coord-seq")
       " is a sequence of coordinate pairs, which are real numbers. It is an error if "
       (:GROUP (:FONT :FACE :I) "coord-seq") " does not contain an even number of elements." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "closed") " is " (:TERM "true")
       ", then the segment connecting the first point and the last point is included in the polyline. The default for "
       (:GROUP (:FONT :FACE :I) "closed") " is " (:TERM "false") "." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "polygon")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to a mathematical polygon. This is a subclass of " (:CL "area")
       ". If you want to create a new class that behaves like a polygon, it should be a subclass of " (:CL "polygon")
       ". All instantiable subclasses of " (:CL "polygon") " must obey the polygon protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "polygonp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "polygon")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-polygon")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "An instantiable class that implements a polygon. This is a subclass of " (:CL "polygon")
       ". This is the class that " (:CL "make-polygon") " and " (:CL "make-polygon*")
       " instantiate. Members of this class are immutable. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "make-polygon")) :PARAMS ((:I "point-seq")) :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "make-polygon*")) :PARAMS ((:I "coord-seq")) :KIND ("Function")) (:PAR)
       "Returns an object of class " (:CL "standard-polygon")
       " consisting of the area contained in the boundary that is specified by the segments connecting each of the points in "
       (:GROUP (:FONT :FACE :I) "point-seq") " (or the points represented by the coordinate pairs in "
       (:GROUP (:FONT :FACE :I) "coord-seq") "). " (:GROUP (:FONT :FACE :I) "point-seq") " is a sequence of "
       (:TERM "points") "; " (:GROUP (:FONT :FACE :I) "coord-seq")
       " is a sequence of coordinate pairs, which are real numbers. It is an error if "
       (:GROUP (:FONT :FACE :I) "coord-seq") " does not contain an even number of elements." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR) " ")
      (:SECTION :TITLE ("3.2.2.1 " "The Polygon and Polyline Protocol") :KIND :SUBSUBSECTION :NAME (1 5 2 3 10) (:PAR)
       "The following generic functions comprise the polygon and polyline protocol. All classes that are subclasses of either "
       (:CL "polygon") " or " (:CL "polyline")
       " must implement methods for these generic functions. Some of the functions below take an argument named "
       (:GROUP (:FONT :FACE :I) "polygon-or-polyline") "; this argument may be either a " (:TERM "polygon") " or a "
       (:TERM "polyline") "." (:PAR)
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "polygon-points")) :PARAMS ((:I "polygon-or-polyline")) :KIND ("Generic Function"))
        (:PAR) "Returns a sequence of points that specify the segments in "
        (:GROUP (:FONT :FACE :I) "polygon-or-polyline")
        ". This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR))
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "map-over-polygon-coordinates")) :PARAMS ((:I "function polygon-or-polyline")) :KIND
         ("Generic Function"))
        (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all of the coordinates of the vertices of "
        (:GROUP (:FONT :FACE :I) "polygon-or-polyline") ". " (:GROUP (:FONT :FACE :I) "function")
        " is a function of two arguments, the " (:MATH "x") " and " (:MATH "y")
        " coordinates of the vertex; it has dynamic extent." (:PAR))
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "map-over-polygon-segments")) :PARAMS ((:I "function polygon-or-polyline")) :KIND
         ("Generic Function"))
        (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to the segments that compose "
        (:GROUP (:FONT :FACE :I) "polygon-or-polyline") ". " (:GROUP (:FONT :FACE :I) "function")
        " is a function of four arguments, the " (:MATH "x") " and " (:MATH "y")
        " coordinates of the start of the segment, and the " (:MATH "x") " and " (:MATH "y")
        " coordinates of the end of the segment; it has dynamic extent. When " (:CL "map-over-polygon-segments")
        " is called on a closed polyline, it will call " (:GROUP (:FONT :FACE :I) "function")
        " on the segment that connects the last point back to the first point." (:PAR))
       (:DEFUN (:SIGNATURE :NAME ((:CL "polyline-closed")) :PARAMS ((:I "polyline")) :KIND ("Generic Function")) (:PAR)
        "Returns " (:TERM "true") " if the polyline " (:GROUP (:FONT :FACE :I) "polyline")
        " is closed, otherwise returns " (:TERM "false") ". This function need be implemented only for "
        (:TERM "polylines") ", not for " (:TERM "polygons") "." (:PAR) " ")))
     (:SECTION :TITLE ("3.2.3 " "Lines") :KIND :SUBSECTION :NAME (5 2 3 10) (:PAR)
      "A line is a polyline consisting of a single segment." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "line")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to a mathematical line segment, that is, a polyline with only a single segment. This is a subclass of "
       (:CL "polyline") ". If you want to create a new class that behaves like a line, it should be a subclass of "
       (:CL "line") ". All instantiable subclasses of " (:CL "line") " must obey the line protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "linep")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
       (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "line") ", otherwise returns "
       (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-line")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "An instantiable class that implements a line segment. This is a subclass of " (:CL "line")
       ". This is the class that " (:CL "make-line") " and " (:CL "make-line*")
       " instantiate. Members of this class are immutable. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "make-line")) :PARAMS ((:I "start-point end-point")) :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "make-line*")) :PARAMS ((:I "start-x start-y end-x end-y")) :KIND ("Function")) (:PAR)
       "Returns an object of class " (:CL "standard-line") " that connects the two " (:TERM "points") " "
       (:GROUP (:FONT :FACE :I) "start-point") " and " (:GROUP (:FONT :FACE :I) "end-point") " (or the positions ("
       (:GROUP (:FONT :FACE :I) "start-x") "," (:GROUP (:FONT :FACE :I) "start-y") ") and ("
       (:GROUP (:FONT :FACE :I) "end-x") "," (:GROUP (:FONT :FACE :I) "end-y") "))." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR) " ")
      (:SECTION :TITLE ("3.2.3.1 " "The Line Protocol") :KIND :SUBSUBSECTION :NAME (1 5 2 3 10) (:PAR)
       "The following generic functions comprise the line API. Only " (:CL "line-start-point*") " and "
       (:CL "line-end-point*") " are in the line protocol, that is, all classes that are subclasses of " (:CL "line")
       " must implement methods for " (:CL "line-start-point*") " and " (:CL "line-end-point*")
       ", but need not implement methods for " (:CL "line-start-point") " and " (:CL "line-end-point") "." (:PAR)
       (:DEFUN (:SIGNATURE :NAME ((:CL "line-start-point*")) :PARAMS ((:I "line")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "line-end-point*")) :PARAMS ((:I "line")) :KIND ("Generic Function")) (:PAR)
        "Returns the starting or ending point, respectively, of the " (:TERM "line") " "
        (:GROUP (:FONT :FACE :I) "line") " as two real numbers representing the coordinates of the point." (:PAR))
       (:DEFUN (:SIGNATURE :NAME ((:CL "line-start-point")) :PARAMS ((:I "line")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "line-end-point")) :PARAMS ((:I "line")) :KIND ("Generic Function")) (:PAR)
        "Returns the starting or ending point of the " (:TERM "line") " " (:GROUP (:FONT :FACE :I) "line")
        ", respectively." (:PAR) "CLIM will supply default methods for " (:CL "line-start-point") " and "
        (:CL "line-end-point") " on the protocol class " (:CL "line") " that are implemented by calling "
        (:CL "line-start-point*") " and " (:CL "line-end-point*") "." (:PAR) " ")))
     (:SECTION :TITLE ("3.2.4 " "Rectangles") :KIND :SUBSECTION :NAME (5 2 3 10) " " (:LABEL :NAME "rect") (:PAR)
      "Rectangles whose edges are parallel to the coordinate axes are a special case of polygon that can be specified completely by four real numbers ("
      (:GROUP (:FONT :FACE :I) "x1") "," (:GROUP (:FONT :FACE :I) "y1") "," (:GROUP (:FONT :FACE :I) "x2") ","
      (:GROUP (:FONT :FACE :I) "y2") "). They are " (:GROUP (:FONT :FACE :SL) "not")
      " closed under general affine transformations (although they are closed under rectilinear transformations)."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "rectangle")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to a mathematical rectangle, that is, rectangular polygons whose sides are parallel to the coordinate axes. This is a subclass of "
       (:CL "polygon") ". If you want to create a new class that behaves like a rectangle, it should be a subclass of "
       (:CL "rectangle") ". All instantiable subclasses of " (:CL "rectangle") " must obey the rectangle protocol. "
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "rectanglep")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "rectangle")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-rectangle")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "An instantiable class that implements an axis-aligned rectangle. This is a subclass of " (:CL "rectangle")
       ". This is the class that " (:CL "make-rectangle") " and " (:CL "make-rectangle*")
       " instantiate. Members of this class are immutable. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "make-rectangle")) :PARAMS ((:I "point1 point2")) :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "make-rectangle*")) :PARAMS ((:I "x1 y1 x2 y2")) :KIND ("Function")) (:PAR)
       "Returns an object of class " (:CL "standard-rectangle")
       " whose edges are parallel to the coordinate axes. One corner is at the " (:TERM "point") " "
       (:GROUP (:FONT :FACE :I) "point1") " (or the position (" (:GROUP (:FONT :FACE :I) "x1") ","
       (:GROUP (:FONT :FACE :I) "y1") ")) and the opposite corner is at the " (:TERM "point") " "
       (:GROUP (:FONT :FACE :I) "point2") " (or the position (" (:GROUP (:FONT :FACE :I) "x2") ","
       (:GROUP (:FONT :FACE :I) "y2") ")). There are no ordering constraints among " (:GROUP (:FONT :FACE :I) "point1")
       " and " (:GROUP (:FONT :FACE :I) "point2") " (or " (:GROUP (:FONT :FACE :I) "x1") " and "
       (:GROUP (:FONT :FACE :I) "x2") ", and " (:GROUP (:FONT :FACE :I) "y1") " and " (:GROUP (:FONT :FACE :I) "y2")
       ")." (:PAR)
       "Most CLIM implementations will choose to represent rectangles in the most efficient way, such as by storing the coordinates of two opposing corners of the rectangle. Because this representation is not sufficient to represent the result of arbitrary transformations of arbitrary rectangles, CLIM is allowed to return a polygon as the result of such a transformation. (The most general class of transformations that is guaranteed to always turn a rectangle into another rectangle is the class of transformations that satisfy "
       (:CL "rectilinear-transformation-p") ".)" (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR) " ")
      (:SECTION :TITLE ("3.2.4.1 " "The Rectangle Protocol") :KIND :SUBSUBSECTION :NAME (1 5 2 3 10) (:PAR)
       "The following generic functions comprise the rectangle API. Only " (:CL "rectangle-edges*")
       " is in the rectangle protocol, that is, all classes that are subclasses of " (:CL "rectangle")
       " must implement methods for " (:CL "rectangle-edges*")
       ", but need not implement methods for the remaining functions." (:PAR)
       (:DEFUN (:SIGNATURE :NAME ((:CL "rectangle-edges*")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function"))
        (:PAR) "Returns the coordinates of the minimum " (:MATH "x") " and " (:MATH "y") " and maximum " (:MATH "x")
        " and " (:MATH "y") " of the rectangle " (:GROUP (:FONT :FACE :I) "rectangle") " as four values, "
        (:GROUP (:FONT :FACE :I) "min-x") ", " (:GROUP (:FONT :FACE :I) "min-y") ", " (:GROUP (:FONT :FACE :I) "max-x")
        ", and " (:GROUP (:FONT :FACE :I) "max-y") "." (:PAR))
       (:DEFUN (:SIGNATURE :NAME ((:CL "rectangle-min-point")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "rectangle-max-point")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function")) (:PAR)
        "Returns the min point and max point of the " (:TERM "rectangle") " " (:GROUP (:FONT :FACE :I) "rectangle")
        ", respectively. The position of a rectangle is specified by its min point." (:PAR)
        "CLIM will supply default methods for " (:CL "rectangle-min-point") " and " (:CL "rectangle-max-point")
        " on the protocol class " (:CL "rectangle") " that are implemented by calling " (:CL "rectangle-edges*") "."
        (:PAR) " ")
       (:DEFUN (:SIGNATURE :NAME ((:CL "rectangle-min-x")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "rectangle-min-y")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "rectangle-max-x")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "rectangle-max-y")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function")) (:PAR)
        "Returns (respectively) the minimum " (:MATH "x") " and " (:MATH "y") " coordinate and maximum " (:MATH "x")
        " and " (:MATH "y") " coordinate of the " (:TERM "rectangle") " " (:GROUP (:FONT :FACE :I) "rectangle") "."
        (:PAR) "CLIM will supply default methods for these four generic functions on the protocol class "
        (:CL "rectangle") " that are implemented by calling " (:CL "rectangle-edges*") "." (:PAR) " ")
       (:DEFUN (:SIGNATURE :NAME ((:CL "rectangle-width")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "rectangle-height")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function"))
        (:SIGNATURE :NAME ((:CL "rectangle-size")) :PARAMS ((:I "rectangle")) :KIND ("Generic Function")) (:PAR)
        (:CL "rectangle-width") " returns the width of the " (:TERM "rectangle") " "
        (:GROUP (:FONT :FACE :I) "rectangle") ", which is the difference between the maximum " (:MATH "x")
        " and its minimum " (:MATH "x") ". " (:CL "rectangle-height")
        " returns the height, which is the difference between the maximum " (:MATH "y") " and its minimum " (:MATH "y")
        ". " (:CL "rectangle-size") " returns two values, the width and the height." (:PAR)
        "CLIM will supply default methods for these four generic functions on the protocol class " (:CL "rectangle")
        " that are implemented by calling " (:CL "rectangle-edges*") "." (:PAR) " ")))
     (:SECTION :TITLE ("3.2.5 " "Ellipses and Elliptical Arcs") :KIND :SUBSECTION :NAME (5 2 3 10) (:PAR) "An "
      (:CONCEPT "ellipse")
      " is an area that is the outline and interior of an ellipse. Circles are special cases of ellipses." (:PAR) "An "
      (:CONCEPT "elliptical arc")
      " is a path consisting of all or a portion of the outline of an ellipse. Circular arcs are special cases of elliptical arcs."
      (:PAR)
      "An ellipse is specified in a manner that is easy to transform, and treats all ellipses on an equal basis. An ellipse is specified by its center point and two vectors that describe a bounding parallelogram of the ellipse. The bounding parallelogram is made by adding and subtracting the vectors from the the center point in the following manner:"
      (:PAR)
      (:TABULAR
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP "  " "  "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-top: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :SL) (:MATH "x") " coordinate") " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP " " (:GROUP (:FONT :FACE :SL) (:MATH "y") " coordinate") " ")))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP "  " "  Center of Ellipse "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-top: 1px solid;" :COLSPAN
         1 (:GROUP " " (:MATH "x" (:SUB "c")) " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP " " (:MATH "y" (:SUB "c")) " ")))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP "  " "  Vectors "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-top: 1px solid;" :COLSPAN
         1 (:GROUP " " (:MATH "dx" (:SUB (:RM "1"))) " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP " " (:MATH "dy" (:SUB (:RM "1"))) " ")))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP "  "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP " " (:MATH "dx" (:SUB (:RM "2"))) " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;"
         :COLSPAN 1 (:GROUP " " (:MATH "dy" (:SUB (:RM "2"))) " ")))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP "  " "  Corners of Parallelogram "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-top: 1px solid;" :COLSPAN
         1 (:GROUP " " (:MATH "x" (:SUB "c") " + dx" (:SUB (:RM "1")) " + dx" (:SUB (:RM "2"))) " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP " " (:MATH "y" (:SUB "c") " + dy" (:SUB (:RM "1")) " + dy" (:SUB (:RM "2"))) " ")))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP "  "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP " " (:MATH "x" (:SUB "c") " + dx" (:SUB (:RM "1")) " - dx" (:SUB (:RM "2"))) " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;"
         :COLSPAN 1 (:GROUP " " (:MATH "y" (:SUB "c") " + dy" (:SUB (:RM "1")) " - dy" (:SUB (:RM "2"))) " ")))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP "  "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP " " (:MATH "x" (:SUB "c") " - dx" (:SUB (:RM "1")) " - dx" (:SUB (:RM "2"))) " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;"
         :COLSPAN 1 (:GROUP " " (:MATH "y" (:SUB "c") " - dy" (:SUB (:RM "1")) " - dy" (:SUB (:RM "2"))) " ")))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "border-bottom: 1px solid;padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP "  "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "border-bottom: 1px solid;padding: 0 .5ex; "
         :COLSPAN 1 (:GROUP " " (:MATH "x" (:SUB "c") " - dx" (:SUB (:RM "1")) " + dx" (:SUB (:RM "2"))) " "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "border-bottom: 1px solid;padding: 0 .5ex; border-right: 1px solid;" :COLSPAN 1
         (:GROUP " " (:MATH "y" (:SUB "c") " - dy" (:SUB (:RM "1")) " + dy" (:SUB (:RM "2"))) " "))))
      (:PAR)
      "Note that several different parallelograms specify the same ellipse. One parallelogram is bound to be a rectangle---the vectors will be perpendicular and correspond to the semi-axes of the ellipse."
      (:PAR)
      (:FIGURE :NUMBER "3.4" :CAPTION ("Different vectors may specify the same ellipse.") " "
       (:CENTER (:IMG :SRC "different-ellipses.png")) "  ")
      (:PAR)
      "The special case of an ellipse with its axes aligned with the coordinate axes can be obtained by setting "
      (:MATH "dx" (:SUB (:RM "2")) " = dy" (:SUB (:RM "1")) " = " (:RM "0")) " or "
      (:MATH "dx" (:SUB (:RM "1")) " = dy" (:SUB (:RM "2")) " = " (:RM "0")) "." (:PAR) " "
      (:DEFUN (:SIGNATURE :NAME ((:CL "ellipse")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to a mathematical ellipse. This is a subclass of " (:CL "area")
       ". If you want to create a new class that behaves like an ellipse, it should be a subclass of " (:CL "ellipse")
       ". All instantiable subclasses of " (:CL "ellipse") " must obey the ellipse protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "ellipsep")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an " (:TERM "ellipse")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-ellipse")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "An instantiable class that implements an ellipse. This is a subclass of " (:CL "ellipse")
       ". This is the class that " (:CL "make-ellipse") " and " (:CL "make-ellipse*")
       " instantiate. Members of this class are immutable. " (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-ellipse")) :PARAMS
        ((:I "center-point  radius-1-dx radius-1-dy radius-2-dx radius-2-dy  " (:GROUP (:FONT :FACE :TT) "&key ")
          "start-angle end-angle"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "make-ellipse*")) :PARAMS
        ((:I "center-x center-y  radius-1-dx radius-1-dy radius-2-dx radius-2-dy  " (:GROUP (:FONT :FACE :TT) "&key ")
          "start-angle end-angle"))
        :KIND ("Function"))
       (:PAR) "Returns an object of class " (:CL "standard-ellipse") ". The center of the ellipse is at the "
       (:TERM "point") " " (:GROUP (:FONT :FACE :I) "center-point") " (or the position ("
       (:GROUP (:FONT :FACE :I) "center-x") "," (:GROUP (:FONT :FACE :I) "center-y") "))." (:PAR) "Two vectors, ("
       (:GROUP (:FONT :FACE :I) "radius-1-dx") "," (:GROUP (:FONT :FACE :I) "radius-1-dy") ") and ("
       (:GROUP (:FONT :FACE :I) "radius-2-dx") "," (:GROUP (:FONT :FACE :I) "radius-2-dy")
       ") specify the bounding parallelogram of the ellipse as explained above. All of the radii are real numbers. If the two vectors are collinear, the ellipse is not well-defined and the "
       (:CL "ellipse-not-well-defined")
       " error will be signalled. The special case of an ellipse with its axes aligned with the coordinate axes can be obtained by setting both "
       (:GROUP (:FONT :FACE :I) "radius-1-dy") " and " (:GROUP (:FONT :FACE :I) "radius-2-dx") " to 0." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "start-angle") " or " (:GROUP (:FONT :FACE :I) "end-angle")
       " are supplied, the ellipse is the \"pie slice\" area swept out by a line from the center of the ellipse to a point on the boundary as the boundary point moves from the angle "
       (:GROUP (:FONT :FACE :I) "start-angle") " to " (:GROUP (:FONT :FACE :I) "end-angle")
       ". Angles are measured counter-clockwise with respect to the positive " (:MATH "x") " axis. If "
       (:GROUP (:FONT :FACE :I) "end-angle") " is supplied, the default for " (:GROUP (:FONT :FACE :I) "start-angle")
       " is " (:MATH (:RM "0")) "; if " (:GROUP (:FONT :FACE :I) "start-angle") " is supplied, the default for "
       (:GROUP (:FONT :FACE :I) "end-angle") " is " (:MATH (:RM "2") (:ENTITY :NAME "pi"))
       "; if neither is supplied then the region is a full ellipse and the angles are meaningless." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "elliptical-arc")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to a mathematical elliptical arc. This is a subclass of " (:CL "path")
       ". If you want to create a new class that behaves like an elliptical arc, it should be a subclass of "
       (:CL "elliptical-arc") ". All instantiable subclasses of " (:CL "elliptical-arc")
       " must obey the elliptical arc protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "elliptical-arc-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an " (:TERM "elliptical arc")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-elliptical-arc")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "An instantiable class that implements an elliptical arc. This is a subclass of " (:CL "elliptical-arc")
       ". This is the class that " (:CL "make-elliptical-arc") " and " (:CL "make-elliptical-arc*")
       " instantiate. Members of this class are immutable. " (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-elliptical-arc")) :PARAMS
        ((:I "center-point  radius-1-dx radius-1-dy radius-2-dx radius-2-dy  " (:GROUP (:FONT :FACE :TT) "&key ")
          "start-angle end-angle"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "make-elliptical-arc*")) :PARAMS
        ((:I "center-x center-y  radius-1-dx radius-1-dy radius-2-dx radius-2-dy  " (:GROUP (:FONT :FACE :TT) "&key ")
          "start-angle end-angle"))
        :KIND ("Function"))
       (:PAR) "Returns an object of class " (:CL "standard-elliptical-arc") ". The center of the ellipse is at the "
       (:TERM "point") " " (:GROUP (:FONT :FACE :I) "center-point") " (or the position ("
       (:GROUP (:FONT :FACE :I) "center-x") "," (:GROUP (:FONT :FACE :I) "center-y") "))." (:PAR) "Two vectors, ("
       (:GROUP (:FONT :FACE :I) "radius-1-dx") "," (:GROUP (:FONT :FACE :I) "radius-1-dy") ") and ("
       (:GROUP (:FONT :FACE :I) "radius-2-dx") "," (:GROUP (:FONT :FACE :I) "radius-2-dy")
       "), specify the bounding parallelogram of the ellipse as explained above. All of the radii are real numbers. If the two vectors are collinear, the ellipse is not well-defined and the "
       (:CL "ellipse-not-well-defined")
       " error will be signalled. The special case of an elliptical arc with its axes aligned with the coordinate axes can be obtained by setting both "
       (:GROUP (:FONT :FACE :I) "radius-1-dy") " and " (:GROUP (:FONT :FACE :I) "radius-2-dx") " to 0." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "start-angle") " and " (:GROUP (:FONT :FACE :I) "start-angle")
       " are supplied, the arc is swept from " (:GROUP (:FONT :FACE :I) "start-angle") " to "
       (:GROUP (:FONT :FACE :I) "end-angle") ". Angles are measured counter-clockwise with respect to the positive "
       (:MATH "x") " axis. If " (:GROUP (:FONT :FACE :I) "end-angle") " is supplied, the default for "
       (:GROUP (:FONT :FACE :I) "start-angle") " is " (:MATH (:RM "0")) "; if " (:GROUP (:FONT :FACE :I) "start-angle")
       " is supplied, the default for " (:GROUP (:FONT :FACE :I) "end-angle") " is "
       (:MATH (:RM "2") (:ENTITY :NAME "pi"))
       "; if neither is supplied then the region is a closed elliptical path and the angles are meaningless." (:PAR)
       "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
       (:PAR) " ")
      (:SECTION :TITLE ("3.2.5.1 " "The Ellipse and Elliptical Arc Protocol") :KIND :SUBSUBSECTION :NAME (1 5 2 3 10)
       (:PAR) "The following functions apply to both ellipses and elliptical arcs. In all cases, the name "
       (:GROUP (:FONT :FACE :I) "elliptical-object") " means that the argument may be an " (:TERM "ellipse") " or an "
       (:TERM "elliptical arc")
       ". These generic functions comprise the ellipse protocol. All classes that are subclasses of either "
       (:CL "ellipse") " or " (:CL "elliptical-arc") " must implement methods for these functions." (:PAR)
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "ellipse-center-point*")) :PARAMS ((:I "elliptical-object")) :KIND
         ("Generic Function"))
        (:PAR) "Returns the center point of " (:GROUP (:FONT :FACE :I) "elliptical-object")
        " as two values representing the coordinate pair." (:PAR))
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "ellipse-center-point")) :PARAMS ((:I "elliptical-object")) :KIND ("Generic Function"))
        (:PAR) "Returns the center point of " (:GROUP (:FONT :FACE :I) "elliptical-object") "." (:PAR)
        (:CL "ellipse-center-point")
        " is part of the ellipse API, but not part of the ellipse protocol. CLIM will supply default methods for "
        (:CL "ellipse-center-point") " on the protocol classes " (:CL "ellipse") " and " (:CL "elliptical-arc")
        " that are implemented by calling " (:CL "ellipse-center-point*") "." (:PAR))
       (:DEFUN (:SIGNATURE :NAME ((:CL "ellipse-radii")) :PARAMS ((:I "elliptical-object")) :KIND ("Generic Function"))
        (:PAR) "Returns four values corresponding to the two radius vectors of "
        (:GROUP (:FONT :FACE :I) "elliptical-arc")
        ". These values may be canonicalized in some way, and so may not be the same as the values passed to the constructor function."
        (:PAR))
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "ellipse-start-angle")) :PARAMS ((:I "elliptical-object")) :KIND ("Generic Function"))
        (:PAR) "Returns the start angle of " (:GROUP (:FONT :FACE :I) "elliptical-object") ". If "
        (:GROUP (:FONT :FACE :I) "elliptical-object") " is a full ellipse or closed path then "
        (:CL "ellipse-start-angle") " will return " (:CL "nil")
        "; otherwise the value will be a number greater than or equal to zero, and less than "
        (:MATH (:RM "2") (:ENTITY :NAME "pi")) "." (:PAR))
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "ellipse-end-angle")) :PARAMS ((:I "elliptical-object")) :KIND ("Generic Function"))
        (:PAR) "Returns the end angle of " (:GROUP (:FONT :FACE :I) "elliptical-object") ". If "
        (:GROUP (:FONT :FACE :I) "elliptical-object") " is a full ellipse or closed path then "
        (:CL "ellipse-end-angle") " will return " (:CL "nil")
        "; otherwise the value will be a number greater than zero, and less than or equal to "
        (:MATH (:RM "2") (:ENTITY :NAME "pi")) "." (:PAR))))))
   " "
   (:SECTION :TITLE ("4 " "Bounding Rectangles") :KIND :CHAPTER :NAME (3 10) " " (:LABEL :NAME "bboxes") (:PAR)
    (:SECTION :TITLE ("4.1 " "Bounding Rectangles") :KIND :SECTION :NAME (1 3 10) (:PAR)
     "Every bounded region has a derived " (:CONCEPT "bounding rectangle")
     ", which is a rectangular region whose sides are parallel to the coordinate axes. Therefore, every bounded region participates in the bounding rectangle protocol. The bounding rectangle for a region is the smallest rectangle that contains every point in the region. However, the bounding rectangle may contain additional points as well. Unbounded regions do not have a bounding rectangle and do not participate in the bounding rectangle protocol. Other objects besides bounded regions participate in the bounding rectangle protocol, such as sheets and output records."
     (:PAR)
     "The coordinate system in which the bounding rectangle is maintained depends on the context. For example, the coordinates of the bounding rectangle of a sheet are expressed in the sheet's parent's coordinate system. For output records, the coordinates of the bounding rectangle are maintained in the coordinate system of the stream with which the output record is associated."
     (:PAR)
     "Note that the bounding rectangle of a transformed region is not in general the same as the result of transforming the bounding rectangle of a region, as shown in Figure "
     (:REF :NAME "output-record-bbox") ". For transformations that satisfy " (:CL "rectilinear-transformation-p")
     ", the following equality holds. For all other transformations, it does not hold." (:PAR)
     (:PRE "
(region-equal
  (transform-region transformation (bounding-rectangle region))
  (bounding-rectangle (transform-region transformation region)))
")
     (:PAR)
     (:FIGURE :NUMBER "4.1" :CAPTION
      ((:LABEL :NAME "output-record-bbox") " The bounding rectangle of an output record.") " "
      (:CENTER (:IMG :SRC "bounding-box.png")) "  ")
     (:PAR)
     "CLIM uses bounding rectangles for a variety of purposes. For example, repainting of windows is driven from the bounding rectangle of the window's viewport, intersected with a \"damage\" region. The formatting engines used by "
     (:CL "formatting-table") " and " (:CL "formatting-graph")
     " operate on the bounding rectangles of the output records in the output. Bounding rectangles are also used internally by CLIM to achieve greater efficiency. For instance, when performing hit detection to see if the pointer is within the region of an output record, CLIM first checks to see if the pointer is within the bounding rectangle of the output record."
     (:PAR)
     "Note that the bounding rectangle for an output record may have a different size depending on the medium on which the output record is rendered. Consider the case of rendering text on different output devices; the font chosen for a particular text style may vary considerably in size from one device to another."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "bounding-rectangle")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that represents a bounding rectangle. If you want to create a new class that behaves like a bounding rectangle, it should be a subclass of "
      (:CL "bounding-rectangle") ". All instantiable subclasses of " (:CL "bounding-rectangle")
      " must obey the bounding rectangle protocol. " (:PAR) "Note that bounding rectangles are not a subclass of "
      (:CL "rectangle") ", nor even a subclass of " (:CL "region")
      ". This is because, in general, bounding rectangles do not obey the region protocols. However, all bounded regions and sheets that obey the bounding rectangle protocol are subclasses of "
      (:CL "bounding-rectangle") "." (:PAR)
      "Bounding rectangles are immutable, but since they reflect the live state of such mutable objects as sheets and output records, bounding rectangles are volatile. Therefore, programmers must not depend on the bounding rectangle associated with a mutable object remaining constant."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "bounding-rectangle-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "bounding rectangle")
      " (that is, supports the bounding rectangle protocol), otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-bounding-rectangle")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "An instantiable class that implements a bounding rectangle. This is a subclass of both "
      (:CL "bounding-rectangle") " and " (:CL "rectangle")
      ", that is, standard bounding rectangles obey the rectangle protocol." (:PAR) (:CL "make-bounding-rectangle")
      " returns an object of this class." (:PAR)
      "The representation of bounding rectangles in CLIM is chosen to be efficient. CLIM will probably represent such rectangles by storing the coordinates of two opposing corners of the rectangle, namely, the \"min point\" and the \"max point\". Because this representation is not sufficient to represent the result of arbitrary transformations of arbitrary rectangles, CLIM is allowed to return a polygon as the result of such a transformation. (The most general class of transformations that is guaranteed to always turn a rectangle into another rectangle is the class of transformations that satisfy "
      (:CL "rectilinear-transformation-p") ".)" (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-bounding-rectangle")) :PARAMS ((:I "x1 y1 x2 y2")) :KIND ("Function"))
      (:PAR) "Returns an object of the class " (:CL "standard-bounding-rectangle") " with the edges specified by "
      (:GROUP (:FONT :FACE :I) "x1") ", " (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and "
      (:GROUP (:FONT :FACE :I) "y2") ", which must be real numbers." (:PAR) (:GROUP (:FONT :FACE :I) "x1") ", "
      (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and " (:GROUP (:FONT :FACE :I) "y2")
      " are \"canonicalized\" in the following way. The min point of the rectangle has an " (:MATH "x")
      " coordinate that is the smaller of " (:GROUP (:FONT :FACE :I) "x1") " and " (:GROUP (:FONT :FACE :I) "x2")
      " and a " (:MATH "y") " coordinate that is the smaller of " (:GROUP (:FONT :FACE :I) "y1") " and "
      (:GROUP (:FONT :FACE :I) "y2") ". The max point of the rectangle has an " (:MATH "x")
      " coordinate that is the larger of " (:GROUP (:FONT :FACE :I) "x1") " and " (:GROUP (:FONT :FACE :I) "x2")
      " and a " (:MATH "y") " coordinate that is the larger of " (:GROUP (:FONT :FACE :I) "y1") " and "
      (:GROUP (:FONT :FACE :I) "y2") ". (Therefore, in a right-handed coordinate system the canonicalized values of "
      (:GROUP (:FONT :FACE :I) "x1") ", " (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and "
      (:GROUP (:FONT :FACE :I) "y2")
      " correspond to the left, top, right, and bottom edges of the rectangle, respectively.)" (:PAR)
      "This function returns fresh objects that may be modified. " (:PAR) " ")
     (:SECTION :TITLE ("4.1.1 " "The Bounding Rectangle Protocol") :KIND :SUBSECTION :NAME (2 1 3 10) (:PAR)
      "The following generic function comprises the bounding rectangle protocol. All classes that participate in this protocol (including all subclasses of "
      (:CL "region") " that are bounded regions) must implement a method for " (:CL "bounding-rectangle*") "." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "bounding-rectangle*")) :PARAMS ((:I "region")) :KIND ("Generic Function"))
       (:PAR) "Returns the bounding rectangle of " (:GROUP (:FONT :FACE :I) "region")
       " as four real numbers specifying the " (:MATH "x") " and " (:MATH "y") " coordinates of the min point and the "
       (:MATH "x") " and " (:MATH "y") " coordinates of the max point of the rectangle. The argument "
       (:GROUP (:FONT :FACE :I) "region")
       " must be either a bounded region (such as a line or an ellipse) or some other object that obeys the bounding rectangle protocol, such as a sheet or an output record."
       (:PAR) "The four returned values " (:GROUP (:FONT :FACE :I) "min-x") ", " (:GROUP (:FONT :FACE :I) "min-y") ", "
       (:GROUP (:FONT :FACE :I) "max-x") ", and " (:GROUP (:FONT :FACE :I) "max-y") " will satisfy the inequalities "
       (:TABULAR
        (:TR
         (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP "minx" (:ENTITY :NAME "le") "maxx")))
        (:TR
         (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP "miny" (:ENTITY :NAME "le") "maxy"))))
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "bounding-rectangle")) :PARAMS ((:I "region")) :KIND ("Generic Function")) (:PAR)
       "Returns the bounding rectangle of " (:GROUP (:FONT :FACE :I) "region") " as an object that is a subclass of "
       (:CL "rectangle") " (described in Section " (:REF :NAME "rect") "). The argument "
       (:GROUP (:FONT :FACE :I) "region")
       " must be either a bounded region (such as a line or an ellipse) or some other object that obeys the bounding rectangle protocol, such as a sheet or an output record."
       (:PAR) "It is unspecified whether " (:CL "bounding-rectangle")
       " will or will not create a new object each time it is called. Many CLIM implementations will cache the bounding rectangle for sheets and output records. The implication of this is that, since bounding rectangles are volatile, programmers should depend on the object returned by "
       (:CL "bounding-rectangle") " remaining constant." (:PAR) (:CL "bounding-rectangle")
       " is part of the bounding rectangle API, but not part of the bounding rectangle protocol. CLIM will supply a default method for "
       (:CL "bounding-rectangle") " on the protocol class " (:CL "bounding-rectangle")
       " that is implemented by calling " (:CL "bounding-rectangle*") "." (:PAR) " "))
     (:SECTION :TITLE ("4.1.2 " "Bounding Rectangle Convenience Functions") :KIND :SUBSECTION :NAME (2 1 3 10) (:PAR)
      "The functions described below are part of the bounding rectangle API, but are not part of the bounding rectangle protocol. They are provided as a convenience to programmers who wish to specialize classes that participate in the bounding rectangle protocol, but do not complicate the task of those programmers who define their own types (such as sheet classes) that participate in this protocol."
      (:PAR) "CLIM will supply default methods for all of these generic functions on the protocol class "
      (:CL "bounding-rectangle") " that are implemented by calling " (:CL "bounding-rectangle*") "." (:PAR) " "
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-bounding-rectangle*")) :PARAMS
        ((:I "(min-x min-y max-x max-y) region " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Binds " (:GROUP (:FONT :FACE :I) "min-x") ", " (:GROUP (:FONT :FACE :I) "min-y") ", "
       (:GROUP (:FONT :FACE :I) "max-x") ", and " (:GROUP (:FONT :FACE :I) "max-y")
       " to the edges of the bounding rectangle of " (:GROUP (:FONT :FACE :I) "region") ", and then executes "
       (:GROUP (:FONT :FACE :I) "body") " in that context. The argument " (:GROUP (:FONT :FACE :I) "region")
       " must be either a bounded region (such as a line or an ellipse) or some other object that obeys the bounding rectangle protocol, such as a sheet or an output record."
       (:PAR) "The arguments " (:GROUP (:FONT :FACE :I) "min-x") ", " (:GROUP (:FONT :FACE :I) "min-y") ", "
       (:GROUP (:FONT :FACE :I) "max-x") ", and " (:GROUP (:FONT :FACE :I) "max-y") " are not evaluated. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
       (:CL "with-bounding-rectangle*") " must be implemented by calling " (:CL "bounding-rectangle*") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "bounding-rectangle-position")) :PARAMS ((:I "region")) :KIND ("Generic Function"))
       (:PAR) "Returns the position of the bounding rectangle of " (:GROUP (:FONT :FACE :I) "region")
       ". The position of a bounding rectangle is specified by its min point." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "bounding-rectangle-min-x")) :PARAMS ((:I "region")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "bounding-rectangle-min-y")) :PARAMS ((:I "region")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "bounding-rectangle-max-x")) :PARAMS ((:I "region")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "bounding-rectangle-max-y")) :PARAMS ((:I "region")) :KIND ("Generic Function")) (:PAR)
       "Returns (respectively) the " (:MATH "x") " and " (:MATH "y") " coordinates of the min point and the "
       (:MATH "x") " and " (:MATH "y") " coordinate of the max point of the bounding rectangle of "
       (:GROUP (:FONT :FACE :I) "region") ". The argument " (:GROUP (:FONT :FACE :I) "region")
       " must be either a bounded region or some other object that obeys the bounding rectangle protocol." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "bounding-rectangle-width")) :PARAMS ((:I "region")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "bounding-rectangle-height")) :PARAMS ((:I "region")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "bounding-rectangle-size")) :PARAMS ((:I "region")) :KIND ("Generic Function")) (:PAR)
       "Returns the width, height, or size (as two values, the width and height) of the bounding rectangle of "
       (:GROUP (:FONT :FACE :I) "region") ", respectively. The argument " (:GROUP (:FONT :FACE :I) "region")
       " must be either a bounded region or some other object that obeys the bounding rectangle protocol." (:PAR)
       "The width of a bounding rectangle is the difference between its maximum " (:MATH "x")
       " coordinate and its minimum " (:MATH "x") " coordinate. The height is the difference between the maximum "
       (:MATH "y") " coordinate and its minimum " (:MATH "y") " coordinate." (:PAR)))))
   " "
   (:SECTION :TITLE ("5 " "Affine Transformations") :KIND :CHAPTER :NAME (3 10) " " (:LABEL :NAME "transforms") (:PAR)
    "An " (:CONCEPT "affine transformation")
    " is a mapping from one coordinate system onto another that preserves straight lines. In other words, if you take a number of points that fall on a straight line and apply an affine transformation to their coordinates, the transformed coordinates will describe a straight line in the new coordinate system. General affine transformations include all the sorts of transformations that CLIM uses, namely, translations, scaling, rotations, and reflections."
    (:PAR) " "
    (:SECTION :TITLE ("5.1 " "Transformations") :KIND :SECTION :NAME (3 3 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "transformation")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class of all transformations. There are one or more subclasses of " (:CL "transformation")
      " with implementation-dependent names that implement transformations. The exact names of these classes is explicitly unspecified. If you want to create a new class that behaves like a transformation, it should be a subclass of "
      (:CL "transformation") ". All instantiable subclasses of " (:CL "transformation")
      " must obey the transformation protocol. " (:PAR)
      "All of the instantiable transformation classes provided by CLIM are immutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "transformationp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "transformation")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "+identity-transformation+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "An instance of a transformation that is guaranteed to be an identity transformation, that is, the transformation that \"does nothing\"."
      (:PAR) " ")
     (:SECTION :TITLE ("5.1.1 " "Transformation Conditions") :KIND :SUBSECTION :NAME (1 3 3 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "transformation-error")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
       "The class that is the superclass of the following three conditions. This class is a subclass of " (:CL "error")
       "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "transformation-underspecified")) :PARAMS ((:I)) :KIND ("Error Condition"))
       (:PAR) "The error that is signalled when " (:CL "make-3-point-transformation")
       " is given three collinear image points. This condition will handle the " (:CL ":points")
       " initarg, which is used to supply the points that are in error." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "reflection-underspecified")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
       "The error that is signalled when " (:CL "make-reflection-transformation")
       " is given two coincident points. This condition will handle the " (:CL ":points")
       " initarg, which is used to supply the points that are in error." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "singular-transformation")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
       "The error that is signalled when " (:CL "invert-transformation")
       " is called on a singular transformation, that is, a transformation that has no inverse. This condition will handle the "
       (:CL ":transformation") " initarg, which is used to supply the transformation that is singular." (:PAR) " ")))
    (:SECTION :TITLE ("5.2 " "Transformation Constructors") :KIND :SECTION :NAME (3 3 10) (:PAR)
     "The following transformation constructors do not capture any of their inputs. The constructors all create objects that are subclasses of "
     (:CL "transformation") "." (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-translation-transformation")) :PARAMS ((:I "translation-x translation-y")) :KIND
       ("Function"))
      (:PAR)
      "A translation is a transformation that preserves length, angle, and orientation of all geometric entities."
      (:PAR) (:CL "make-translation-transformation") " returns a transformation that translates all points by "
      (:GROUP (:FONT :FACE :I) "translation-x") " in the " (:MATH "x") " direction and "
      (:GROUP (:FONT :FACE :I) "translation-y") " in the " (:MATH "y") " direction. "
      (:GROUP (:FONT :FACE :I) "translation-x") " and " (:GROUP (:FONT :FACE :I) "translation-y")
      " must be real numbers." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-rotation-transformation")) :PARAMS
       ((:I "angle " (:GROUP (:FONT :FACE :TT) "&optional ") "origin")) :KIND ("Function"))
      (:SIGNATURE :NAME ((:CL "make-rotation-transformation*")) :PARAMS
       ((:I "angle " (:GROUP (:FONT :FACE :TT) "&optional ") "origin-x origin-y")) :KIND ("Function"))
      (:PAR)
      "A rotation is a transformation that preserves length and angles of all geometric entities. Rotations also preserve one point (the origin) and the distance of all entities from that point."
      (:PAR) (:CL "make-rotation-transformation") " returns a transformation that rotates all points by "
      (:GROUP (:FONT :FACE :I) "angle") " (which is a real number indicating an angle in radians) around the point "
      (:GROUP (:FONT :FACE :I) "origin") ". If " (:GROUP (:FONT :FACE :I) "origin")
      " is supplied it must be a point; if not supplied it defaults to " (:MATH "(" (:RM "0") "," (:RM "0") ")") ". "
      (:GROUP (:FONT :FACE :I) "origin-x") " and " (:GROUP (:FONT :FACE :I) "origin-y")
      " must be real numbers, and default to " (:MATH (:RM "0")) "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-scaling-transformation")) :PARAMS
       ((:I "scale-x scale-y " (:GROUP (:FONT :FACE :TT) "&optional ") "origin")) :KIND ("Function"))
      (:SIGNATURE :NAME ((:CL "make-scaling-transformation*")) :PARAMS
       ((:I "scale-x scale-y " (:GROUP (:FONT :FACE :TT) "&optional ") "origin-x origin-y")) :KIND ("Function"))
      (:PAR)
      "There is no single definition of a scaling transformation. Transformations that preserve all angles and multiply all lengths by the same factor (preserving the \"shape\" of all entities) are certainly scaling transformations. However, scaling is also used to refer to transformations that scale distances in the "
      (:MATH "x") " direction by one amount and distances in the " (:MATH "y") " direction by another amount." (:PAR)
      (:CL "make-scaling-transformation") " returns a transformation that multiplies the " (:MATH "x")
      "-coordinate distance of every point from " (:GROUP (:FONT :FACE :I) "origin") " by "
      (:GROUP (:FONT :FACE :I) "scale-x") " and the " (:MATH "y") "-coordinate distance of every point from "
      (:GROUP (:FONT :FACE :I) "origin") " by " (:GROUP (:FONT :FACE :I) "scale-y") ". "
      (:GROUP (:FONT :FACE :I) "scale-x") " and " (:GROUP (:FONT :FACE :I) "scale-y") " must be real numbers. If "
      (:GROUP (:FONT :FACE :I) "origin") " is supplied it must be a point; if not supplied it defaults to "
      (:MATH "(" (:RM "0") "," (:RM "0") ")") ". " (:GROUP (:FONT :FACE :I) "origin-x") " and "
      (:GROUP (:FONT :FACE :I) "origin-y") " must be real numbers, and default to " (:MATH (:RM "0")) "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-reflection-transformation")) :PARAMS ((:I "point1 point2")) :KIND ("Function"))
      (:SIGNATURE :NAME ((:CL "make-reflection-transformation*")) :PARAMS ((:I "x1 y1 x2 y2")) :KIND ("Function"))
      (:PAR)
      "A reflection is a transformation that preserves lengths and magnitudes of angles, but changes the sign (or \"handedness\") of angles. If you think of the drawing plane on a transparent sheet of paper, a reflection is a transformation that \"turns the paper over\"."
      (:PAR) (:CL "make-reflection-transformation")
      " returns a transformation that reflects every point through the line passing through the " (:TERM "points") " "
      (:GROUP (:FONT :FACE :I) "point1") " and " (:GROUP (:FONT :FACE :I) "point2") " (or through the positions "
      (:MATH "(x" (:RM "1") ",y" (:RM "1") ")") " and " (:MATH "(x" (:RM "2") ",y" (:RM "2") ")")
      " in the case of the spread version)." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-transformation")) :PARAMS ((:I "mxx mxy myx myy tx ty")) :KIND ("Function"))
      (:PAR) "Returns a general transformation whose effect is: "
      (:TABULAR
       (:TR
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "x" (:SUP (:ENTITY :NAME "prime")) " = "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "m" (:SUB "xx") "x + m" (:SUB "xy") "y + t" (:SUB "x"))))
       (:TR
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "y" (:SUP (:ENTITY :NAME "prime")) " = "))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "m" (:SUB "yx") "x + m" (:SUB "yy") "y + t" (:SUB "y")))))
      " where " (:MATH "x") " and " (:MATH "y") " are the coordinates of a point before the transformation and "
      (:MATH "x" (:SUP (:ENTITY :NAME "prime"))) " and " (:MATH "y" (:SUP (:ENTITY :NAME "prime")))
      " are the coordinates of the corresponding point after." (:PAR) "All of the arguments to "
      (:CL "make-transformation") " must be real numbers." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-3-point-transformation")) :PARAMS
       ((:I "point-1 point-2 point-3 point-1-image point-2-image point-3-image")) :KIND ("Function"))
      (:PAR) "Returns a transformation that takes " (:TERM "points") " " (:GROUP (:FONT :FACE :I) "point-1") " into "
      (:GROUP (:FONT :FACE :I) "point-1-image") ", " (:GROUP (:FONT :FACE :I) "point-2") " into "
      (:GROUP (:FONT :FACE :I) "point-2-image") " and " (:GROUP (:FONT :FACE :I) "point-3") " into "
      (:GROUP (:FONT :FACE :I) "point-3-image")
      ". Three non-collinear points and their images under the transformation are enough to specify any affine transformation."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "point-1") ", " (:GROUP (:FONT :FACE :I) "point-2") " and "
      (:GROUP (:FONT :FACE :I) "point-3") " are collinear, the " (:CL "transformation-underspecified")
      " error will be signalled. If " (:GROUP (:FONT :FACE :I) "point-1-image") ", "
      (:GROUP (:FONT :FACE :I) "point-2-image") " and " (:GROUP (:FONT :FACE :I) "point-3-image")
      " are collinear, the resulting transformation will be singular (that is, will have no inverse) but this is not an error."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-3-point-transformation*")) :PARAMS
       ((:I "x1 y1 x2 y2 x3 y3 x1-image y1-image x2-image y2-image x3-image y3-image")) :KIND ("Function"))
      (:PAR) "Returns a transformation that takes the points at the positions (" (:GROUP (:FONT :FACE :I) "x1") ","
      (:GROUP (:FONT :FACE :I) "y1") ") into (" (:GROUP (:FONT :FACE :I) "x1-image") ","
      (:GROUP (:FONT :FACE :I) "y1-image") "), (" (:GROUP (:FONT :FACE :I) "x2") "," (:GROUP (:FONT :FACE :I) "y2")
      ") into (" (:GROUP (:FONT :FACE :I) "x2-image") "," (:GROUP (:FONT :FACE :I) "y2-image") ") and ("
      (:GROUP (:FONT :FACE :I) "x3") "," (:GROUP (:FONT :FACE :I) "y3") ") into (" (:GROUP (:FONT :FACE :I) "x3-image")
      "," (:GROUP (:FONT :FACE :I) "y3-image")
      "). Three non-collinear points and their images under the transformation are enough to specify any affine transformation."
      (:PAR) "If the positions " (:MATH "(x" (:RM "1") ",y" (:RM "1") ")") ", "
      (:MATH "(x" (:RM "2") ",y" (:RM "2") ")") " and " (:MATH "(x" (:RM "3") ",y" (:RM "3") ")")
      " are collinear, the " (:CL "transformation-underspecified") " error will be signalled. If ("
      (:GROUP (:FONT :FACE :I) "x1-image") "," (:GROUP (:FONT :FACE :I) "y1-image") "), ("
      (:GROUP (:FONT :FACE :I) "x2-image") "," (:GROUP (:FONT :FACE :I) "y2-image") "), and ("
      (:GROUP (:FONT :FACE :I) "x3-image") "," (:GROUP (:FONT :FACE :I) "y3-image")
      ") are collinear, the resulting transformation will be singular but this is not an error." (:PAR)
      "This is the spread version of " (:CL "make-3-point-transformation") "." (:PAR) " "))
    (:SECTION :TITLE ("5.3 " "The Transformation Protocol") :KIND :SECTION :NAME (3 3 10) (:PAR)
     "The following subsections describe the transformation protocol. All classes that are subclasses of "
     (:CL "transformation") " must implement methods for all of the generic functions in the following subsections."
     (:PAR) " "
     (:SECTION :TITLE ("5.3.1 " "Transformation Predicates") :KIND :SUBSECTION :NAME (3 3 3 10) (:PAR)
      "In all of the functions below, the argument named " (:GROUP (:FONT :FACE :I) "transformation")
      " must be a transformation." (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "transformation-equal")) :PARAMS ((:I "transformation1 transformation2")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the two " (:TERM "transformations") " "
       (:GROUP (:FONT :FACE :I) "transformation1") " and " (:GROUP (:FONT :FACE :I) "transformation2")
       " have equivalent effects (that is, are mathematically equal), otherwise returns " (:TERM "false") "." (:PAR)
       "Implementations are encouraged to allow transformations that are not numerically equal due to floating-point roundoff errors to be "
       (:CL "transformation-equal") ". An appropriate level of \"fuzziness\" is " (:CL "single-float-epsilon")
       ", or some small multiple of " (:CL "single-float-epsilon") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "identity-transformation-p")) :PARAMS ((:I "transformation")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") " is equal (in the sense of " (:CL "transformation-equal")
       ") to the identity transformation, otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "invertible-transformation-p")) :PARAMS ((:I "transformation")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") " has an inverse, otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "translation-transformation-p")) :PARAMS ((:I "transformation")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation")
       " is a pure translation, that is, a transformation such that there are two distance components " (:MATH "dx")
       " and " (:MATH "dy") " and every point " (:MATH "(x,y)") " is moved to " (:MATH "(x + dx,y + dy)")
       ". Otherwise, " (:CL "translation-transformation-p") " returns " (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "reflection-transformation-p")) :PARAMS ((:I "transformation")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation")
       " inverts the \"handedness\" of the coordinate system, otherwise returns " (:TERM "false")
       ". Note that this is a very inclusive category---transformations are considered reflections even if they distort, scale, or skew the coordinate system, as long as they invert the handedness."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "rigid-transformation-p")) :PARAMS ((:I "transformation")) :KIND ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation")
       " transforms the coordinate system as a rigid object, that is, as a combination of translations, rotations, and pure reflections. Otherwise, it returns "
       (:TERM "false") "." (:PAR)
       "Rigid transformations are the most general category of transformations that preserve magnitudes of all lengths and angles."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "even-scaling-transformation-p")) :PARAMS ((:I "transformation")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") " multiplies all " (:MATH "x") " lengths and " (:MATH "y")
       " lengths by the same magnitude, otherwise returns " (:TERM "false")
       ". It does include pure reflections through vertical and horizontal lines." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "scaling-transformation-p")) :PARAMS ((:I "transformation")) :KIND ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") " multiplies all " (:MATH "x") " lengths by one magnitude and all "
       (:MATH "y") " lengths by another magnitude, otherwise returns " (:TERM "false")
       ". This category includes even scalings as a subset." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "rectilinear-transformation-p")) :PARAMS ((:I "transformation")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation")
       " will always transform any axis-aligned rectangle into another axis-aligned rectangle, otherwise returns "
       (:TERM "false") ". This category includes scalings as a subset, and also includes 90 degree rotations." (:PAR)
       "Rectilinear transformations are the most general category of transformations for which the bounding rectangle of a transformed object can be found by transforming the bounding rectangle of the original object."
       (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " " (:GROUP (:FONT :FACE :SL) "Supply this figure. --- SWM")
       (:PAR)
       (:FIGURE :NUMBER "5.1" :CAPTION
        ("The predicates for analyzing the mathematical properties of a transformation.") " "
        (:CENTER "To be supplied.") "  ")
       (:PAR) " "))
     (:SECTION :TITLE ("5.3.2 " "Composition of Transformations") :KIND :SUBSECTION :NAME (3 3 3 10) (:PAR)
      "If we transform from one coordinate system to another, then from the second to a third coordinate system, we can regard the resulting transformation as a single transformation resulting from "
      (:CONCEPT "composing")
      " the two component transformations. It is an important and useful property of affine transformations that they are closed under composition. Note that composition is not commutative; in general, the result of applying transformation "
      (:MATH "A") " and then applying transformation " (:MATH "B") " is not the same as applying " (:MATH "B")
      " first, then " (:MATH "A") "." (:PAR)
      "Any arbitrary transformation can be built up by composing a number of simpler transformations, but that composition is not unique."
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "compose-transformations")) :PARAMS ((:I "transformation1 transformation2")) :KIND
        ("Generic Function"))
       (:PAR)
       "Returns a transformation that is the mathematical composition of its arguments. Composition is in right-to-left order, that is, the resulting transformation represents the effects of applying the "
       (:TERM "transformation") " " (:GROUP (:FONT :FACE :I) "transformation2") " followed by the "
       (:TERM "transformation") " " (:GROUP (:FONT :FACE :I) "transformation1") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "invert-transformation")) :PARAMS ((:I "transformation")) :KIND ("Generic Function"))
       (:PAR) "Returns a transformation that is the inverse of the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation")
       ". The result of composing a transformation with its inverse is equal to the identity transformation." (:PAR)
       "If " (:GROUP (:FONT :FACE :I) "transformation") " is singular, " (:CL "invert-transformation")
       " will signal the " (:CL "singular-transformation")
       " error, with a named restart that is invoked with a transformation and makes " (:CL "invert-transformation")
       " return that transformation. This is to allow a drawing application, for example, to use a generalized inverse to transform a region through a singular transformation."
       (:PAR)
       "Note that with finite-precision arithmetic there are several low-level conditions that might occur during the attempt to invert a singular or \"almost singular\" transformation. (These include computation of a zero determinant, floating-point underflow during computation of the determinant, or floating-point overflow during subsequent multiplication.) "
       (:CL "invert-transformation") " must signal the " (:CL "singular-transformation")
       " error for all of these cases." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "compose-translation-with-transformation")) :PARAMS ((:I "transformation dx dy")) :KIND
        ("Function"))
       (:SIGNATURE :NAME ((:CL "compose-scaling-with-transformation")) :PARAMS
        ((:I "transformation sx sy " (:GROUP (:FONT :FACE :TT) "&optional ") "origin")) :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "compose-rotation-with-transformation")) :PARAMS
        ((:I "transformation angle " (:GROUP (:FONT :FACE :TT) "&optional ") "origin")) :KIND ("Function"))
       (:PAR) "These functions create a new transformation by composing the " (:TERM "transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation")
       " with a given translation, scaling, or rotation, respectively. The order of composition is that the translation, scaling, or rotation \"transformation\" is first, followed by "
       (:GROUP (:FONT :FACE :I) "transformation") "." (:PAR) (:GROUP (:FONT :FACE :I) "dx") " and "
       (:GROUP (:FONT :FACE :I) "dy") " are as for " (:CL "make-translation-transformation") ". "
       (:GROUP (:FONT :FACE :I) "sx") " and " (:GROUP (:FONT :FACE :I) "sy") " are as for "
       (:CL "make-scaling-transformation") ". " (:GROUP (:FONT :FACE :I) "angle") " and "
       (:GROUP (:FONT :FACE :I) "origin") " are as for " (:CL "make-rotation-transformation") "." (:PAR)
       "Note that these functions could be implemented by using the various constructors and "
       (:CL "compose-transformations")
       ". They are provided, because it is common to build up a transformation as a series of simple transformations."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "compose-transformation-with-translation")) :PARAMS ((:I "transformation dx dy")) :KIND
        ("Function"))
       (:SIGNATURE :NAME ((:CL "compose-transformation-with-scaling")) :PARAMS
        ((:I "transformation sx sy " (:GROUP (:FONT :FACE :TT) "&optional ") "origin")) :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "compose-transformation-with-rotation")) :PARAMS
        ((:I "transformation angle " (:GROUP (:FONT :FACE :TT) "&optional ") "origin")) :KIND ("Function"))
       (:PAR)
       "These functions create a new transformation by composing a given translation, scaling, or rotation, respectively, with the "
       (:TERM "transformation") " " (:GROUP (:FONT :FACE :I) "transformation") ". The order of composition is "
       (:GROUP (:FONT :FACE :I) "transformation")
       " is first, followed by the translation, scaling, or rotation \"transformation\"." (:PAR)
       (:GROUP (:FONT :FACE :I) "dx") " and " (:GROUP (:FONT :FACE :I) "dy") " are as for "
       (:CL "make-translation-transformation") ". " (:GROUP (:FONT :FACE :I) "sx") " and "
       (:GROUP (:FONT :FACE :I) "sy") " are as for " (:CL "make-scaling-transformation") ". "
       (:GROUP (:FONT :FACE :I) "angle") " and " (:GROUP (:FONT :FACE :I) "origin") " are as for "
       (:CL "make-rotation-transformation") "." (:PAR)
       "Note that these functions could be implemented by using the various constructors and "
       (:CL "compose-transformations")
       ". They are provided, because it is common to build up a transformation as a series of simple transformations."
       (:PAR) " "))
     (:SECTION :TITLE ("5.3.3 " "Applying Transformations") :KIND :SUBSECTION :NAME (3 3 3 10) (:PAR)
      "Transforming a region applies a coordinate transformation to that region, thus moving its position on the drawing plane, rotating it, or scaling it. Note that transforming a region does not side-effect the "
      (:GROUP (:FONT :FACE :I) "region")
      " argument; it is free to either create a new region or return an existing (cached) region." (:PAR)
      "These generic functions must be implemented for all classes of transformations. Furthermore, all subclasses of "
      (:CL "region") " and " (:CL "design") " must implement methods for " (:CL "transform-region") " and "
      (:CL "untransform-region")
      ". That is, methods for the following generic functions will typically specialize both the "
      (:GROUP (:FONT :FACE :I) "transformation") " and " (:TERM "region") " arguments." (:PAR)
      "Note that, if the extended region classes are not implemented, the following functions are not closed, that is, they may return results that are not CLIM regions."
      (:PAR) " "
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "transform-region")) :PARAMS ((:I "transformation region")) :KIND ("Generic Function"))
       (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "transformation") " to the " (:TERM "region") " "
       (:GROUP (:FONT :FACE :I) "region") ", and returns the transformed region." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "untransform-region")) :PARAMS ((:I "transformation region")) :KIND
        ("Generic Function"))
       (:PAR) "This is exactly equivalent to " (:BR) " " (:CODE "(transform-region (invert-transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") (:CODE ")") " " (:GROUP (:FONT :FACE :I) "region") (:CODE ")") " ."
       (:PAR) "CLIM provides a default method for " (:CL "untransform-region") " on the " (:CL "transformation")
       " protocol class that does exactly this." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "transform-position")) :PARAMS ((:I "transformation x y")) :KIND ("Generic Function"))
       (:PAR) "Applies the " (:TERM "transformation") " " (:GROUP (:FONT :FACE :I) "transformation")
       " to the point whose coordinates are the real numbers " (:GROUP (:FONT :FACE :I) "x") " and "
       (:GROUP (:FONT :FACE :I) "y") ", and returns two values, the transformed " (:MATH "x")
       " coordinate and the transformed " (:MATH "y") " coordinate." (:PAR) (:CL "transform-position")
       " is the spread version of " (:CL "transform-region") " in the case where the region is a point." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "untransform-position")) :PARAMS ((:I "transformation x y")) :KIND ("Generic Function"))
       (:PAR) "This is exactly equivalent to " (:BR) " " (:CODE "(transform-position (invert-transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") (:CODE ")") " " (:GROUP (:FONT :FACE :I) "x") " "
       (:GROUP (:FONT :FACE :I) "y") (:CODE ")") " ." (:PAR) "CLIM provides a default method for "
       (:CL "untransform-position") " on the " (:CL "transformation") " protocol class that does exactly this." (:PAR)
       " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "transform-distance")) :PARAMS ((:I "transformation dx dy")) :KIND ("Generic Function"))
       (:PAR) "Applies the " (:TERM "transformation") " " (:GROUP (:FONT :FACE :I) "transformation")
       " to the distance represented by the real numbers " (:GROUP (:FONT :FACE :I) "dx") " and "
       (:GROUP (:FONT :FACE :I) "dy") ", and returns two values, the transformed " (:GROUP (:FONT :FACE :I) "dx")
       " and the transformed " (:GROUP (:FONT :FACE :I) "dy") "." (:PAR)
       "A distance represents the difference between two points. It does " (:GROUP (:FONT :FACE :SL) "not")
       " transform like a point." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "untransform-distance")) :PARAMS ((:I "transformation dx dy")) :KIND
        ("Generic Function"))
       (:PAR) "This is exactly equivalent to " (:BR) " " (:CODE "(transform-distance (invert-transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") (:CODE ")") " " (:GROUP (:FONT :FACE :I) "dx") " "
       (:GROUP (:FONT :FACE :I) "dy") (:CODE ")") " ." (:PAR) "CLIM provides a default method for "
       (:CL "untransform-distance") " on the " (:CL "transformation") " protocol class that does exactly this." (:PAR)
       " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "transform-rectangle*")) :PARAMS ((:I "transformation x1 y1 x2 y2")) :KIND
        ("Generic Function"))
       (:PAR) "Applies the " (:TERM "transformation") " " (:GROUP (:FONT :FACE :I) "transformation")
       " to the rectangle specified by the four coordinate arguments, which are real numbers. The arguments "
       (:GROUP (:FONT :FACE :I) "x1") ", " (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and "
       (:GROUP (:FONT :FACE :I) "y1") " are canonicalized in the same way as for " (:CL "make-bounding-rectangle")
       ". Returns four values that specify the minimum and maximum points of the transformed rectangle in the order "
       (:GROUP (:FONT :FACE :I) "min-x") ", " (:GROUP (:FONT :FACE :I) "min-y") ", " (:GROUP (:FONT :FACE :I) "max-x")
       ", and " (:GROUP (:FONT :FACE :I) "max-y") "." (:PAR) "It is an error is "
       (:GROUP (:FONT :FACE :I) "transformation") " does not satisfy " (:CL "rectilinear-transformation-p") "." (:PAR)
       (:CL "transform-rectangle*") " is the spread version of " (:CL "transform-region")
       " in the case where the transformation is rectilinear and the region is a rectangle." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "untransform-rectangle*")) :PARAMS ((:I "transformation x1 y1 x2 y2")) :KIND
        ("Generic Function"))
       (:PAR) "This is exactly equivalent to " (:BR) " " (:CODE "(transform-rectangle* (invert-transformation") " "
       (:GROUP (:FONT :FACE :I) "transformation") (:CODE ")") " " (:GROUP (:FONT :FACE :I) "x1") " "
       (:GROUP (:FONT :FACE :I) "y1") " " (:GROUP (:FONT :FACE :I) "x2") " " (:GROUP (:FONT :FACE :I) "y2") (:CODE ")")
       " ." (:PAR) "CLIM provides a default method for " (:CL "untransform-rectangle*") " on the "
       (:CL "transformation") " protocol class that does exactly this." (:PAR)))))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part III: " "Windowing Substrate") :NAME (10) " " " "
   (:SECTION :TITLE ("6 " "Overview of Window Facilities") :KIND :CHAPTER :NAME (4 10) (:PAR)
    (:SECTION :TITLE ("6.1 " "Introduction") :KIND :SECTION :NAME (3 4 10) (:PAR)
     "A central notion in organizing user interfaces is allocating screen regions to particular tasks and recursively subdividing these regions into subregions. The windowing layer of CLIM defines an extensible framework for constructing, using, and managing such "
     (:CONCEPT "hierarchies of interactive regions")
     ". This framework allows uniform treatment of the following things:" (:PAR)
     (:UL (:LI "Window objects like those in X or NeWS." (:PAR))
      (:LI "Lightweight gadgets typical of toolkit layers, such as Motif or OpenLook." (:PAR))
      (:LI "Structured graphics like output records and an application's presentation objects." (:PAR))
      (:LI
       "Objects that act as Lisp handles for windows or gadgets implemented in a different language (such as OpenLook gadgets implemented in C). "))
     (:PAR)
     "From the perspective of most CLIM users, CLIM's windowing layer plays the role of a window system. However, CLIM will usually use 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 systems or as display servers."
     (:PAR) "The fundamental window abstraction defined by CLIM 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, CLIM 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") "." (:PAR)
     "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 :NAME "ports-and-grafts") "." (:PAR) " ")
    (:SECTION :TITLE ("6.2 " "Properties of Sheets") :KIND :SECTION :NAME (3 4 10) (:PAR)
     "Sheets have the following properties:" (:PAR)
     (:DL (:DT "A coordinate system")
      (:DD "Provides the ability to refer to locations in a sheet's abstract plane." (:PAR)) (:DT "A region")
      (:DD
       "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."
       (:PAR))
      (:DT "A parent")
      (:DD "A sheet that is the parent in a windowing relationship in which this sheet is a child." (:PAR))
      (:DT "Children")
      (:DD
       "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."
       (:PAR))
      (:DT "A transformation")
      (:DD "Determines how points in this sheet's coordinate system are mapped into points in its parents." (:PAR))
      (:DT "An enabled flag")
      (:DD
       "Indicates whether the sheet is currently actively participating in the windowing relationship with its parent and siblings."
       (:PAR))
      (:DT "An event handler")
      (:DD "A procedure invoked when the display server wishes to inform CLIM of external events." (:PAR))
      (:DT "Output state")
      (:DD
       "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. "))
     (:PAR) " ")
    (:SECTION :TITLE ("6.3 " "Sheet Protocols") :KIND :SECTION :NAME (3 4 10) (:PAR)
     "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:"
     (:PAR)
     (:DL (:DT "The windowing protocol")
      (:DD
       "Describes the relationships between the sheet and its parent and children (and, by extension, all of its ancestors and descendants)."
       (:PAR))
      (:DT "The input protocol")
      (:DD
       "Provides the event handler for a sheet. Events may be handled synchronously, asynchronously, or not at all."
       (:PAR))
      (:DT "The output protocol")
      (:DD
       "Provides graphical and textual output, and manages descriptive output state such as color, transformation, and clipping."
       (:PAR))
      (:DT "The repaint protocol")
      (:DD
       "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."
       (:PAR))
      (:DT "The notification protocol")
      (:DD
       "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. "))
     (:PAR)
     "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."
     (:PAR) " "))
   (:SECTION :TITLE ("7 " "Properties of Sheets") :KIND :CHAPTER :NAME (4 10) " " (:LABEL :NAME "sheet-properties")
    (:PAR)
    (:SECTION :TITLE ("7.1 " "Basic Sheet Classes") :KIND :SECTION :NAME (3 4 10) (:PAR)
     "Note that there are no standard sheet classes in CLIM, and no pre-packaged way to create sheets in general. If a programmer needs to create an instance of some class of sheet, "
     (:CL "make-instance") " must be used. For most purposes, calling " (:CL "make-pane")
     " is how application programmers will make sheets." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "sheet")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a sheet. This and the next chapter describe all of the sheet protocols. If you want to create a new class that behaves like a sheet, it should be a subclass of "
      (:CL "sheet") ". All instantiable subclasses of " (:CL "sheet") " must obey the sheet protocol. " (:PAR)
      "All of the subclasses of " (:CL "sheet") " are mutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "sheetp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "sheet") ", otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "basic-sheet")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The basic class on which all CLIM sheets are built, a subclass of " (:CL "sheet")
      ". This class is an abstract class, intended only to be subclassed, not instantiated. " (:PAR) (:PAR)))
    (:SECTION :TITLE ("7.2 " "Relationships Between Sheets") :KIND :SECTION :NAME (3 4 10) (:PAR)
     "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."
     (:PAR)
     (:DL (:DT "Adopted")
      (:DD "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." (:PAR))
      (:DT "Disowned")
      (:DD "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." (:PAR))
      (:DT "Grafted")
      (:DD "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."
       (:PAR))
      (:DT "Degrafted")
      (:DD "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."
       (:PAR))
      (:DT "Enabled")
      (:DD "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."
       (:PAR))
      (:DT "Disabled") (:DD "The opposite of enabled is " (:CONCEPT "disabled") ". "))
     (:PAR) " "
     (:SECTION :TITLE ("7.2.1 " "Sheet Relationship Functions") :KIND :SUBSECTION :NAME (2 3 4 10) (:PAR)
      "The generic functions in this section comprise the sheet protocol. All sheet objects must implement or inherit methods for each of these generic functions."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-parent")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns the parent of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") ", or " (:CL "nil")
       " if the sheet has no parent." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-children")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns a list of sheets that are the children of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "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. This function returns objects that reveal CLIM's internal state; do not modify those objects. "
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-adopt-child")) :PARAMS ((:I "sheet child")) :KIND ("Generic Function"))
       (:PAR) "Adds the child sheet " (:GROUP (:FONT :FACE :I) "child") " to the set of children of the "
       (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") ", and makes the " (:GROUP (:FONT :FACE :I) "sheet")
       " the child's parent. If " (:GROUP (:FONT :FACE :I) "child") " already has a parent, the "
       (:CL "sheet-already-has-parent") " error will be signalled." (:PAR)
       "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." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sheet-disown-child")) :PARAMS
        ((:I "sheet child " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp " (:CL "t") ")")) :KIND ("Generic Function"))
       (:PAR) "Removes the child sheet " (:GROUP (:FONT :FACE :I) "child") " from the set of children of the "
       (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") ", and makes the parent of the child be " (:CL "nil")
       ". If " (:GROUP (:FONT :FACE :I) "child") " is not actually a child of " (:GROUP (:FONT :FACE :I) "sheet")
       " and " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", then the " (:CL "sheet-is-not-child")
       " error will be signalled." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-siblings")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns a list of all of the siblings of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       ". The sibling are all of the children of " (:GROUP (:FONT :FACE :I) "sheet") "'s parent excluding "
       (:GROUP (:FONT :FACE :I) "sheet") " itself. This function returns fresh objects that may be modified. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-enabled-children")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:PAR) "Returns a list of those children of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       " that are enabled. This function returns fresh objects that may be modified. " (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sheet-ancestor-p")) :PARAMS ((:I "sheet putative-ancestor")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "putative-ancestor") " is in fact an ancestor of the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "sheet") ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "raise-sheet")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "bury-sheet")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "These functions reorder the children of a sheet by raising the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "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."
       (:PAR) "This may change which parts of which sheets are visible on the display device." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "reorder-sheets")) :PARAMS ((:I "sheet new-ordering")) :KIND ("Generic Function"))
       (:PAR) "Reorders the children of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       " to have the new ordering specified by " (:GROUP (:FONT :FACE :I) "new-ordering") ". "
       (:GROUP (:FONT :FACE :I) "new-ordering") " is an ordered list of the child sheets; elements at the front of "
       (:GROUP (:FONT :FACE :I) "new-ordering") " are \"on top\" of elements at the rear." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "new-ordering") " does not contain all of the children of "
       (:GROUP (:FONT :FACE :I) "sheet") ", the " (:CL "sheet-ordering-underspecified") " error will be signalled. If "
       (:GROUP (:FONT :FACE :I) "new-ordering") " contains a sheet that is not a child of "
       (:GROUP (:FONT :FACE :I) "sheet") ", the " (:CL "sheet-is-not-child") " error will be signalled." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-enabled-p")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns " (:TERM "true") " if the the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "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." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf sheet-enabled-p)")) :PARAMS ((:I "enabled-p sheet")) :KIND ("Generic Function"))
       (:PAR) "When " (:GROUP (:FONT :FACE :I) "enabled-p") " is " (:TERM "true") ", this enables the the "
       (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") ". When " (:GROUP (:FONT :FACE :I) "enabled-p") " is "
       (:TERM "false") ", this disables the sheet." (:PAR)
       "Note that a sheet is not visible unless it and all of its ancestors are enabled." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-viewable-p")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns " (:TERM "true") " if the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       " and all its ancestors are enabled, and if one of its ancestors is a graft. See Chapter "
       (:REF :NAME "ports-and-grafts") " for further information." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sheet-occluding-sheets")) :PARAMS ((:I "sheet child")) :KIND ("Generic Function"))
       (:PAR) "Returns a list of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "child")
       "'s siblings that occlude part or all of the region of the " (:GROUP (:FONT :FACE :I) "child")
       ". In general, these are the siblings that are enabled and appear earlier in the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "sheet") "'s children. If " (:GROUP (:FONT :FACE :I) "sheet")
       " does not permit overlapping among its children, " (:CL "sheet-occluding-sheets") " will return " (:CL "nil")
       "." (:PAR) "This function returns fresh objects that may be modified. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "map-over-sheets")) :PARAMS ((:I "function sheet")) :KIND ("Generic Function"))
       (:PAR) "Applies the function " (:GROUP (:FONT :FACE :I) "function") " to the sheet "
       (:GROUP (:FONT :FACE :I) "sheet") ", and then applies " (:GROUP (:FONT :FACE :I) "function")
       " to all of the descendents (the children, the children's children, and so forth) of "
       (:GROUP (:FONT :FACE :I) "sheet") "." (:PAR)
       "Function is a function of one argument, the sheet; it has dynamic extent." (:PAR) " "))
     (:SECTION :TITLE ("7.2.2 " "Sheet Genealogy Classes") :KIND :SUBSECTION :NAME (2 3 4 10) (:PAR)
      "Different \"mixin\" classes are provided that implement the relationship protocol. None of the four following classes is instantiable."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-parent-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes that have a parent." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-leaf-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes that will never have children." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-single-child-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes that have at most a single child." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-multiple-child-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes that may have zero or more children." (:PAR) " ")))
    (:SECTION :TITLE ("7.3 " "Sheet Geometry") :KIND :SECTION :NAME (3 4 10) (:PAR)
     "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."
     (:PAR)
     (:SECTION :TITLE ("7.3.1 " "Sheet Geometry Functions") :KIND :SUBSECTION :NAME (2 3 4 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-transformation")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf sheet-transformation)")) :PARAMS ((:I "transformation sheet")) :KIND
        ("Generic Function"))
       (:PAR) "Returns a transformation that converts coordinates in the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "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."
       (:PAR) "When the sheet's transformation is changed, " (:CL "note-sheet-transformation-changed")
       " is called on the to notify the sheet of the change." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-region")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf sheet-region)")) :PARAMS ((:I "region sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns a region object that represents the set of points to which the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "sheet") " refers. The region is in the sheet's coordinate system. Using " (:CL "setf")
       " on this accessor modifies the sheet's region." (:PAR) "When the sheet's region is changed, "
       (:CL "note-sheet-region-region") " is called on " (:GROUP (:FONT :FACE :I) "sheet")
       " to notify the sheet of the change." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL)
        "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? --- RSL")
       (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL)
        "I'm not convinced I like this business of requesting a change by modifying an accessor. It might 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. Currently, using "
        (:CL "setf")
        " on mirrored sheets requests that the server move or resize the sheet; the accessor will continue to return the old value until the notification comes in from the display server that says that the mirror has been moved. --- RSL")
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "move-sheet")) :PARAMS ((:I "sheet x y")) :KIND ("Generic Function")) (:PAR)
       "Moves the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") " to the new position " (:MATH "(x,y)") ". "
       (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       " are expressed in the coordinate system of " (:GROUP (:FONT :FACE :I) "sheet") "'s parent." (:PAR)
       (:CL "move-sheet") " simply modifies " (:GROUP (:FONT :FACE :I) "sheet")
       "'s transformation, and could be implemented as follows:" (:PAR)
       (:PRE "
(defmethod move-sheet ((sheet basic-sheet) x y)
  (let ((transform (sheet-transformation sheet)))
    (multiple-value-bind (old-x old-y)
        (transform-position transform 0 0)
      (setf (sheet-transformation sheet)
            (compose-translation-with-transformation
              transform (- x old-x) (- y old-y))))))
")
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "resize-sheet")) :PARAMS ((:I "sheet width height")) :KIND ("Generic Function"))
       (:PAR) "Resizes the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") " to have a new width "
       (:GROUP (:FONT :FACE :I) "width") " and a new height " (:GROUP (:FONT :FACE :I) "height") ". "
       (:GROUP (:FONT :FACE :I) "width") " and " (:GROUP (:FONT :FACE :I) "height") " are real numbers." (:PAR)
       (:CL "resize-sheet") " simply modifies " (:GROUP (:FONT :FACE :I) "sheet")
       "'s region, and could be implemented as follows:" (:PAR)
       (:PRE "
(defmethod resize-sheet ((sheet basic-sheet) width height)
  (setf (sheet-region sheet)
        (make-bounding-rectangle 0 0 width height)))
")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "move-and-resize-sheet")) :PARAMS ((:I "sheet x y width height")) :KIND
        ("Generic Function"))
       (:PAR) "Moves the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") " to the new position "
       (:MATH "(x,y)") ", and changes its size to the new width " (:GROUP (:FONT :FACE :I) "width")
       " and the new height " (:GROUP (:FONT :FACE :I) "height") ". " (:GROUP (:FONT :FACE :I) "x") " and "
       (:GROUP (:FONT :FACE :I) "y") " are expressed in the coordinate system of " (:GROUP (:FONT :FACE :I) "sheet")
       "'s parent. " (:GROUP (:FONT :FACE :I) "width") " and " (:GROUP (:FONT :FACE :I) "height") " are real numbers."
       (:PAR) (:CL "move-and-resize-sheet") " could be implemented as follows:" (:PAR)
       (:PRE "
(defmethod move-and-resize-sheet ((sheet basic-sheet) x y width height)
  (move-sheet sheet x y)
  (resize-sheet sheet width height))
")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-sheet-position-to-parent")) :PARAMS ((:I "sheet x y")) :KIND ("Generic Function"))
       (:PAR) "Applies the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") "'s transformation to the point "
       (:MATH "(x,y)") ", returning the coordinates of that point in " (:GROUP (:FONT :FACE :I) "sheet")
       "'s parent's coordinate system." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-sheet-position-to-child")) :PARAMS ((:I "sheet x y")) :KIND ("Generic Function"))
       (:PAR) "Applies the inverse of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       "'s transformation to the point " (:MATH "(x,y)") " (represented in " (:GROUP (:FONT :FACE :I) "sheet")
       "'s parent's coordinate system), returning the coordinates of that same point in "
       (:GROUP (:FONT :FACE :I) "sheet") " coordinate system." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-sheet-rectangle*-to-parent")) :PARAMS ((:I "sheet x1 y1 x2 y2")) :KIND
        ("Generic Function"))
       (:PAR) "Applies the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       "'s transformation to the bounding rectangle specified by the corner points "
       (:MATH "(x" (:RM "1") ",y" (:RM "1") ")") " and " (:MATH "(x" (:RM "2") ",y" (:RM "2") ")")
       ", returning the bounding rectangle of the transformed region as four values, "
       (:GROUP (:FONT :FACE :I) "min-x") ", " (:GROUP (:FONT :FACE :I) "min-y") ", " (:GROUP (:FONT :FACE :I) "max-x")
       ", and " (:GROUP (:FONT :FACE :I) "max-y") ". The arguments " (:GROUP (:FONT :FACE :I) "x1") ", "
       (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and " (:GROUP (:FONT :FACE :I) "y1")
       " are canonicalized in the same way as for " (:CL "make-bounding-rectangle") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-sheet-rectangle*-to-child")) :PARAMS ((:I "sheet x1 y1 x2 y2")) :KIND
        ("Generic Function"))
       (:PAR) "Applies the inverse of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       "'s transformation to the bounding rectangle delimited by the corner points "
       (:MATH "(x" (:RM "1") ",y" (:RM "1") ")") " and " (:MATH "(x" (:RM "2") ",y" (:RM "2") ")") " (represented in "
       (:GROUP (:FONT :FACE :I) "sheet")
       "'s parent's coordinate system), returning the bounding rectangle of the transformed region as four values, "
       (:GROUP (:FONT :FACE :I) "min-x") ", " (:GROUP (:FONT :FACE :I) "min-y") ", " (:GROUP (:FONT :FACE :I) "max-x")
       ", and " (:GROUP (:FONT :FACE :I) "max-y") ". The arguments " (:GROUP (:FONT :FACE :I) "x1") ", "
       (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and " (:GROUP (:FONT :FACE :I) "y1")
       " are canonicalized in the same way as for " (:CL "make-bounding-rectangle") "." (:PAR)
       (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL) "I now think that " (:CL "map-") " in these names is misleading; maybe "
        (:CL "convert-") " is better? --- SWM")
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-sheets-containing-position")) :PARAMS ((:I "function sheet x y")) :KIND
        ("Generic Function"))
       (:PAR) "Applies the function " (:GROUP (:FONT :FACE :I) "function") " to all of the children of the sheet "
       (:GROUP (:FONT :FACE :I) "sheet") " that contain the position " (:MATH "(x,y)") ". "
       (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y") " are expressed in "
       (:GROUP (:FONT :FACE :I) "sheet") "'s coordinate system." (:PAR)
       "Function is a function of one argument, the sheet; it has dynamic extent." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-sheets-overlapping-region")) :PARAMS ((:I "function sheet region")) :KIND
        ("Generic Function"))
       (:PAR) "Applies the function " (:GROUP (:FONT :FACE :I) "function") " to all of the children of the sheet "
       (:GROUP (:FONT :FACE :I) "sheet") " that overlap the region " (:GROUP (:FONT :FACE :I) "region") ". "
       (:GROUP (:FONT :FACE :I) "region") " is expressed in " (:GROUP (:FONT :FACE :I) "sheet") "'s coordinate system."
       (:PAR) "Function is a function of one argument, the sheet; it has dynamic extent." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "child-containing-position")) :PARAMS ((:I "sheet x y")) :KIND ("Generic Function"))
       (:PAR) "Returns the topmost enabled direct child of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       " whose region contains the position " (:MATH "(x,y)") ". The position is expressed in "
       (:GROUP (:FONT :FACE :I) "sheet") "'s coordinate system." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "children-overlapping-region")) :PARAMS ((:I "sheet region")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "children-overlapping-rectangle*")) :PARAMS ((:I "sheet x1 y1 x2 y2")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the list of enabled direct children of the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "sheet") " whose region overlaps the " (:TERM "region") " "
       (:GROUP (:FONT :FACE :I) "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 "
       (:MATH "(x" (:RM "1") ",y" (:RM "1") ")") " and " (:MATH "(x" (:RM "2") ",y" (:RM "2") ")")
       ". The region is expressed in " (:GROUP (:FONT :FACE :I) "sheet")
       "'s coordinate system. This function returns fresh objects that may be modified. " (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sheet-delta-transformation")) :PARAMS ((:I "sheet ancestor")) :KIND
        ("Generic Function"))
       (:PAR) "Returns a transformation that is the composition of all of the sheet transformations between the "
       (:TERM "sheets") " " (:GROUP (:FONT :FACE :I) "sheet") " and " (:GROUP (:FONT :FACE :I) "ancestor") ". If "
       (:GROUP (:FONT :FACE :I) "ancestor") " is " (:CL "nil") ", " (:CL "sheet-delta-transformation")
       " will return the transformation to the root of the sheet hierarchy. If " (:GROUP (:FONT :FACE :I) "ancestor")
       " is not an ancestor of sheet, the " (:CL "sheet-is-not-ancestor") " error will be signalled." (:PAR)
       "The computation of the delta transformation is likely to be cached." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sheet-allocated-region")) :PARAMS ((:I "sheet child")) :KIND ("Generic Function"))
       (:PAR) "Returns the visible region of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "child") " in the "
       (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") "'s coordinate system. If "
       (:GROUP (:FONT :FACE :I) "child")
       " is occluded by any of its siblings, those siblings' regions are subtracted (using " (:CL "region-difference")
       ") from " (:GROUP (:FONT :FACE :I) "child") "'s actual region." (:PAR) " "))
     (:SECTION :TITLE ("7.3.2 " "Sheet Geometry Classes") :KIND :SUBSECTION :NAME (2 3 4 10) (:PAR)
      "Each of the following implements the sheet geometry protocol in a different manner, according to the sheet's requirements. None of the four following classes is instantiable."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-identity-transformation-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes whose coordinate system is identical to that of its parent." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-translation-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes whose coordinate system is related to that of its parent by a simple translation."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-y-inverting-transformation-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes whose coordinate system is related to that of its parent by inverting the "
       (:MATH "y") " coordinate system, and optionally translating by some amount in " (:MATH "x") " and " (:MATH "y")
       "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-transformation-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into sheet classes whose coordinate system is related to that of its parent by an arbitrary affine transformation. CLIM implementations are allowed to restrict these transformations to just rectilinear ones."
       (:PAR) " "))))
   (:SECTION :TITLE ("8 " "Sheet Protocols") :KIND :CHAPTER :NAME (4 10) " " (:LABEL :NAME "sheet-protocols") (:PAR)
    (:SECTION :TITLE ("8.1 " "Input Protocol") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "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." (:PAR)
     "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." (:PAR)
     "In addition to handling input event, a sheet is also responsible for providing other input services, such as controlling the pointer's appearance, and polling for current pointer and keyboard state."
     (:PAR) "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." (:PAR) (: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; this process is called " (:CONCEPT "distributing")
     ". 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 "dispatches")
     " 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."
     (:PAR) "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." (:PAR)
     " "
     (:SECTION :TITLE ("8.1.1 " "Input Protocol Functions") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      "In the functions below, the " (:GROUP (:FONT :FACE :I) "client")
      " argument is typically a sheet, but it may be another object that supports event distribution, dispatching, and handling."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-event-queue")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Any sheet that can process events will have an event queue from which the events are gotten. "
       (:CL "sheet-event-queue")
       " returns the object that acts as the event queue. The exact representation of an event queue is explicitly unspecified."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "process-next-event")) :PARAMS
        ((:I "port " (:GROUP (:FONT :FACE :TT) "&key ") "wait-function timeout")) :KIND ("Generic Function"))
       (:PAR) "This function provides a standard interface for one pass through a port's event processing loop. "
       (:GROUP (:FONT :FACE :I) "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:"
       (:PAR)
       (:UL (:LI "If an event if received and processed, the predicate should return " (:TERM "true") "." (:PAR))
        (:LI "If a timeout occurs, the predicate should return " (:TERM "false") "." (:PAR))
        (:LI "If the wait function returns " (:TERM "true") ", the predicate should return the two values "
         (:TERM "false") " and " (:CL ":timeout") ". "))
       (:PAR)
       "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."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "port-keyboard-input-focus")) :PARAMS ((:I "port")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf port-keyboard-input-focus)")) :PARAMS ((:I "focus port")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the client to which keyboard events are to be dispatched." (:PAR)
       (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL) "Should this accessor be called " (:CL "keyboard-input-focus")
        "? It may be that we want to be able to call it on a frame in order to implement some sort of per-frame input focus. --- RSL")
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "distribute-event")) :PARAMS ((:I "port event")) :KIND ("Generic Function"))
       (:PAR) "The " (:GROUP (:FONT :FACE :I) "event") " is distributed to the " (:GROUP (:FONT :FACE :I) "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."
       (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL) "Do we just want to call this function " (:CL "dispatch-event")
        " and have it called on the port first? --- RSL")
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "dispatch-event")) :PARAMS ((:I "client event")) :KIND ("Generic Function"))
       (:PAR) "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." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "queue-event")) :PARAMS ((:I "client event")) :KIND ("Generic Function")) (:PAR)
       "Places the event " (:GROUP (:FONT :FACE :I) "event") " into the queue of events for the client "
       (:GROUP (:FONT :FACE :I) "client") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "handle-event")) :PARAMS ((:I "client event")) :KIND ("Generic Function")) (:PAR)
       "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."
       (:PAR) "In addition to " (:CL "queue-event")
       ", the queued input protocol handles the following generic functions. The " (:GROUP (:FONT :FACE :I) "client")
       " argument to these functions is typically a sheet." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "event-read")) :PARAMS ((:I "client")) :KIND ("Generic Function")) (:PAR)
       "Takes the next event out of the queue of events for this client." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "event-read-no-hang")) :PARAMS ((:I "client")) :KIND ("Generic Function")) (:PAR)
       "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." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "event-peek")) :PARAMS
        ((:I "client " (:GROUP (:FONT :FACE :TT) "&optional ") "event-type")) :KIND ("Generic Function"))
       (:PAR) "Returns the next event in the queue without removing it from the queue. If "
       (:GROUP (:FONT :FACE :I) "event-type")
       " is supplied, events that are not of that type are first removed and discarded." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "event-unread")) :PARAMS ((:I "client event")) :KIND ("Generic Function")) (:PAR)
       "Places the " (:GROUP (:FONT :FACE :I) "event") " at the head of the " (:GROUP (:FONT :FACE :I) "client")
       "'s event queue, so as to be the next event read." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "event-listen")) :PARAMS ((:I "client")) :KIND ("Generic Function")) (:PAR)
       "Returns " (:TERM "true") " if there are any events queued for " (:GROUP (:FONT :FACE :I) "client")
       ", otherwise returns " (:TERM "false") "." (:PAR) " "))
     (:SECTION :TITLE ("8.1.2 " "Input Protocol Classes") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      "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 "pointer-button-click-event") "." (:PAR)
      "None of the five following classes is instantiable." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-sheet-input-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "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." (:PAR)
       "The " (:CL "standard-sheet-input-mixin") " class will also provide a " (:CL "sheet-event-queue")
       " method, describe above." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "immediate-sheet-input-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class of sheet provides a method for " (:CL "dispatch-event") " that calls " (:CL "handle-event")
       " immediately for all events." (:PAR) "The " (:CL "immediate-sheet-input-mixin") " class will also provide a "
       (:CL "sheet-event-queue") " method, describe above." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-mute-input-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This is mixed in to any sheet class the does not handle any input events." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "delegate-sheet-input-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class of sheet provides a method for " (:CL "dispatch-event") " that calls " (:CL "dispatch-event")
       " on a designated substitute recipient and the event. The initarg " (:CL ":delegate") " or the accessor "
       (:GROUP "delegate-sheet-delegate") " may be used to set the recipient of dispatched events." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "delegate-sheet-delegate")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf delegate-sheet-delegate)")) :PARAMS ((:I "delegate sheet")) :KIND
        ("Generic Function"))
       (:PAR) "This may be set to another recipient of events dispatched to a sheet of class "
       (:CL "delegate-sheet-input-mixin") ". " (:GROUP (:FONT :FACE :I) "delegate")
       " is the object to which events will be dispatched, and is usually another sheet. If the delegate is "
       (:CL "nil") ", events are discarded." (:PAR) (:PAR) " ")))
    (:SECTION :TITLE ("8.2 " "Standard Device Events") :KIND :SECTION :NAME (5 4 10) (:PAR) "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 "
     (:MATH "x") " and " (:MATH "y")
     " bposition of the pointer within that sheet, the key name or character corresponding to a key on the keyboard, and so forth."
     (:PAR) "Figure " (:REF :NAME "event-hier") " shows all the event classes." (:PAR)
     (:FIGURE :NUMBER "8.1" :CAPTION
      ((:LABEL :NAME "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.")
      " " (:HR) "  XXXXXXXXXXXX  " (:CL "event") " " (:BR) " " (:CL "device-event") " " (:BR) " "
      (:CL "keyboard-event") " " (:BR) " " (:CL "key-press-event") " " (:BR) " " (:CL "key-release-event") " " (:BR)
      " " (:CL "pointer-event") " " (:BR) " " (:CL "pointer-button-event") " " (:BR) " "
      (:CL "pointer-button-press-event") " " (:BR) " " (:CL "pointer-button-release-event") " " (:BR) " "
      (:CL "pointer-button-hold-event") " " (:BR) " " (:CL "pointer-motion-event") " " (:BR) " "
      (:CL "pointer-boundary-event") " " (:BR) " " (:CL "pointer-enter-event") " " (:BR) " " (:CL "pointer-exit-event")
      " " (:BR) " " (:CL "window-event") " " (:BR) " " (:CL "window-configuration-event") " " (:BR) " "
      (:CL "window-repaint-event") " " (:BR) " " (:CL "window-manager-event") " " (:BR) " "
      (:CL "window-manager-delete--event") " " (:BR) " " (:CL "timer-event") " " (:BR) "    " (:HR) " ")
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "event")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to any sort of \"event\". If you want to create a new class that behaves like an event, it should be a subclass of "
      (:CL "event") ". All instantiable subclasses of " (:CL "event") " must obey the event protocol. " (:PAR)
      "All of the event classes are immutable. CLIM implementations may choose to keep a resource of the device event classes, but this must be invisible at the API level. That is, any event visible at the level of the API must act as though it is immutable."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "eventp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an " (:TERM "event") ", otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":timestamp")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "event") " must take a " (:CL ":timestamp")
      " initarg, which is used to specify the timestamp for the event." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "event-timestamp")) :PARAMS ((:I "event")) :KIND ("Generic Function")) (:PAR)
      "Returns an integer that is a monotonically increasing timestamp for the the " (:TERM "event") " "
      (:GROUP (:FONT :FACE :I) "event") ". The timestamp must have at least as many bits of precision as a fixnum."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "event-type")) :PARAMS ((:I "event")) :KIND ("Generic Function")) (:PAR)
      "For the " (:TERM "event") " " (:GROUP (:FONT :FACE :I) "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")
      "." (:PAR) "All event classes must implement methods for " (:CL "event-type") " and " (:CL "event-timestamp") "."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "device-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL ":sheet")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":modifier-state")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "The instantiable class that corresponds to any sort of device event. This is a subclass of " (:CL "event") "."
      (:PAR) "All subclasses of " (:CL "device-event") " must take the " (:CL ":sheet") " and " (:CL ":modifier-state")
      " initargs, which are used to specify the sheet and modifier state components for the event." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "event-sheet")) :PARAMS ((:I "device-event")) :KIND ("Generic Function")) (:PAR)
      "Returns the sheet associated with the event " (:GROUP (:FONT :FACE :I) "device-event") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "event-modifier-state")) :PARAMS ((:I "device-event")) :KIND ("Generic Function"))
      (:PAR)
      "Returns an integer 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+") "." (:PAR)
      "All device event classes must implement methods for " (:CL "event-sheet") " and " (:CL "event-modifier-state")
      "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "keyboard-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL ":key-name")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "The instantiable class that corresponds to any sort of keyboard event. This is a subclass of "
      (:CL "device-event") "." (:PAR) "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." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "keyboard-event-key-name")) :PARAMS ((:I "keyboard-event")) :KIND ("Generic Function"))
      (:PAR)
      "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."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "keyboard-event-character")) :PARAMS ((:I "keyboard-event")) :KIND ("Generic Function"))
      (:PAR) "Returns the character associated with the event " (:GROUP (:FONT :FACE :I) "keyboard-event")
      ", if there is any." (:PAR) "All keyboard event classes must implement methods for "
      (:CL "keyboard-event-key-name") " and " (:CL "keyboard-event-character") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "key-press-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL "key-release-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable classes that correspond to a key press or release event. This is a subclass of "
      (:CL "keyboard-event") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL ":pointer")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":button")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":x")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":y")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "The instantiable class that corresponds to any sort of pointer event. This is a subclass of "
      (:CL "device-event") "." (:PAR) "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 " (:MATH "x") " and "
      (:MATH "y") " position of the pointer at the time of the event. The sheet's " (:MATH "x") " and " (:MATH "y")
      " positions are derived from the supplied native " (:MATH "x") " and " (:MATH "y")
      " positions and the sheet itself." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-event-x")) :PARAMS ((:I "pointer-event")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "pointer-event-y")) :PARAMS ((:I "pointer-event")) :KIND ("Generic Function")) (:PAR)
      "Returns the " (:MATH "x") " and " (:MATH "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."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "pointer-event-native-x")) :PARAMS ((:I "pointer-event")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "pointer-event-native-y")) :PARAMS ((:I "pointer-event")) :KIND ("Generic Function"))
      (:PAR) "Returns the " (:MATH "x") " and " (:MATH "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."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "pointer-event-pointer")) :PARAMS ((:I "pointer-event")) :KIND ("Generic Function"))
      (:PAR) "Returns the pointer object to which this event refers." (:PAR)
      "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") ", and " (:CL "pointer-event-pointer") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-button-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that corresponds to any sort of pointer button event. This is a subclass of "
      (:CL "pointer-event") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "pointer-event-button")) :PARAMS ((:I "pointer-button-event")) :KIND
       ("Generic Function"))
      (:PAR)
      "Returns the an integer corresponding to the pointer button that was pressed or released, which will be one of "
      (:CL "+pointer-left-button+") ", " (:CL "+pointer-middle-button+") ", or " (:CL "+pointer-right-button+") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-button-press-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL "pointer-button-release-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL "pointer-button-hold-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable classes that correspond to a pointer button press, button release, and click-and-hold events. These are subclasses of "
      (:CL "pointer-button-event") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-click-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL "pointer-double-click-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL "pointer-click-and-hold-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable classes that correspond to a pointer button press, followed immediately by (respectively) a button release, another button press, or pointer motion. These are subclasses of "
      (:CL "pointer-button-event") ". Ports are not required to generate these events." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-motion-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that corresponds to any sort of pointer motion event. This is a subclass of "
      (:CL "pointer-event") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-boundary-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that corresponds to a pointer motion event that crosses some sort of sheet boundary. This is a subclass of "
      (:CL "pointer-motion-event") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "pointer-boundary-event-kind")) :PARAMS ((:I "pointer-boundary-event")) :KIND
       ("Generic Function"))
      (:PAR) "Returns the \"kind\" of boundary event, which will be one of " (:CL ":ancestor") ", " (:CL ":virtual")
      ", " (:CL ":inferior") ", " (:CL ":nonlinear") ", " (:CL ":nonlinear-virtual") ", or " (:CL "nil")
      ". These event kinds correspond to the detail members for X11 enter and exit events." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-enter-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL "pointer-exit-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable classes that correspond to a pointer enter or exit event. These are subclasses of "
      (:CL "pointer-boundary-event") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "window-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL ":region")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "The instantiable class that corresponds to any sort of windowing event. This is a subclass of " (:CL "event")
      "." (:PAR) "All subclasses of " (:CL "window-event") " must take a " (:CL ":region")
      " initarg, which is used to specify the damage region associated with the event." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "window-event-region")) :PARAMS ((:I "window-event")) :KIND ("Generic Function"))
      (:PAR) "Returns the region of the sheet that is affected by a window event." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "window-event-native-region")) :PARAMS ((:I "window-event")) :KIND ("Generic Function"))
      (:PAR) "Returns the region of the sheet in native coordinates." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "window-event-mirrored-sheet")) :PARAMS ((:I "window-event")) :KIND ("Generic Function"))
      (:PAR) "Returns the mirrored sheet that is attached to the mirror on which the event occurred." (:PAR)
      "All window event classes must implement methods for " (:CL "window-event-region") ", "
      (:CL "window-event-native-region") ", and " (:CL "window-event-mirrored-sheet") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "window-configuration-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that corresponds to a window changing its size or position. This is a subclass of "
      (:CL "window-event") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "window-repaint-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that corresponds to a request to repaint the window. This is a subclass of "
      (:CL "window-event") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "window-manager-event")) :PARAMS ((:I)) :KIND ("Class"))
      (:SIGNATURE :NAME ((:CL ":sheet")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "The instantiable class that corresponds to any sort of window manager event. This is a subclass of "
      (:CL "event") "." (:PAR) "All subclasses of " (:CL "window-manager-event") " must take a " (:CL ":sheet")
      " initarg, which is used to specify the sheet on which the window manager acted." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "window-manager-delete-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that corresponds to window manager event that causes a host window to be deleted. This is a subclass of "
      (:CL "window-manager-event") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "timer-event")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that corresponds to a timeout event. This is a subclass of " (:CL "event") "." (:PAR)
      " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "+pointer-left-button+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+pointer-middle-button+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+pointer-right-button+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "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." (:PAR)
      "These constants are powers of 2 so that they can be combined with " (:CL "logior") " and tested with "
      (:CL "logtest") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "+shift-key+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+control-key+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+meta-key+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+super-key+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+hyper-key+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "Constants that correspond to the shift, control, meta, super, and hyper modifier keys being held down on the keyboard. These constants are powers of 2 that are disjoint from the pointer button constants, so that they can be combined with "
      (:CL "logior") " and tested with " (:CL "logtest") "." (:PAR) (:CL "event-modifier-state")
      " will return some combination of these values." (:PAR)
      "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."
      (:PAR) " "))
    (:SECTION :TITLE ("8.3 " "Output Protocol") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "The output protocol is concerned with the appearance of displayed output on the window associated with a sheet. The sheet output protocol is responsible for providing a means of doing output to a sheet, and for delivering repaint requests to the sheet's client."
     (:PAR)
     "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." (:PAR) " "
     (:SECTION :TITLE ("8.3.1 " "Output Properties") :KIND :SUBSECTION :NAME (4 5 4 10) (:PAR)
      "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."
      (:PAR) "If a sheet is mute for output, it is an error to set any of these values." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to the output state for some kind of sheet. There is no single advertised standard medium class. If you want to create a new class that behaves like a medium, it should be a subclass of "
       (:CL "medium") ". All instantiable subclasses of " (:CL "medium") " must obey the medium protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "mediump")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "medium")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "basic-medium")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The basic class on which all CLIM mediums are built, a subclass of " (:CL "medium")
       ". This class is an abstract class, intended only to be subclassed, not instantiated. " (:PAR)
       " 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." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-foreground")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-foreground)")) :PARAMS ((:I "design medium")) :KIND ("Generic Function"))
       (:PAR) "Returns (and, with " (:CL "setf") ", sets) the current foreground ink for the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium") ". This is described in detail in Chapter " (:REF :NAME "drawing-options")
       "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-background")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-background)")) :PARAMS ((:I "design medium")) :KIND ("Generic Function"))
       (:PAR) "Returns (and, with " (:CL "setf") ", sets) the current background ink for the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium") ". This is described in detail in Chapter " (:REF :NAME "drawing-options")
       "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-ink")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-ink)")) :PARAMS ((:I "design medium")) :KIND ("Generic Function")) (:PAR)
       "Returns (and, with " (:CL "setf") ", sets) the current drawing ink for the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium") ". This is described in detail in Chapter " (:REF :NAME "drawing-options")
       "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-transformation")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-transformation)")) :PARAMS ((:I "transformation medium")) :KIND
        ("Generic Function"))
       (:PAR) "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") " " (:GROUP (:FONT :FACE :I) "medium")
       "'s coordinate system. By default, it is the identity transformation. This is described in detail in Chapter "
       (:REF :NAME "drawing-options") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-clipping-region")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-clipping-region)")) :PARAMS ((:I "region medium")) :KIND
        ("Generic Function"))
       (:PAR) "Returns (and, with " (:CL "setf")
       ", sets) the clipping region that encloses all output performed on the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "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" (:PAR)
       (:PRE "
(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)))
")
       (:PAR)
       "are two rectangles. The first one has edges of (0,0,5,5), while the second one has edges of (0,0,20,20)."
       (:PAR) "By default, the user clipping region is the value of " (:CL "+everywhere+") "." (:PAR)
       (:GROUP (:FONT :FACE :B) "Major issue: ") " "
       (:GROUP (:FONT :FACE :SL)
        "What exactly are \"user coordinates\"? We need to define all of the coordinate systems in one place: device, window, stream, etc. --- SWM")
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-line-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-line-style)")) :PARAMS ((:I "line-style medium")) :KIND
        ("Generic Function"))
       (:PAR) "Returns (and, with " (:CL "setf") ", sets) the current line style for the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium") ". This is described in detail in Chapter " (:REF :NAME "drawing-options")
       " and Section " (:REF :NAME "line-styles") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-text-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-text-style)")) :PARAMS ((:I "text-style medium")) :KIND
        ("Generic Function"))
       (:PAR) "Returns (and, with " (:CL "setf") ", sets) the current text style for the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium")
       " of any textual output that may be displayed on the window. This is described in detail in Chapter "
       (:REF :NAME "drawing-options") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-default-text-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf medium-default-text-style)")) :PARAMS ((:I "text-style medium")) :KIND
        ("Generic Function"))
       (:PAR) "Returns (and, with " (:CL "setf") ", sets) the default text style for output on the " (:TERM "medium")
       " " (:GROUP (:FONT :FACE :I) "medium") ". This is described in detail in Chapter "
       (:REF :NAME "drawing-options") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-merged-text-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:PAR) "Returns the actual text style used in rendering text on the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium") ". It returns the result of" (:PAR)
       (:PRE " 
(merge-text-styles (medium-text-style medium)
                   (medium-default-text-style medium))
")
       (:PAR) "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." (:PAR) " "))
     (:SECTION :TITLE ("8.3.2 " "Output Protocol Functions") :KIND :SUBSECTION :NAME (4 5 4 10) (:PAR)
      "The output protocol functions on mediums (and sheets that support the standard output protocol) include those functions described in Section "
      (:REF :NAME "graphics-protocols") "." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL) "We need to do a little better than this. --- SWM") (:PAR) " ")
     (:SECTION :TITLE ("8.3.3 " "Output Protocol Classes") :KIND :SUBSECTION :NAME (4 5 4 10) (:PAR)
      "The following classes implement the standard output protocols. None of the five following classes is instantiable."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-sheet-output-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed in to any sheet that provides the standard output protocol, such as repainting and graphics."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-mute-output-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed in to any sheet that provides none of the output protocol." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-with-medium-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is used for any sheet that has either a permanent or a temporary medium." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "permanent-medium-sheet-output-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed in to any sheet that always has a medium associated with it. It is a subclass of "
       (:CL "sheet-with-medium-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "temporary-medium-sheet-output-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed in to any sheet that may have a medium associated with it, but does not necessarily have a medium at any given instant. It is a subclass of "
       (:CL "sheet-with-medium-mixin") "." (:PAR) " "))
     (:SECTION :TITLE ("8.3.4 " "Associating a Medium with a Sheet") :KIND :SUBSECTION :NAME (4 5 4 10) (:PAR)
      "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."
      (:PAR)
      "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."
      (:PAR) "To associate a sheet with a medium, the macro " (:CL "with-sheet-medium")
      " is used. Only sheets that are subclasses of " (:CL "sheet-with-medium-mixin")
      " may have a medium associated with them." (:PAR) " "
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-sheet-medium")) :PARAMS
        ((:I "(medium sheet) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Within the body, the variable " (:GROUP (:FONT :FACE :I) "medium")
       " is bound to the sheet's medium. If the sheet does not have a medium permanently allocated, one will be allocated and associated with the sheet for the duration of the body (by calling "
       (:CL "engraft-medium")
       "), and then degrafted from the sheet and deallocated 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") "." (:PAR) "This macro will signal a runtime error if sheet is not a subclass of "
       (:CL "sheet-with-medium-mixin") "." (:PAR) "The " (:GROUP (:FONT :FACE :I) "medium")
       " argument is not evaluated, and must be a symbol that is bound to a medium. " (:GROUP (:FONT :FACE :I) "body")
       " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-sheet-medium-bound")) :PARAMS
        ((:I "(sheet medium) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) (:CL "with-sheet-medium-bound") " is used to associate the specific medium "
       (:GROUP (:FONT :FACE :I) "medium") " with the sheet " (:GROUP (:FONT :FACE :I) "sheet")
       " for the duration of the body " (:GROUP (:FONT :FACE :I) "body")
       ". Typically, a single medium will be allocated an passed to several different sheets that can use the same medium."
       (:PAR)
       "If the sheet already has a medium allocated to it, the new medium will not be grafted to the sheet, and "
       (:CL "with-sheet-medium-bound") " will simple evaluate the body. If the value of "
       (:GROUP (:FONT :FACE :I) "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") "."
       (:PAR) "This macro will signal a runtime error if sheet is not a subclass of " (:CL "sheet-with-medium-mixin")
       "." (:PAR) (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-medium")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns the medium associated with the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") ". If "
       (:GROUP (:FONT :FACE :I) "sheet") " does not have a medium allocated to it, " (:CL "sheet-medium") " returns "
       (:CL "nil") "." (:PAR) "This function will signal an error if sheet is not a subclass of "
       (:CL "sheet-with-medium-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-sheet")) :PARAMS ((:I "medium")) :KIND ("Generic Function")) (:PAR)
       "Returns the sheet associated with the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". If "
       (:GROUP (:FONT :FACE :I) "medium") " is not grafted to a sheet, " (:CL "medium-sheet") " returns " (:CL "nil")
       "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-drawable")) :PARAMS ((:I "medium")) :KIND ("Generic Function")) (:PAR)
       "Returns an implementation-dependent object that corresponds to the actual host window that will be drawn on when the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " is drawn on. If " (:GROUP (:FONT :FACE :I) "medium")
       " is not grafted to a sheet or the medium's sheet is not currently mirrored on a display server, "
       (:CL "medium-drawable") " returns " (:CL "nil") "." (:PAR)
       "Programmers can use this function to get a host window system object that can be manipulated using the functions of the host window system. This might be done in order to explicitly trade of performance against portability."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "port")) :PARAMS ((:I "(medium " (:CL "basic-medium") ")")) :KIND ("Method"))
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "medium")
       " is both grafted to a sheet and the sheet is currently mirrored on a display server, this returns the port with which "
       (:GROUP (:FONT :FACE :I) "medium") " is associated. Otherwise it returns " (:CL "nil") "." (:PAR))
      (:SECTION :TITLE ("8.3.4.1 " "Grafting and Degrafting of Mediums") :KIND :SUBSUBSECTION :NAME (1 4 5 4 10) (:PAR)
       "The following generic functions are the protocol-level functions responsible for the allocating, deallocating, grafting, and degrafting of mediums. They are not intended for general use by programmers."
       (:PAR)
       (:DEFUN (:SIGNATURE :NAME ((:CL "allocate-medium")) :PARAMS ((:I "port sheet")) :KIND ("Generic Function"))
        (:PAR) "Allocates a medium from the " (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port")
        "'s medium resource, or calls " (:CL "make-medium")
        " on the port to create a new medium if the resource is empty or the port does not maintain a resource of mediums. The resulting medium will have its default characteristics determined by "
        (:GROUP (:FONT :FACE :I) "sheet") "." (:PAR))
       (:DEFUN (:SIGNATURE :NAME ((:CL "deallocate-medium")) :PARAMS ((:I "port medium")) :KIND ("Generic Function"))
        (:PAR) "Returns the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " to "
        (:GROUP (:FONT :FACE :I) "port") "'s medium resource." (:PAR))
       (:DEFUN (:SIGNATURE :NAME ((:CL "make-medium")) :PARAMS ((:I "port sheet")) :KIND ("Generic Function")) (:PAR)
        "Creates a new medium for the " (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port")
        ". The new medium will have its default characteristics determined by " (:GROUP (:FONT :FACE :I) "sheet") "."
        (:PAR))
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "engraft-medium")) :PARAMS ((:I "medium port sheet")) :KIND ("Generic Function"))
        (:PAR) "Grafts the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " to the " (:TERM "sheet") " "
        (:GROUP (:FONT :FACE :I) "sheet") " on the " (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port") "." (:PAR)
        "The default method on " (:CL "basic-medium") " will set " (:CL "medium-sheet") " on "
        (:GROUP (:FONT :FACE :I) "medium")
        " to point to the sheet, and will set up the medium state (foreground ink, background ink, and so forth) from the defaults gotten from "
        (:GROUP "sheet")
        ". Each implementation may specialize this generic function in order to set up such things as per-medium ink caches, and so forth."
        (:PAR))
       (:DEFUN
        (:SIGNATURE :NAME ((:CL "degraft-medium")) :PARAMS ((:I "medium port sheet")) :KIND ("Generic Function"))
        (:PAR) "Degrafts the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " from the " (:TERM "sheet") " "
        (:GROUP (:FONT :FACE :I) "sheet") " on the " (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port") "." (:PAR)
        "The default method on " (:CL "basic-medium") " will set " (:CL "medium-sheet") " back to " (:CL "nil")
        ". Each implementation may specialize this generic function in order to clear any caches it has set up, and so forth."
        (:PAR) " "))))
    (:SECTION :TITLE ("8.4 " "Repaint Protocol") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "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."
     (:PAR) " "
     (:SECTION :TITLE ("8.4.1 " "Repaint Protocol Functions") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "queue-repaint")) :PARAMS ((:I "sheet repaint-event")) :KIND ("Generic Function"))
       (:PAR) "Requests that the repaint event " (:GROUP (:FONT :FACE :I) "repaint-event")
       " be placed in the input queue of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       ". A program that reads events out of the queue will be expected to call " (:CL "handle-event")
       " for the sheet using the repaint region gotten from " (:GROUP (:FONT :FACE :I) "repaint-event") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "handle-repaint")) :PARAMS ((:I "sheet region")) :KIND ("Generic Function"))
       (:PAR) "Implements repainting for a given sheet class. " (:TERM "sheet") " is the sheet to repaint and "
       (:GROUP (:FONT :FACE :I) "region") " is the region to repaint." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "repaint-sheet")) :PARAMS ((:I "sheet region")) :KIND ("Generic Function"))
       (:PAR) "Recursively causes repainting of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       " and any of its descendants that overlap the " (:TERM "region") " " (:GROUP (:FONT :FACE :I) "region") "."
       (:PAR)
       "All CLIM implementations must support repainting for regions that are rectangles or region sets composed entirely of rectangles."
       (:PAR) " "))
     (:SECTION :TITLE ("8.4.2 " "Repaint Protocol Classes") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      "The following classes implement the standard repaint protocols. None of the three following classes is instantiable."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-repainting-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR) "Defines a "
       (:CL "dispatch-repaint") " method that calls " (:CL "queue-repaint") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "immediate-repainting-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "Defines a " (:CL "dispatch-repaint") " method that calls " (:CL "handle-repaint") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-mute-repainting-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "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."
       (:PAR) " ")))
    (:SECTION :TITLE ("8.5 " "Sheet Notification Protocol") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "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." (:PAR)
     (:SECTION :TITLE ("8.5.1 " "Relationship to Window System Change Notifications") :KIND :SUBSECTION :NAME
      (2 5 4 10) (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL) "More to be written. --- RSL") (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "note-sheet-grafted")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-sheet-degrafted")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-sheet-adopted")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-sheet-disowned")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-sheet-enabled")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-sheet-disabled")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "These notification functions are invoked when the state change has been made to the " (:TERM "sheet") " "
       (:GROUP (:FONT :FACE :I) "sheet") "." (:PAR) " "))
     (:SECTION :TITLE ("8.5.2 " "Sheet Geometry Notifications") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " " (:GROUP (:FONT :FACE :SL) "More to be written. --- RSL") (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "note-sheet-region-changed")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-sheet-transformation-changed")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:PAR) "These notification functions are invoked when the region or transformation of the " (:TERM "sheet")
       (:GROUP (:FONT :FACE :I) "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") "." (:PAR) " "))))
   (:SECTION :TITLE ("9 " "Ports, Grafts, and Mirrored Sheets") :KIND :CHAPTER :NAME (4 10) " "
    (:LABEL :NAME "ports-and-grafts") (:PAR)
    (:SECTION :TITLE ("9.1 " "Introduction") :KIND :SECTION :NAME (4 4 10) (:PAR)
     "A sheet hierarchy must be attached to a display server so as to permit input and output. This is managed by the use of "
     (:CONCEPT "ports") " and " (:CONCEPT "grafts") "." (:PAR))
    (:SECTION :TITLE ("9.2 " "Ports") :KIND :SECTION :NAME (4 4 10) (:PAR) "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."
     (:PAR) "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."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "port")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a port. If you want to create a new class that behaves like a port, it should be a subclass of "
      (:CL "port") ". All instantiable subclasses of " (:CL "port") " must obey the port protocol. " (:PAR)
      "All of the subclasses of " (:CL "port") " are mutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "portp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "port") ", otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "basic-port")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The basic class on which all CLIM ports are built, a subclass of " (:CL "port")
      ". This class is an abstract class, intended only to be subclassed, not instantiated. " (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-port")) :PARAMS
       ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "initargs " (:GROUP (:FONT :FACE :TT) "&key ") "(server-path "
         (:CL "*default-server-path*") ") " (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
       :KIND ("Function"))
      (:PAR) "Finds a port that provides a connection to the window server addressed by "
      (:GROUP (:FONT :FACE :I) "server-path")
      ". If no such connection exists, a new connection will be constructed and returned. The initargs in "
      (:GROUP (:FONT :FACE :I) "initargs") " will be passed to the function that constructed the new port." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*default-server-path*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "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." (:PAR) "The value of " (:CL "*default-server-path*")
      " is a cons of a port type followed by a list of initargs." (:PAR)
      "The following are the recommendations for port types and their initargs. This list is not intended to be comprehensive, nor is it required that a CLIM implementation support any of these port types."
      (:PAR) (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL ":clx")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&key ") "host display-id screen-id"))
       :KIND ("Server Path"))
      (:PAR) "Given this server path, " (:CL "find-port") " finds a port for the X server on the given "
      (:GROUP (:FONT :FACE :I) "host") ", using the " (:GROUP (:FONT :FACE :I) "display-id") " and "
      (:GROUP (:FONT :FACE :I) "screen-id") "." (:PAR)
      "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." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL ":motif")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&key ") "host display-id screen-id"))
       :KIND ("Server Path"))
      (:PAR) "Given this server path, " (:CL "find-port") " finds a port for a Motif X server on the given "
      (:GROUP (:FONT :FACE :I) "host") ", using the " (:GROUP (:FONT :FACE :I) "display-id") " and "
      (:GROUP (:FONT :FACE :I) "screen-id") "." (:PAR)
      "On a Unix host, if these values are not supplied, the defaults come from the " (:CL "DISPLAY")
      " environment variable." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL ":openlook")) :PARAMS
       ((:I (:GROUP (:FONT :FACE :TT) "&key ") "host display-id screen-id")) :KIND ("Server Path"))
      (:PAR) "Given this server path, " (:CL "find-port") " finds a port for an OpenLook X server on the given "
      (:GROUP (:FONT :FACE :I) "host") ", using the " (:GROUP (:FONT :FACE :I) "display-id") " and "
      (:GROUP (:FONT :FACE :I) "screen-id") "." (:PAR)
      "On a Unix host, if these values are not supplied, the defaults come from the " (:CL "DISPLAY")
      " environment variable." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL ":genera")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&key ") "screen")) :KIND
       ("Server Path"))
      (:PAR) "Given this server path, " (:CL "find-port")
      " finds a port for local Genera platform on the screen object " (:GROUP (:FONT :FACE :I) "screen") ". "
      (:GROUP (:FONT :FACE :I) "screen") " defaults to " (:GROUP (:FONT :FACE :I) "tv:main-screen")
      ", but could also be an object return from " (:CL "color:find-color-screen") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "port")) :PARAMS ((:I "object")) :KIND ("Generic Function")) (:PAR)
      "Returns the port associated with " (:GROUP (:FONT :FACE :I) "object") ". " (:CL "port")
      " is defined for all sheet classes (including grafts and streams that support the CLIM graphics protocol), mediums, and application frames. For degrafted sheets or other objects that aren't currently associated with particular ports, "
      (:CL "port") " will return " (:CL "nil") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-port-locked")) :PARAMS ((:I "(port) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Executes " (:GROUP (:FONT :FACE :I) "body") " after grabbing a lock associated with the " (:TERM "port")
      " " (:GROUP (:FONT :FACE :I) "port") ", which may be a port or any object on which the function " (:CL "port")
      " works. If " (:GROUP (:FONT :FACE :I) "object") " currently has no port, " (:GROUP (:FONT :FACE :I) "body")
      " will be executed without locking." (:PAR) (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "map-over-ports")) :PARAMS ((:I "function")) :KIND ("Function")) (:PAR) "Invokes "
      (:GROUP (:FONT :FACE :I) "function")
      " on each existing port. Function is a function of one argument, the port; it has dynamic extent." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "port-server-path")) :PARAMS ((:I "port")) :KIND ("Generic Function")) (:PAR)
      "Returns the server path associated with the " (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "port-name")) :PARAMS ((:I "port")) :KIND ("Generic Function")) (:PAR)
      "Returns an implementation-dependent string that is the name of the port. For example, a " (:CL ":clx")
      " port might have a name of " (:CL "\"summer:0.0\"") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "port-type")) :PARAMS ((:I "port")) :KIND ("Generic Function")) (:PAR)
      "Returns the type of the port, that is, the first element of the server path spec." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "port-properties")) :PARAMS ((:I "port indicator")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf port-properties)")) :PARAMS ((:I "property port indicator")) :KIND
       ("Generic Function"))
      (:PAR)
      "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."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "restart-port")) :PARAMS ((:I "port")) :KIND ("Generic Function")) (:PAR)
      "In a multi-process Lisp, " (:CL "restart-port")
      " restarts the global input processing loop associated with the " (:TERM "port") " "
      (:GROUP (:FONT :FACE :I) "port")
      ". All pending input events are discarded. Server resources may or may not be released and reallocated during or after this action."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "destroy-port")) :PARAMS ((:I "port")) :KIND ("Generic Function")) (:PAR)
      "Destroys the connection with the window server represented by the " (:TERM "port") " "
      (:GROUP (:FONT :FACE :I) "port") ". All sheet hierarchies that are associated with "
      (:GROUP (:FONT :FACE :I) "port") " are forcibly degrafted by disowning the children of grafts on "
      (:GROUP (:FONT :FACE :I) "port") " using " (:GROUP (:FONT :FACE :I) "sheet-disown-child")
      ". All server resources utilized by such hierarchies or by any graphics objects on "
      (:GROUP (:FONT :FACE :I) "port") " are released as part of the connection shutdown." (:PAR) " "))
    (:SECTION :TITLE ("9.3 " "Grafts") :KIND :SECTION :NAME (4 4 10) (:PAR) "A " (:CONCEPT "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."
     (:PAR)
     "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."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-grafted-p")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:TERM "true") " if any of the sheet's ancestors is a graft, otherwise returns " (:TERM "false") "."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-graft")) :PARAMS
       ((:I (:GROUP (:FONT :FACE :TT) "&key ") "(server-path " (:CL "*default-server-path*") ")  (port "
         (:CL "(find-port :server-path server-path)") ")  (orientation " (:CL ":default") ") (units " (:CL ":device")
         ")"))
       :KIND ("Function"))
      (:PAR) "Finds a graft that represents the display device on the port " (:GROUP (:FONT :FACE :I) "port")
      " that also matches the other supplied parameters. If no such graft exists, a new graft is constructed and returned."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "server-path") " is supplied, " (:CL "find-graft")
      " finds a graft whose port provides a connection to the window server addressed by "
      (:GROUP (:FONT :FACE :I) "server-path") "." (:PAR) "It is an error to provide both "
      (:GROUP (:FONT :FACE :I) "port") " and " (:GROUP (:FONT :FACE :I) "server-path") " in a call to "
      (:CL "find-graft") "." (:PAR) (:GROUP (:FONT :FACE :I) "orientation")
      " specifies the orientation of the graft's coordinate system. Supported values are " (:CL ":default") " and "
      (:CL ":graphics") ", which have the meanings describe below:" (:PAR)
      (:UL
       (:LI (:CL ":default")
        "---a coordinate system with its origin is in the upper left hand corner of the display device with "
        (:MATH "y") " increasing from top to bottom and " (:MATH "x") " increasing from left to right." (:PAR))
       (:LI (:CL ":graphics")
        "---a coordinate system with its origin in the lower left hand corner of the display device with " (:MATH "y")
        " increasing from bottom to top and " (:MATH "x") " increasing from left to right. "))
      (:PAR) (:GROUP (:FONT :FACE :I) "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." (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL) "I don't know how much of this is obsolete. --- RSL") (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "graft")) :PARAMS ((:I "object")) :KIND ("Generic Function")) (:PAR)
      "Returns the graft currently associated with " (:GROUP (:FONT :FACE :I) "object") ". " (:CL "graft")
      " is defined for all sheet classes (including streams that support the CLIM graphics protocol), mediums, and application frames. For degrafted sheets or other objects that aren't currently associated with a particular graft, "
      (:CL "graft") " will return " (:CL "nil") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "map-over-grafts")) :PARAMS ((:I "function port")) :KIND ("Function")) (:PAR)
      "Invokes " (:GROUP (:FONT :FACE :I) "function") " on each existing graft associated with the " (:TERM "port") " "
      (:GROUP (:FONT :FACE :I) "port") ". " (:GROUP (:FONT :FACE :I) "function")
      " is a function of one argument, the graft; it has dynamic extent." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-graft-locked")) :PARAMS
       ((:I "(graft) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:PAR) "Executes " (:GROUP (:FONT :FACE :I) "body") " after grabbing a lock associated with the " (:TERM "graft")
      " " (:GROUP (:FONT :FACE :I) "graft") ", which may be a graft or any object on which the function " (:CL "graft")
      " works. If " (:GROUP (:FONT :FACE :I) "object") " currently has no graft, " (:GROUP (:FONT :FACE :I) "body")
      " will be executed without locking." (:PAR) (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "graft-orientation")) :PARAMS ((:I "graft")) :KIND ("Generic Function")) (:PAR)
      "Returns the orientation of the " (:TERM "graft") " " (:GROUP (:FONT :FACE :I) "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")
      "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "graft-units")) :PARAMS ((:I "graft")) :KIND ("Generic Function")) (:PAR)
      "Returns the units of the " (:TERM "graft") " " (:GROUP (:FONT :FACE :I) "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") "."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "graft-width")) :PARAMS
       ((:I "graft " (:GROUP (:FONT :FACE :TT) "&key ") "(units " (:CL ":device") ")")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "graft-height")) :PARAMS
       ((:I "graft " (:GROUP (:FONT :FACE :TT) "&key ") "(units " (:CL ":device") ")")) :KIND ("Generic Function"))
      (:PAR) "Returns the width and height of the " (:TERM "graft") " " (:GROUP (:FONT :FACE :I) "graft")
      " (and by extension the associated host window) in the units indicated. " (:GROUP (:FONT :FACE :I) "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 " (:GROUP (:FONT :FACE :I) "unit") " of " (:CL ":screen-sized")
      " is specified, both of these functions will return a value of " (:CL "1") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "graft-pixels-per-millimeter")) :PARAMS ((:I "graft")) :KIND ("Function"))
      (:SIGNATURE :NAME ((:CL "graft-pixels-per-inch")) :PARAMS ((:I "graft")) :KIND ("Function")) (:PAR)
      "Returns the number of pixels per millimeter or inch of the " (:TERM "graft") " "
      (:GROUP (:FONT :FACE :I) "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") "." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "Do we want to support non-square pixels? If so, these functions aren't sufficient. --- Rao")
      (:PAR) " "))
    (:SECTION :TITLE ("9.4 " "Mirrors and Mirrored Sheets") :KIND :SECTION :NAME (4 4 10) (:PAR) "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."
     (:PAR)
     "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."
     (:PAR)
     "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."
     (:PAR)
     "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."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "mirrored-sheet-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "This class is mixed in to sheet classes that can be directly mirrored." (:PAR) " ")
     (:SECTION :TITLE ("9.4.1 " "Mirror Functions") :KIND :SUBSECTION :NAME (2 4 4 10) (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "What kind of an object is a mirror? Is it the Lisp object that is the handle to the actual toolkit window or gadget? --- SWM")
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-direct-mirror")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns the mirror of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       ". If the sheet is not a subclass of " (:CL "mirrored-sheet-mixin") ", this will return " (:CL "nil")
       ". If the sheet is a subclass of " (:CL "mirrored-sheet-mixin") " and does not currently have a mirror, "
       (:CL "sheet-mirror") " will return " (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-mirrored-ancestor")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:PAR) "Returns the nearest mirrored ancestor of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet") "."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-mirror")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns the mirror of the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "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:"
       (:PAR)
       (:PRE "
(defun sheet-mirror (sheet)
  (sheet-direct-mirror (sheet-mirrored-ancestor sheet)))
")
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "realize-mirror")) :PARAMS ((:I "port mirrored-sheet")) :KIND ("Generic Function"))
       (:PAR) "Creates a mirror for the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "mirrored-sheet") " on the "
       (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port")
       ", if it does not already have one. The returned value is the sheet's mirror; the type of this object is implementation dependent."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "destroy-mirror")) :PARAMS ((:I "port mirrored-sheet")) :KIND ("Generic Function"))
       (:PAR) "Destroys the mirror for the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "mirrored-sheet") " on the "
       (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "raise-mirror")) :PARAMS ((:I "port sheet")) :KIND ("Generic Function")) (:PAR)
       "Raises the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       "'s mirror to the top of all of the host windows on the " (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port")
       ". " (:GROUP (:FONT :FACE :I) "sheet") " need not be a directly mirrored sheet." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "bury-mirror")) :PARAMS ((:I "port sheet")) :KIND ("Generic Function")) (:PAR)
       "Buries the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "sheet")
       "'s mirror at the bottom of all of the host windows on the " (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port")
       ". " (:GROUP (:FONT :FACE :I) "sheet") " need not be a directly mirrored sheet." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "port")) :PARAMS ((:I "(sheet " (:CL "basic-sheet") ")")) :KIND ("Method"))
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "sheet")
       " is currently mirrored on a display server, this returns the port with which "
       (:GROUP (:FONT :FACE :I) "sheet") " is associated. Otherwise it returns " (:CL "nil") "." (:PAR) " "))
     (:SECTION :TITLE ("9.4.2 " "Internal Interfaces for Native Coordinates") :KIND :SUBSECTION :NAME (2 4 4 10) (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "Do these functions work on any sheet, or only on sheets that have a mirror, or only on sheets that have a direct mirror? Also, define what a \"native coordinate\" are. Also, do "
       (:CL "sheet-device-transformation") " and " (:CL "sheet-device-region")
       " really account for the user's transformation and clipping region? --- SWM")
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sheet-native-transformation")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:PAR) "Returns the transformation for the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "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."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-native-region")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "Returns the region for the " (:TERM "sheet") " " (:GROUP (:FONT :FACE :I) "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."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sheet-device-transformation")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:PAR)
       "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."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "sheet-device-region")) :PARAMS ((:I "sheet")) :KIND ("Generic Function")) (:PAR)
       "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."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "invalidate-cached-transformations")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:PAR) (: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") " " (:GROUP (:FONT :FACE :I) "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." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "invalidate-cached-regions")) :PARAMS ((:I "sheet")) :KIND ("Generic Function"))
       (:PAR) (: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") " " (:GROUP (:FONT :FACE :I) "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." (:PAR) " "))))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part IV: " "Sheet and Medium Output Facilities") :NAME (10) " " " "
   (:SECTION :TITLE ("10 " "Drawing Options") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "drawing-options") (:PAR)
    "This chapter describes the drawing options that are used by CLIM's drawing functions, and the relationship between drawing options, sheets, and mediums. These drawing options control various aspects of the drawing process, and can be provided as keyword arguments to all of the drawing functions."
    (:PAR) " "
    (:SECTION :TITLE ("10.1 " "Medium Components") :KIND :SECTION :NAME (3 5 10) (:PAR)
     "Medium objects contain components that correspond to the drawing options; when no value for a drawing option is explicitly provided to a drawing function, it is taken from the medium. These values can be directly queried or modified using accessors defined on the sheet or medium. They can also be temporarily bound within a dynamic context using "
     (:CL "with-drawing-options") ", " (:CL "with-text-style") ", and related forms." (:PAR) (:CL "setf")
     " of one of these components while it is temporarily bound (via " (:CL "with-drawing-options")
     ", for instance) takes effect immediately but is undone when the dynamic binding context is exited." (:PAR)
     "In systems that support multiple processes, the consequences are unspecified if one process reads or writes a medium component that is temporarily bound by another process."
     (:PAR)
     "The following functions read and write components of a medium related to drawing options. While these functions are defined for mediums, they can also be called on sheets support the sheet output protocol and on streams that output to such sheets. All classes that support the medium protocol 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." (:PAR) " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-foreground")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "medium-background")) :PARAMS ((:I "medium")) :KIND ("Generic Function")) (:PAR)
      "Returns the foreground and background inks (which are designs) for the " (:TERM "medium") " "
      (:GROUP (:FONT :FACE :I) "medium")
      ", respectively. The foreground ink is the default ink used when drawing. The background ink is the ink used when erasing. See Chapter "
      (:REF :NAME "color") " for a more complete description of designs." (:PAR)
      "Any indirect inks are resolved against the foreground and background at the time a design is rendered." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf medium-foreground)")) :PARAMS ((:I "design medium")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf medium-background)")) :PARAMS ((:I "design medium")) :KIND ("Generic Function"))
      (:PAR) "Sets the foreground and background ink, respectively, for the " (:TERM "medium") " "
      (:GROUP (:FONT :FACE :I) "medium") " to " (:GROUP (:FONT :FACE :I) "design") ". You may not set "
      (:CL "medium-foreground") " or " (:CL "medium-background") " to an indirect ink." (:PAR)
      (:GROUP (:FONT :FACE :I) "design")
      " is an unbounded design. If the background design is not completely opaque at all points, the consequences are unspecified."
      (:PAR)
      "Changing the foreground or background of a sheet that supports output recording causes the contents of the stream's viewport to be erased and redrawn using the new foreground and background."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-ink")) :PARAMS ((:I "medium")) :KIND ("Generic Function")) (:PAR)
      "The current drawing ink for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      ", which can be any design. The drawing functions draw with the color and pattern that this specifies. See Chapter "
      (:REF :NAME "color") " for a more complete description of inks. The " (:CL ":ink")
      " drawing option temporarily changes the value of " (:CL "medium-ink") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "(setf medium-ink)")) :PARAMS ((:I "design medium")) :KIND ("Generic Function"))
      (:PAR) "Sets the current drawing ink for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " to "
      (:GROUP (:FONT :FACE :I) "design") ". " (:GROUP (:FONT :FACE :I) "design") " is as for "
      (:CL "medium-foreground") ", and may be an indirect ink as well." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-transformation")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
      (:PAR) "The current user transformation for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      ". This transformation is used to transform the coordinates supplied as arguments to drawing functions to the coordinate system of the drawing plane. See Chapter "
      (:REF :NAME "transforms") " for a complete description of transformations. The " (:CL ":transformation")
      " drawing option temporarily changes the value of " (:CL "medium-transformation") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf medium-transformation)")) :PARAMS ((:I "transformation medium")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the current user transformation for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      " to the " (:TERM "transformation") " " (:GROUP (:FONT :FACE :I) "transformation") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-clipping-region")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
      (:PAR) "The current clipping region for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      ". The drawing functions do not affect the drawing plane outside this region. The " (:CL ":clipping-region")
      " drawing option temporarily changes the value of " (:CL "medium-clipping-region") "." (:PAR)
      "The clipping region is expressed in user coordinates." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf medium-clipping-region)")) :PARAMS ((:I "region medium")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the current clipping region for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " to "
      (:GROUP (:FONT :FACE :I) "region") ". " (:GROUP (:FONT :FACE :I) "region") " must be a subclass of " (:CL "area")
      ". Furthermore, some implementations may signal an error if the clipping region is not a rectangle or a region set composed entirely of rectangles."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-line-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function")) (:PAR)
      "The current line style for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      ". The line and arc drawing functions render according to this line style. See Section "
      (:REF :NAME "line-styles") " for a complete description of line styles. The " (:CL ":line-style")
      " drawing option temporarily changes the value of " (:CL "medium-line-style") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf medium-line-style)")) :PARAMS ((:I "line-style medium")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the current line style for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " to the "
      (:TERM "line style") " " (:GROUP (:FONT :FACE :I) "line-style") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-default-text-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
      (:PAR) "The default text style for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". "
      (:CL "medium-default-text-style") " will return a fully specified text style, unlike " (:CL "medium-text-style")
      ", which may return a text style with null components. Any text styles that are not fully specified by the time they are used for rendering are merged against "
      (:CL "medium-default-text-style") " using " (:CL "merge-text-styles") "." (:PAR) "The default value for "
      (:CL "medium-default-text-style") " for any medium is " (:CL "*default-text-style*") "." (:PAR) "See Chapter "
      (:REF :NAME "text-styles") " for a complete description of text styles." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf medium-default-text-style)")) :PARAMS ((:I "text-style medium")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the default text style for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " to the "
      (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style") ". " (:GROUP (:FONT :FACE :I) "text-style")
      " must be a fully specified text style." (:PAR)
      "Some CLIM implementations may arrange to erase and redraw the output on an output recording stream when the default text style of the stream is changed. Implementations that do this must obey the proper vertical spacing for output streams, and must reformat tables, graphs, and so forth, as necessary. Because of the expense of this operation, CLIM implementations are not required to support this."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-text-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function")) (:PAR)
      "The current text style for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      ". The text drawing functions, including ordinary stream output, render text as directed by this text style merged against the default text style. This controls both graphical text (such as that drawn by "
      (:CL "draw-text*") ") and stream text (such as that written by " (:CL "write-string") "). See Chapter "
      (:REF :NAME "text-styles") " for a complete description of text styles. The " (:CL ":text-style")
      " drawing option temporarily changes the value of " (:CL "medium-text-style") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf medium-text-style)")) :PARAMS ((:I "text-style medium")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the current text style for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " to the "
      (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style") ". " (:GROUP (:FONT :FACE :I) "text-style")
      " need not be a fully merged text style." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-current-text-style")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
      (:PAR) "The current, fully merged text style for the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      ". This is the text style that will be used when drawing text output, and is the result of merging "
      (:CL "medium-text-style") " against " (:CL "medium-default-text-style") "." (:PAR) " "))
    (:SECTION :TITLE ("10.2 " "Drawing Option Binding Forms") :KIND :SECTION :NAME (3 5 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-drawing-options")) :PARAMS
       ((:I "(medium " (:GROUP (:FONT :FACE :TT) "&rest ") "drawing-options) " (:GROUP (:FONT :FACE :TT) "&body ")
         "body"))
       :KIND ("Macro"))
      (:PAR) "Binds the state of the " (:TERM "medium") " designated by " (:GROUP (:FONT :FACE :I) "medium")
      " to correspond to the supplied drawing options, and executes the body with the new drawing options specified by "
      (:GROUP (:FONT :FACE :I) "drawing-options")
      " in effect. Each option causes binding of the corresponding component of the medium for the dynamic extent of the body. The drawing functions effectively do a "
      (:CL "with-drawing-options") " when drawing option arguments are supplied to them." (:PAR)
      (:GROUP (:FONT :FACE :I) "medium")
      " can be a medium, a sheet that supports the sheet output protocol, or a stream that outputs to such a sheet. The "
      (:GROUP (:FONT :FACE :I) "medium")
      " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
      (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:CL "with-drawing-options") " must be implemented by expanding into a call to "
      (:CL "invoke-with-drawing-options") ", supplying a function that executes " (:GROUP (:FONT :FACE :I) "body")
      " as the " (:GROUP (:FONT :FACE :I) "continuation") " argument to " (:CL "invoke-with-drawing-options")
      ". The exact behavior of this macro is described under " (:CL "invoke-with-drawing-options") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "invoke-with-drawing-options")) :PARAMS
       ((:I "medium continuation " (:GROUP (:FONT :FACE :TT) "&rest ") "drawing-options")) :KIND ("Generic Function"))
      (:PAR) "Binds the state of the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      " to correspond to the supplied drawing options, and then calls the function "
      (:GROUP (:FONT :FACE :I) "continuation") " with the new drawing options in effect. "
      (:GROUP (:FONT :FACE :I) "continuation") " is a function of one argument, the medium; it has dynamic extent. "
      (:GROUP (:FONT :FACE :I) "drawing-options")
      " is a list of alternating keyword-value pairs, and must have even length. Each option in "
      (:GROUP (:FONT :FACE :I) "drawing-options")
      " causes binding of the corresponding component of the medium for the dynamic extent of the body." (:PAR)
      (:GROUP (:FONT :FACE :I) "medium")
      " can be a medium, a sheet that supports the sheet output protocol, or a stream that outputs to such a sheet. All classes that obey the medium protocol must implement a method for "
      (:CL "invoke-with-drawing-options") "." (:PAR)
      "The drawing options can be any of the following, plus any of the suboptions for line styles and text styles. The default value specified for a drawing option is the value to which the corresponding component of a medium is normally initialized."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":ink")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
      "A design that will be used as the ink for drawing operations. The drawing functions draw with the color and pattern that this specifies. The default value is "
      (:CL "+foreground-ink+") ". See Chapter " (:REF :NAME "color") " for a complete description of inks." (:PAR)
      "The " (:CL ":ink") " " (:GROUP (:FONT :FACE :I) "ink") " drawing option temporarily changes the value of "
      (:CL "(medium-ink " (:GROUP (:FONT :FACE :I) "medium") ")") " to " (:GROUP (:FONT :FACE :I) "ink")
      ", replacing the previous ink; the new and old inks are not combined in any way." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL ":transformation")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
      "This transforms the coordinates used as arguments to drawing functions to the coordinate system of the drawing plane. The default value is "
      (:CL "+identity-transformation+") ". See Chapter " (:REF :NAME "transforms")
      " for a complete description of transformations." (:PAR) "The " (:CL ":transformation") " "
      (:GROUP (:FONT :FACE :I) "xform") " drawing option temporarily changes the value of"
      (:CL "(medium-transformation " (:GROUP (:FONT :FACE :I) "medium") ")") " to "
      (:CL "(compose-transformations (medium-transformation "
           (:GROUP (:FONT :FACE :I) "medium")
           ") "
           (:GROUP (:FONT :FACE :I) "xform")
           ")")
      "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL ":clipping-region")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
      "The drawing functions do not affect the drawing plane outside this region. The clipping region must be an "
      (:CL "area")
      ". Furthermore, some implementations might signal an error if the clipping region is not a rectangle or a region set composed entirely of rectangles. Rendering is clipped both by this clipping region and by other clipping regions associated with the mapping from the target drawing plane to the viewport that displays a portion of the drawing plane. The default is "
      (:CL "+everywhere+") ", or in other words, no clipping occurs in the drawing plane, only in the viewport." (:PAR)
      "The " (:CL ":clipping-region") " " (:GROUP (:FONT :FACE :I) "region")
      " drawing option temporarily changes the value of "
      (:CL "(medium-clipping-region " (:GROUP (:FONT :FACE :I) "medium") ")") " to "
      (:CL "(region-intersection (transform-region (medium-transformation "
           (:GROUP (:FONT :FACE :I) "medium")
           ") "
           (:GROUP (:FONT :FACE :I) "region")
           ") (medium-clipping-region "
           (:GROUP (:FONT :FACE :I) "medium")
           "))")
      ". If both a clipping region and a transformation are supplied in the same set of drawing options, the clipping region argument is transformed by the newly composed transformation before calling "
      (:CL "region-intersection") "." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "A better explanation is needed. It does the right thing, but it's hard to tell that from this description. That is, the clipping region is expressed in user coordinates. --- DCPL")
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL ":line-style")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
      "The line and arc drawing functions render according to this line style. The line style suboptions and default are defined in Section "
      (:REF :NAME "line-styles") "." (:PAR) "The " (:CL ":line-style") " " (:GROUP (:FONT :FACE :I) "ls")
      " drawing option temporarily changes the value of "
      (:CL "(medium-line-style " (:GROUP (:FONT :FACE :I) "medium") ")") " to " (:GROUP (:FONT :FACE :I) "ls")
      ", replacing the previous line style; the new and old line styles are not combined in any way." (:PAR)
      "If line style suboptions are supplied, they temporarily change the value of "
      (:CL "(medium-line-style " (:GROUP (:FONT :FACE :I) "medium") ")")
      " to a line style constructed from the specified suboptions. Components not specified by suboptions are defaulted from the "
      (:CL ":line-style") " drawing option, if it is supplied, or else from the previous value of "
      (:CL "(medium-line-style " (:GROUP (:FONT :FACE :I) "medium") ")") ". That is, if both the " (:CL ":line-style")
      " option and line style suboptions are supplied, the suboptions take precedence over the components of the "
      (:CL ":line-style") " option." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL ":text-style")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
      "The text drawing functions, including ordinary stream output, render text as directed by this text style merged against the default text style. The default value has all null components. See Chapter "
      (:REF :NAME "text-styles") " for a complete description of text styles, including the text style suboptions."
      (:PAR) "The " (:CL ":text-style") " " (:GROUP (:FONT :FACE :I) "ts")
      " drawing option temporarily changes the value of "
      (:CL "(medium-text-style " (:GROUP (:FONT :FACE :I) "medium") ")") " to "
      (:CL "(merge-text-styles "
           (:GROUP (:FONT :FACE :I) "ts")
           " (medium-text-style "
           (:GROUP (:FONT :FACE :I) "medium")
           "))")
      "." (:PAR) "If text style suboptions are supplied, they temporarily change the value of "
      (:CL "(medium-text-style " (:GROUP (:FONT :FACE :I) "medium") ")")
      " to a text style constructed from the specified suboptions, merged with the " (:CL ":text-style")
      " drawing option if it is specified, and then merged with the previous value of "
      (:CL "(medium-text-style " (:GROUP (:FONT :FACE :I) "medium") ")") ". That is, if both the " (:CL ":text-style")
      " option and text style suboptions are supplied, the suboptions take precedence over the components of the "
      (:CL ":text-style") " option." (:PAR) " ")
     (:SECTION :TITLE ("10.2.1 " "Transformation \"Convenience\" Forms") :KIND :SUBSECTION :NAME (2 3 5 10) (:PAR)
      "The following three functions are no different than using " (:CL "with-drawing-options") " with the "
      (:CL ":transformation")
      " keyword argument supplied. However, they are sufficiently useful that they are provided as a convenience to programmers."
      (:PAR)
      "In order to preserve referential transparency, these three forms apply the translation, rotation, or scaling transformation first, then the rest of the transformation from "
      (:CL "(medium-transformation " (:GROUP (:FONT :FACE :I) "medium") ")")
      ". That is, the following two forms would return the same transformation (assuming that the medium's transformation in the second example is the identity transformation):"
      (:PAR)
      (:PRE "
(compose-transformations
  (make-translation-transformation dx dy)
  (make-rotation-transformation angle))

(with-translation (medium dx dy)
  (with-rotation (medium angle)
    (medium-transformation medium)))
")
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-translation")) :PARAMS
        ((:I "(medium dx dy) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Establishes a translation on the " (:TERM "medium") " designated by " (:GROUP (:FONT :FACE :I) "medium")
       " that translates by " (:GROUP (:FONT :FACE :I) "dx") " in the " (:MATH "x") " direction and "
       (:GROUP (:FONT :FACE :I) "dy") " in the " (:MATH "y") " direction, and then executes "
       (:GROUP (:FONT :FACE :I) "body") " with that transformation in effect." (:PAR) (:GROUP (:FONT :FACE :I) "dx")
       " and " (:GROUP (:FONT :FACE :I) "dy") " are as for " (:CL "make-translation-transformation") "." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "medium")
       " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
       (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-scaling")) :PARAMS
        ((:I "(medium sx " (:GROUP (:FONT :FACE :TT) "&optional ") "sy origin) " (:GROUP (:FONT :FACE :TT) "&body ")
          "body"))
        :KIND ("Macro"))
       (:PAR) "Establishes a scaling transformation on the " (:TERM "medium") " designated by "
       (:GROUP (:FONT :FACE :I) "medium") " that scales by " (:GROUP (:FONT :FACE :I) "sx") " in the " (:MATH "x")
       " direction and " (:GROUP (:FONT :FACE :I) "sy") " in the " (:MATH "y") " direction, and then executes "
       (:GROUP (:FONT :FACE :I) "body") " with that transformation in effect. If " (:GROUP (:FONT :FACE :I) "sy")
       " is not supplied, it defaults to " (:GROUP (:FONT :FACE :I) "sx") ". If " (:GROUP (:FONT :FACE :I) "origin")
       " is supplied, the scaling is about that point; if it is not supplied, it defaults to "
       (:MATH "(" (:RM "0") "," (:RM "0") ")") "." (:PAR) (:GROUP (:FONT :FACE :I) "sx") " and "
       (:GROUP (:FONT :FACE :I) "sy") " are as for " (:CL "make-scaling-transformation") "." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "medium")
       " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
       (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-rotation")) :PARAMS
        ((:I "(medium angle " (:GROUP (:FONT :FACE :TT) "&optional ") "origin) " (:GROUP (:FONT :FACE :TT) "&body ")
          "body"))
        :KIND ("Macro"))
       (:PAR) "Establishes a rotation on the " (:TERM "medium") " designated by " (:GROUP (:FONT :FACE :I) "medium")
       " that rotates by " (:GROUP (:FONT :FACE :I) "angle") ", and then executes " (:GROUP (:FONT :FACE :I) "body")
       " with that transformation in effect. If " (:GROUP (:FONT :FACE :I) "origin")
       " is supplied, the rotation is about that point; if it is not supplied, it defaults to "
       (:MATH "(" (:RM "0") "," (:RM "0") ")") "." (:PAR) (:GROUP (:FONT :FACE :I) "angle") " and "
       (:GROUP (:FONT :FACE :I) "origin") " are as for " (:CL "make-rotation-transformation") "." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "medium")
       " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
       (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-identity-transformation")) :PARAMS
        ((:I "(medium) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Establishes the identity transformation on the " (:TERM "medium") " designated by "
       (:GROUP (:FONT :FACE :I) "medium") "." (:PAR) "The " (:GROUP (:FONT :FACE :I) "medium")
       " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
       (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) (:PAR)))
     (:SECTION :TITLE ("10.2.2 " "Establishing Local Coordinate Systems") :KIND :SUBSECTION :NAME (2 3 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-local-coordinates")) :PARAMS
        ((:I "(medium " (:GROUP (:FONT :FACE :TT) "&optional ") "x y) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "Binds the dynamic environment to establish a local coordinate system on the " (:TERM "medium")
       " designated by " (:GROUP (:FONT :FACE :I) "medium")
       " with the origin of the new coordinate system at the position " (:MATH "(x,y)")
       ". The \"directionality\" of the coordinate system is otherwise unchanged. " (:GROUP (:FONT :FACE :I) "x")
       " and " (:GROUP (:FONT :FACE :I) "y") " are real numbers, and both default to 0." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "medium")
       " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
       (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-first-quadrant-coordinates")) :PARAMS
        ((:I "(medium " (:GROUP (:FONT :FACE :TT) "&optional ") "x y) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "Binds the dynamic environment to establish a local coordinate system on the " (:TERM "medium")
       " designated by " (:GROUP (:FONT :FACE :I) "medium") " with the positive " (:MATH "x")
       " axis extending to the right and the positive " (:MATH "y")
       " axis extending upward, with the origin of the new coordinate system at the position " (:MATH "(x,y)") ". "
       (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y") " are real numbers, and both default to 0."
       (:PAR) "The " (:GROUP (:FONT :FACE :I) "medium")
       " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
       (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) " ")))
    (:SECTION :TITLE ("10.3 " "Line Styles" (:LABEL :NAME "line-styles")) :KIND :SECTION :NAME (3 5 10) (:PAR)
     "A line or other path is a one-dimensional object. However in order to be visible, the rendering of a line must occupy some non-zero area on the display hardware. A "
     (:CONCEPT "line style")
     " represents the advice of CLIM to the rendering substrate on how to perform the rendering." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "line-style")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class for line styles. If you want to create a new class that behaves like a line style, it should be a subclass of "
      (:CL "line-style") ". All instantiable subclasses of " (:CL "line-style") " must obey the line style protocol. "
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "line-style-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "line style")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-line-style")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "An instantiable class that implements line styles. A subclass of " (:CL "line-style")
      ". This is the class that " (:CL "make-line-style") " instantiates. Members of this class are immutable. "
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-line-style")) :PARAMS
       ((:I (:GROUP (:FONT :FACE :TT) "&key ") "unit thickness joint-shape cap-shape dashes")) :KIND ("Function"))
      (:PAR) "Returns an object of class " (:CL "standard-line-style")
      " with the supplied characteristics. The arguments and their default values are described in Section "
      (:REF :NAME "line-style-options") "." (:PAR) " ")
     (:SECTION :TITLE ("10.3.1 " "Line Style Protocol and Line Style Suboptions" (:LABEL :NAME "line-style-options"))
      :KIND :SUBSECTION :NAME (2 3 5 10) (:PAR)
      "Each of these suboptions has a corresponding reader that can be used to extract a particular component from a line style. The generic functions decribed below comprise the line style protocol; all subclasses of "
      (:CL "line-style") " must implement methods for these generic functions." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL ":line-unit")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "line-style-unit")) :PARAMS ((:I "line-style")) :KIND ("Generic Function")) (:PAR)
       "Gives the unit used for measuring line thickness and dash pattern length for the line style. Possible values are "
       (:CL ":normal") ", " (:CL ":point") ", or " (:CL ":coordinate") ". The meaning of these options is:" (:PAR)
       (:UL
        (:LI (:CL ":normal")
         "---thicknesses and lengths are given in a relative measure in terms of the usual or \"normal\" line thickness. The normal line thickness is the thickness of the \"comfortably visible thin line\", "
         (:GROUP
          "In some window systems, the phrase \"thinnest visible line\" is used. This is not appropriate for CLIM, which intends to be device independent. (For instance, the thinnest visible line on a 400 d.p.i. laser printer is a function of the user's viewing distance from the paper.) Another attribute of a \"normal\" line is that its thickness should approximately match the stroke thickness of \"normal\" text, where again the exact measurements are the province of the rendering engine, not of CLIM.")
         " which is a property of the underlying rendering substrate. This is the default." (:PAR))
        (:LI (:CL ":point")
         "---thicknesses and lengths are given in an absolute measure in terms of printer's points (approximately "
         (:MATH (:RM "1") "/" (:RM "7") (:RM "2")) " of an inch). "
         (:GROUP
          "This measure was chosen so that CLIM implementors who interface CLIM to an underlying rendering engine (the window system) may legitimately choose to make it render as 1 pixel on current (1990) display devices.")
         (:PAR))
        (:LI (:CL ":coordinate")
         "---this means that the same units should be used for line thickness as are used for coordinates. In this case, the line thickness is scaled by the medium's current transformation, whereas "
         (:CL ":normal") " and " (:CL ":point") " do not scale the line thickness. "))
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL ":line-thickness")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "line-style-thickness")) :PARAMS ((:I "line-style")) :KIND ("Generic Function")) (:PAR)
       "The thickness, in the units indicated by " (:CL "line-style-unit")
       ", of the lines or arcs drawn by a drawing function. The thickness must be a real number. The default is 1, which combined with the default unit of "
       (:CL ":normal") ", means that the default line drawn is the \"comfortably visible thin line\"." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":line-joint-shape")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "line-style-joint-shape")) :PARAMS ((:I "line-style")) :KIND ("Generic Function"))
       (:PAR) "Specifies the shape of joints between segments of unfilled figures. The possible shapes are "
       (:CL ":miter") ", " (:CL ":bevel") ", " (:CL ":round") ", and " (:CL ":none") "; the default is " (:CL ":miter")
       ". Note that the joint shape is implemented by the host window system, so not all platforms will necessarily fully support it."
       (:PAR)
       (:FIGURE :NUMBER "10.1" :CAPTION ("Line joint shapes.") " " (:CENTER (:IMG :SRC "line-joint-shapes.png")) "  ")
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":line-cap-shape")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "line-style-cap-shape")) :PARAMS ((:I "line-style")) :KIND ("Generic Function")) (:PAR)
       "Specifies the shape for the ends of lines and arcs drawn by a drawing function, one of " (:CL ":butt") ", :"
       (:CL "square") ", " (:CL ":round") ", or " (:CL ":no-end-point") "; the default is " (:CL ":butt")
       ". Note that the cap shape is implemented by the host window system, so not all platforms will necessarily fully support it."
       (:PAR)
       (:FIGURE :NUMBER "10.2" :CAPTION ("Line cap shapes.") " " (:CENTER (:IMG :SRC "line-cap-shapes.png")) "  ")
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":line-dashes")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "line-style-dashes")) :PARAMS ((:I "line-style")) :KIND ("Generic Function")) (:PAR)
       "Controls whether lines or arcs are drawn as dashed figures, and if so, what the dashing pattern is. Possible values are:"
       (:PAR)
       (:UL (:LI (:CL "nil") "---lines are drawn solid, with no dashing. This is the default." (:PAR))
        (:LI (:CL "t")
         "---lines are drawn dashed, with a dash pattern that is unspecified and may vary with the rendering engine. This allows the underlying display substrate to provide a default dashed line for the programmer whose only requirement is to draw a line that is visually distinguishable from the default solid line."
         (:PAR))
        (:LI
         "A sequence---specifies a sequence, usually a vector, controlling the dash pattern of a drawing function. It is an error if the sequence does not contain an even number of elements. The elements of the sequence are lengths (as real numbers) of individual components of the dashed line or arc. The odd elements specify the length of inked components, the even elements specify the gaps. All lengths are expressed in the units described by "
         (:CL "line-style-unit") ". "))
       (:PAR) "(See also " (:CL "make-contrasting-dash-patterns") ".)" (:PAR)))
     (:SECTION :TITLE ("10.3.2 " "Contrasting Dash Patterns") :KIND :SUBSECTION :NAME (2 3 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-contrasting-dash-patterns")) :PARAMS
        ((:I "n " (:GROUP (:FONT :FACE :TT) "&optional ") "k")) :KIND ("Function"))
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "k") " is not supplied, this returns a vector of "
       (:GROUP (:FONT :FACE :I) "n")
       " dash patterns with recognizably different appearance. Elements of the vector are guaranteed to be acceptable values for "
       (:CL ":dashes") ", and do not include " (:CL "nil")
       ", but their class is not otherwise specified. The vector is a fresh object that may be modified." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "k") " is supplied, it must be an integer between 0 and "
       (:MATH (:GROUP (:FONT :FACE :I) "n") " - " (:RM "1")) " (inclusive), in which case "
       (:CL "make-contrasting-dash-patterns") " returns the " (:GROUP (:FONT :FACE :I) "k")
       "'th dash-pattern rather than returning a vector of dash-patterns." (:PAR)
       "If the implementation does not have " (:GROUP (:FONT :FACE :I) "n") " different contrasting dash patterns, "
       (:CL "make-contrasting-dash-patterns") " signals an error. This will not happen unless "
       (:GROUP (:FONT :FACE :I) "n") " is greater than eight." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "contrasting-dash-pattern-limit")) :PARAMS ((:I "port")) :KIND ("Generic Function"))
       (:PAR) "Returns the number of contrasting dash patterns that can be rendered on any medium on the "
       (:TERM "port") " " (:GROUP (:FONT :FACE :I) "port")
       ". Implementations are encouraged to make this as large as possible, but it must be at least 8. All classes that obey the port protocol must implement a method for this generic function."
       (:PAR)))))
   " "
   (:SECTION :TITLE ("11 " "Text Styles") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "text-styles") (:PAR)
    "When specifying a particular \"appearance\" for rendered characters, there is a tension between portability and access to specific font for a display device. CLIM provides a portable mechanism for describing the desired "
    (:CONCEPT "text style")
    " in abstract terms. Each CLIM \"port\" defines a mapping between these abstract style specifications and particular device-specific fonts. In this way, an application programmer can specify the desired text style in abstract terms secure in the knowledge that an appropriate device font will be selected at run time by CLIM. However, some programmers may require direct access to particular device fonts. The text style mechanism supports specifying device fonts by name, allowing the programmer to sacrifice portability for control."
    (:PAR) " "
    (:SECTION :TITLE ("11.1 " "Text Styles") :KIND :SECTION :NAME (3 5 10) (:PAR)
     "Text style objects have components for family, face, and size. Not all of these attributes need be supplied for a given text style object. Text styles can be merged in much the same way as pathnames are merged; unspecified components in the style object (that is, components that have "
     (:CL "nil")
     " in them) may be filled in by the components of a \"default\" style object. A text style object is called "
     (:CONCEPT "fully specified") " if none of its components is " (:CL "nil")
     ", and the size component is not a relative size (that is, is neither " (:CL ":smaller") " nor " (:CL ":larger")
     ")." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "text-style")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class for text styles. If you want to create a new class that behaves like a text style, it should be a subclass of "
      (:CL "text-style") ". All instantiable subclasses of " (:CL "text-style") " must obey the text style protocol. "
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "text-style-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "text style")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-text-style")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "An instantiable class that implements text styles. It is a subclass of " (:CL "text-style")
      ". This is the class that " (:CL "make-text-style") " instantiates. Members of this class are immutable. " (:PAR)
      "The interface to text styles is as follows:" (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-text-style")) :PARAMS ((:I "family face size")) :KIND ("Function")) (:PAR)
      "Returns an object of class " (:CL "standard-text-style") " with a family of " (:GROUP (:FONT :FACE :I) "family")
      ", a face of " (:GROUP (:FONT :FACE :I) "face") ", and a size of " (:GROUP (:FONT :FACE :I) "size") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "family") " is one of " (:CL ":fix") ", " (:CL ":serif") ", " (:CL ":sans-serif")
      ", or " (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :I) "face") " is one of " (:CL ":roman") ", " (:CL ":bold")
      ", " (:CL ":italic") ", " (:CL "(:bold :italic)") ", or " (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :I) "size")
      " is a real number representing the size in printer's points, one of the logical sizes (" (:CL ":normal") ", "
      (:CL ":tiny") ", " (:CL ":very-small") ", " (:CL ":small") ", " (:CL ":large") ", " (:CL ":very-large") ", "
      (:CL ":huge") "), a relative size (" (:CL ":smaller") " or " (:CL ":larger") "), or " (:CL "nil") "." (:PAR)
      "Implementations are permitted to extend legal values for " (:GROUP (:FONT :FACE :I) "family") ", "
      (:GROUP (:FONT :FACE :I) "face") ", and " (:GROUP (:FONT :FACE :I) "size") "." (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "Need to describe what family, face, size mean in terms of visual appearance. This should also be reconciled with the ISO description of the attributes of a \"text style\", including such things as underlining, subscripts, superscripts, etc. --- York, SWM")
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*default-text-style*")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "The default text style used on a CLIM medium if no text style it explicitly specified for the medium when it it created. This must be a fully merged text style."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*undefined-text-style*")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "The text style that is used as a fallback if no mapping exists for some other text style when some text is about to be rendered on a display device (via "
      (:CL "write-string") " and " (:CL "draw-string*")
      ", for example). This text style be fully merged, and it must have a mapping for all display devices." (:PAR)
      " ")
     (:SECTION :TITLE ("11.1.1 " "Text Style Protocol and Text Style Suboptions") :KIND :SUBSECTION :NAME (1 3 5 10)
      (:PAR) "The following generic functions comprise the text style protocol. All subclasses of " (:CL "text-style")
      " must implement methods for each of these generic functions." (:PAR)
      "Each of the suboptions described below has a corresponding reader accessor that can be used to extract a particular component from a text style."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "text-style-components")) :PARAMS ((:I "text-style")) :KIND ("Generic Function"))
       (:PAR) "Returns the components of the " (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style")
       " as three values, the family, face, and size." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":text-family")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "text-style-family")) :PARAMS ((:I "text-style")) :KIND ("Generic Function")) (:PAR)
       "Specifies the family of the " (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":text-face")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "text-style-face")) :PARAMS ((:I "text-style")) :KIND ("Generic Function")) (:PAR)
       "Specifies the face of the " (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":text-size")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL "text-style-size")) :PARAMS ((:I "text-style")) :KIND ("Generic Function")) (:PAR)
       "Specifies the size of the " (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "parse-text-style")) :PARAMS ((:I "style-spec")) :KIND ("Function")) (:PAR)
       "Returns a text style object. " (:GROUP (:FONT :FACE :I) "style-spec") " may be a " (:CL "text-style")
       " object or a device font, in which case it is returned as is, or it may be a list of the family, face, and size (that is, a \"style spec\"), in which case it is \"parsed\" and a "
       (:CL "text-style")
       " object is returned. This function is for efficiency, since a number of common functions that take a style object as an argument can also take a style spec, in particular "
       (:CL "draw-text") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "merge-text-styles")) :PARAMS ((:I "style1 style2")) :KIND ("Generic Function"))
       (:PAR) "Merges the " (:TERM "text styles") " " (:GROUP (:FONT :FACE :I) "style1") " with "
       (:GROUP (:FONT :FACE :I) "style2") ", that is, returns a new text style that is the same as "
       (:GROUP (:FONT :FACE :I) "style1") ", except that unspecified components in " (:GROUP (:FONT :FACE :I) "style1")
       " are filled in from " (:GROUP (:FONT :FACE :I) "style2")
       ". For convenience, the two arguments may be also be style specs." (:PAR)
       "When merging the sizes of two text styles, if the size from " (:GROUP (:FONT :FACE :I) "style1")
       " is a relative size, the resulting size is either the next smaller or next larger size than is specified by "
       (:GROUP (:FONT :FACE :I) "style2") ". The ordering of sizes, from smallest to largest, is " (:CL ":tiny") ", "
       (:CL ":very-small") ", " (:CL ":small") ", " (:CL ":normal") ", " (:CL ":large") ", " (:CL ":very-large")
       ", and " (:CL ":huge") "." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL)
        "Need to describe face-merging properly. For example, merging a bold face with an italic one can result in a bold-italic face. --- SWM")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "text-style-ascent")) :PARAMS ((:I "text-style medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "text-style-descent")) :PARAMS ((:I "text-style medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "text-style-height")) :PARAMS ((:I "text-style medium")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "text-style-width")) :PARAMS ((:I "text-style medium")) :KIND ("Generic Function"))
       (:PAR) "Returns the ascent, descent, height, and width (respectively) of the font corresponding to the "
       (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style") " as it would be rendered on the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". " (:GROUP (:FONT :FACE :I) "text-style")
       " must be a fully specified text style." (:PAR)
       "The ascent of a font is the distance between the top of the tallest character in that font and the font's baseline. The descent of a font is the distance between the baseline and the bottom of the lowest descending character (usually \"g\", \"p\", \"q\", or \"y\"). The height of a font is the sum of the ascent and the descent of the font. The width of a font is the width of some representative character in the font."
       (:PAR) "The methods for these generic functions will typically specialize both the "
       (:GROUP (:FONT :FACE :I) "text-style") " and " (:GROUP (:FONT :FACE :I) "medium")
       " arguments. Implementations should also provide \"trampoline\" for these generic functions on output sheets; the trampolines will simply call the method for the medium."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "text-style-fixed-width-p")) :PARAMS ((:I "text-style medium")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "text styles") " " (:GROUP (:FONT :FACE :I) "text-style")
       " will map to a fixed-width font on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
       ", otherwise returns " (:TERM "false") ". " (:GROUP (:FONT :FACE :I) "text-style")
       " must be a fully specified text style." (:PAR)
       "The methods for this generic function will typically specialize both the "
       (:GROUP (:FONT :FACE :I) "text-style") " and " (:GROUP (:FONT :FACE :I) "medium")
       " arguments. Implementations should also provide a \"trampoline\" for this generic function for output sheets; the trampoline will simply call the method for the medium."
       (:PAR) " " (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL) "Discuss baselines? Kerning? --- SWM") (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "text-size")) :PARAMS
        ((:I "medium string " (:GROUP (:FONT :FACE :TT) "&key ") "text-style (start " (:CL "0") ") end")) :KIND
        ("Generic Function"))
       (:PAR) "Computes the \"cursor motion\" in device units that would take place if "
       (:GROUP (:FONT :FACE :I) "string") " (which may be either a string or a character) were output to the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " starting at the position "
       (:MATH "(" (:RM "0") "," (:RM "0") ")")
       ". Five values are returned: the total width of the string in device units, the total height of the string in device units, the final "
       (:MATH "x") " cursor position (which is the same as the width if there are no " (:CODE "#\\Newline")
       " characters in the string), the final " (:MATH "y") " cursor position (which is 0 if the string has no "
       (:CODE "#\\Newline") " characters in it, and is incremented by the line height of "
       (:GROUP (:FONT :FACE :I) "medium") " for each " (:CODE "#\\Newline")
       " character in the string), and the string's baseline." (:PAR) (:GROUP (:FONT :FACE :I) "text-style")
       " specifies what text style is to be used when doing the output, and defaults to "
       (:CL "medium-merged-text-style") " of the medium. " (:GROUP (:FONT :FACE :I) "text-style")
       " must be a fully specified text style. " (:GROUP (:FONT :FACE :I) "start") " and "
       (:GROUP (:FONT :FACE :I) "end") " may be used to specify a substring of " (:GROUP (:FONT :FACE :I) "string") "."
       (:PAR)
       "If a programmer needs to account for kerning or the ascent or descent of the text style, he should measure the size of the bounding rectangle of the text rendered on "
       (:GROUP (:FONT :FACE :I) "medium") "." (:PAR)
       "All mediums and output sheets must implement a method for this generic function." (:PAR) " ")))
    (:SECTION :TITLE ("11.2 " "Text Style Binding Forms") :KIND :SECTION :NAME (3 5 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-text-style")) :PARAMS
       ((:I "(medium text-style) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:PAR) "Binds the current text style of the " (:TERM "medium") " designated by "
      (:GROUP (:FONT :FACE :I) "medium") " to correspond to the new text style. "
      (:GROUP (:FONT :FACE :I) "text-style")
      " may either a text style object or a style spec (that is, a list of the a family, a face code, and a size). "
      (:GROUP (:FONT :FACE :I) "body") " is executed with the new text style in effect." (:PAR) "The "
      (:GROUP (:FONT :FACE :I) "medium")
      " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
      (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:CL "with-text-style") " must be implemented by expanding into a call to " (:CL "invoke-with-text-style")
      ", supplying a function that executes " (:GROUP (:FONT :FACE :I) "body") " as the "
      (:GROUP (:FONT :FACE :I) "continuation") " argument to " (:CL "invoke-with-text-style") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "invoke-with-text-style")) :PARAMS ((:I "medium continuation text-style")) :KIND
       ("Generic Function"))
      (:PAR) "Binds the current text style of the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      " to correspond to the new text style, and calls the function " (:GROUP (:FONT :FACE :I) "continuation")
      " with the new text style in effect. " (:GROUP (:FONT :FACE :I) "text-style")
      " may either a text style object or a style spec (that is, a list of the a family, a face code, and a size). "
      (:GROUP (:FONT :FACE :I) "continuation") " is a function of one argument, the medium; it has dynamic extent."
      (:PAR) (:GROUP (:FONT :FACE :I) "medium")
      " can be a medium, a sheet that supports the sheet output protocol, or a stream that outputs to such a sheet. All classes that obey the medium protocol must implement a method for "
      (:CL "invoke-with-text-style") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-text-family")) :PARAMS
       ((:I "(medium family) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:SIGNATURE :NAME ((:CL "with-text-face")) :PARAMS
       ((:I "(medium face) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:SIGNATURE :NAME ((:CL "with-text-size")) :PARAMS
       ((:I "(medium size) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:PAR) "Binds the current text style of the " (:TERM "medium") " designated by "
      (:GROUP (:FONT :FACE :I) "medium")
      " to correspond to a new text style consisting of the current text style with the new family, face, or size (respectively) merged in. "
      (:GROUP (:FONT :FACE :I) "face") ", " (:GROUP (:FONT :FACE :I) "family") ", and "
      (:GROUP (:FONT :FACE :I) "size") " are as for " (:CL "make-text-style") ". " (:GROUP (:FONT :FACE :I) "body")
      " is executed with the new text style in effect." (:PAR) "The " (:GROUP (:FONT :FACE :I) "medium")
      " argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If "
      (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      "These macros are \"convenience\" forms of " (:CL "with-text-style") " that must expand into calls to "
      (:CL "invoke-with-text-style") "." (:PAR) " "))
    (:SECTION :TITLE ("11.3 " "Controlling Text Style Mappings") :KIND :SECTION :NAME (3 5 10) (:PAR)
     "Text styles are mapped to fonts using the " (:CL "text-style-mapping")
     " function, which takes a port, a character set, and a text style and returns a font object. All ports must implement methods for the following generic functions, for all classes of text style."
     (:PAR)
     "The objects used to represent a font mapping are unspecified and are likely to vary from port to port. For instance, a mapping might be some sort of font object on one type of port, or might simply be the name of a font on another."
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL) "We still need to describe what a device font is. Ditto, character sets. --- SWM")
     (:PAR)
     "Part of initializing a port is to define the mappings between text styles and font names for the port's host window system."
     (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "text-style-mapping")) :PARAMS
       ((:I "port text-style " (:GROUP (:FONT :FACE :TT) "&optional ") "character-set")) :KIND ("Generic Function"))
      (:PAR) "Returns the font mapping that will be used when rendering characters in the character set "
      (:GROUP (:FONT :FACE :I) "character-set") " in the " (:TERM "text style") " "
      (:GROUP (:FONT :FACE :I) "text-style") " on any medium on the " (:TERM "port") " "
      (:GROUP (:FONT :FACE :I) "port") ". If there is no mapping associated with "
      (:GROUP (:FONT :FACE :I) "character-set") " and " (:GROUP (:FONT :FACE :I) "text-style") " on "
      (:GROUP (:FONT :FACE :I) "port")
      ", then some other object will be returned that corresponds to the \"unmapped\" text style." (:PAR)
      (:GROUP (:FONT :FACE :I) "character-set") " defaults to the standard character set." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf text-style-mapping)")) :PARAMS
       ((:I "mapping port text-style " (:GROUP (:FONT :FACE :TT) "&optional ") "character-set")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the text style mapping for " (:GROUP (:FONT :FACE :I) "port") ", "
      (:GROUP (:FONT :FACE :I) "character-set") ", and " (:GROUP (:FONT :FACE :I) "text-style") " to "
      (:GROUP (:FONT :FACE :I) "mapping") ". " (:GROUP (:FONT :FACE :I) "port") ", "
      (:GROUP (:FONT :FACE :I) "character-set") ", and " (:GROUP (:FONT :FACE :I) "text-style") " are as for "
      (:CL "text-style-mapping") ". " (:GROUP (:FONT :FACE :I) "mapping")
      " is either a font name or a list of the form "
      (:CL "(:style "
           (:GROUP (:FONT :FACE :I) "family")
           " "
           (:GROUP (:FONT :FACE :I) "face")
           " "
           (:GROUP (:FONT :FACE :I) "size")
           ")")
      "; in the latter case, the given style is translated at runtime into the font represented by the specified style."
      (:PAR) (:GROUP (:FONT :FACE :I) "character-set") " defaults to the standard character set." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-device-font-text-style")) :PARAMS ((:I "display-device device-font-name")) :KIND
       ("Function"))
      (:PAR)
      "Returns a text style object that will be mapped directly to the specified device font when text is output to a to the display device with this style. Device font styles do not merge with any other kind of style."
      (:PAR))))
   " "
   (:SECTION :TITLE ("12 " "Graphics") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "graphics") (:PAR)
    (:SECTION :TITLE ("12.1 " "Overview of Graphics") :KIND :SECTION :NAME (7 5 10) (:PAR)
     "The CLIM graphic drawing model is an idealized model of graphical pictures. The model provides the language that application programs use to describe the intended visual appearance of textual and graphical output. Usually not all of the contents of the screen are described using the graphic drawing model. For example, menus and scroll bars might be described in higher-level terms."
     (:PAR)
     "An important aspect of the CLIM graphic drawing model is its extreme device independence. The model describes ideal graphical images and ignores limitations of actual graphics devices. One consequence of this is that the actual visual appearance of the screen can only be an approximation of the appearance specified by the model. Another consequence of this is that the model is highly portable."
     (:PAR)
     "CLIM separates output into two layers, a text/graphics layer in which one specifies the desired visual appearance independent of device resolution and characteristics, and a rendering layer in which some approximation of the desired visual appearance is created on the device. Of course application programs can inquire about the device resolution and characteristics if they wish and modify their desired visual appearance on that basis. (There is also a third layer above these two layers, the adaptive toolkit layer where one specifies the desired functionality rather than the desired visual appearance.)"
     (:PAR) (:GROUP (:FONT :FACE :B) "Major issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "There are still no functions to ask about device resolution and characteristics. What characteristics do we need to be able to get to besides the obvious ones of resolution and \"color depth\". Also, do we really need to refer to the adaptive toolkit layer here? --- SWM")
     (:PAR) "CLIM's drawing functions provide convenient ways to draw several commonly-used shapes." (:PAR)
     "The interaction between graphics and output recording will be described in Chapter "
     (:REF :NAME "output-recording") "." (:PAR) " ")
    (:SECTION :TITLE ("12.2 " "Definitions") :KIND :SECTION :NAME (7 5 10) (:PAR)
     (:SECTION :TITLE ("Drawing plane.") :KIND :PARAGRAPH (:PAR)
      "A drawing plane is an infinite two-dimensional plane on which graphical output occurs. The drawing plane contains an arrangement of colors and opacities that is modified by each graphical output operation. It is not possible to read back the contents of a drawing plane, except by examining the output-history. Normally each window has its own drawing plane."
      (:PAR))
     (:SECTION :TITLE ("Coordinates.") :KIND :PARAGRAPH (:PAR)
      "Coordinates are a pair of real numbers in implementation-defined units that identify a point in the drawing plane."
      (:PAR))
     (:SECTION :TITLE ("Sheets and Mediums.") :KIND :PARAGRAPH (:PAR)
      "In this chapter, we use a medium as a destination for output. The medium has a drawing plane, two designs called the medium's foreground and background, a transformation, a clipping region, a line style, and a text style. There are per-medium, dynamically scoped, default drawing options. Different medium classes are provided to allow programmers to draw on different sorts of devices, such as displays, printers, and virtual devices such as bitmaps."
      (:PAR)
      "Many sheets can be used for doing output, so the drawing functions can also take a sheet as the output argument. In this case, drawing function \"trampolines\" to the sheet's medium. So, while the functions defined here are specified to be called on sheets, they can also be called on sheets."
      (:PAR)
      "A stream is a special kind of sheet that implements the stream protocol; streams include additional state such as the current text cursor (which is some point in the drawing plane)."
      (:PAR)
      "By default, the \"fundamental\" coordinate system of a CLIM stream (not a general sheet or medium, whose fundamental coordinate system is not defined) is a left handed system with "
      (:MATH "x") " increasing to the right, and " (:MATH "y") " increasing downward. "
      (:MATH "(" (:RM "0") "," (:RM "0") ")") " is at the upper left corner." (:PAR) " "))
    (:SECTION :TITLE ("12.3 " "Drawing is Approximate") :KIND :SECTION :NAME (7 5 10) (:PAR)
     "Note that although the drawing plane contains an infinite number of mathematical points, and drawing can be described as an infinite number of color and opacity computations, the drawing plane cannot be viewed directly and has no material existence. It is only an abstraction. What can be viewed directly is the result of rendering portions of the drawing plane onto a medium. No infinite computations or objects of infinite size are required to implement CLIM, because the results of rendering have finite size and finite resolution."
     (:PAR)
     "A drawing plane is described as having infinitely fine spatial, color, and opacity resolution, and as allowing coordinates of unbounded positive or negative magnitude. A viewport into a drawing plane, on the other hand, views only a finite region (usually rectangular) of the drawing plane. Furthermore, a viewport has limited spatial resolution and can only produce a limited number of colors. These limitations are imposed by the display hardware on which the viewport is displayed. A viewport also has limited opacity resolution, determined by the finite arithmetic used in the drawing engine (which may be hardware or software or both)."
     (:PAR)
     "Coordinates are real numbers in implementation-defined units. Often these units equal the spatial resolution of a viewport, so that a line of thickness 1 is equivalent to the thinnest visible line. However, this equivalence is not required and should not be assumed by application programs."
     (:PAR)
     "A valid CLIM implementation can be quite restrictive in the size and resolution of its viewports. For example, the spatial resolution might be only a few dozen points per inch, the maximum size might be only a few hundred points on a side, and there could be as few as two displayable colors (usually black and white). The fully transparent and fully opaque opacity levels must always be supported, but a valid CLIM implementation might support only a few opacity levels in between (or possibly even none). A valid CLIM implementation might implement color blending and unsaturated colors by stippling, although it is preferred, when possible, for a viewport to display a uniform color as a uniform color rather than as a perceptible stipple."
     (:PAR)
     "When CLIM records the output to a sheet, there are no such limitations since CLIM just remembers the drawing operations that were performed, not the results of rendering."
     (:PAR) "CLIM provides some ways to ask what resolution limits are in effect for a medium. See Chapter "
     (:REF :NAME "drawing-options") " for their descriptions." (:PAR)
     "The application programmer uses the CLIM graphic drawing model as an interface to describe the intended visual appearance. An implementation does its best to approximate that ideal appearance in a viewport, within its limitations of spatial resolution, color resolution, number of simultaneously displayable colors, and drawing speed. This will usually require tradeoffs, for example between speed and accuracy, and each implementation must make these tradeoffs according to its own hardware/software environment and user concerns. For example, if the actual device supports a limited number of colors, the desired color may be approximated by techniques such as dithering or stippling. If the actual device cannot draw curves exactly, they may be approximated, with or without anti-aliasing. If the actual device has limited opacity resolution, color blending may be approximate. A viewport might display colors that don't appear in the drawing plane, both because of color and opacity approximation and because of anti-aliasing at the edges of drawn shapes."
     (:PAR)
     "It is likely that different implementations will produce somewhat different visual appearance when running the same application. If an application requires more detailed control, it must resort to a lower-level interface, and will become less portable as a result. These lower-level interfaces will be documented on a per-platform basis."
     (:PAR)
     "Drawing computations are always carried out \"in color\", even if the viewport is only capable of displaying black and white. In other words, the CLIM drawing model is always the fully general model, even if an implementation's color resolution is limited enough that full use of the model is not possible. Of course an application that fundamentally depends on color will not work well on a viewport that cannot display color. Other applications will degrade gracefully."
     (:PAR)
     "Whether the implementation uses raster graphics or some other display technique is invisible at this interface. CLIM does not specify the existence of pixels nor the exact details of scan conversion, which will vary from one drawing engine to the next."
     (:PAR)
     "Performance will also vary between implementations. This interface is defined in terms of simple conceptual operations, however an actual implementation may use caching, specialized object representations, and other optimizations to avoid materializing storage-intensive or computation-costly intermediate results and to take advantage of available hardware."
     (:PAR) " ")
    (:SECTION :TITLE ("12.4 " "Rendering Conventions for Geometric Shapes") :KIND :SECTION :NAME (7 5 10) (:PAR)
     "The intent of this section is to describe the conventions for how CLIM should render a shape on a display device. These conventions and the accompanying examples are meant to describe a set of goals that a CLIM implementation should try to meet. However, compliant CLIM implementations may deviate from these goals if necessary (for example, if the rendering performance on a specific platform would be unacceptably slow if these goals were met exactly and implementors feel that users would be better served by speed than by accuracy). Note that we discuss only pixel-based display devices here, which are the most common, but by no means the only, sort of display device that can be supported by CLIM."
     (:PAR)
     "When CLIM draws a geometric shape on some sort of display device, the idealized geometric shape must somehow be rendered on the display device. The geometric shapes are made up of a set of mathematical points, which have no size; the rendering of the shape is usually composed of pixels, which are roughly square. These pixels exist in \"device coordinates\", which are gotten by transforming the user-supplied coordinates by all of the user-supplied transformation, the medium transformation, and the transformation that maps from the sheet to the display device. (Note that if the last transformation is a pure translation that translates by an integer multiple of device units, then it has no effect on the rendering other than placement of the figure drawn on the display device.)"
     (:PAR)
     "Roughly speaking, a pixel is affected by drawing a shape only when it is inside the shape (we will define what we mean by \"inside\" in a moment). Since pixels are little squares and the abstract points have no size, for most shapes there will be many pixels that lie only partially inside the shape. Therefore, it is important to describe the conventions used by CLIM as to which pixels should be affected when drawing a shape, so that the proper interface to the per-platform rendering engine can be constructed. (It is worth noting that on devices that support color or grayscale, the rendering engine may attempt to draw a pixel that is partially inside the shape darker or lighter, depending on how much of it is inside the shape. This is called "
     (:CONCEPT "anti-aliasing") ".) The conventions used by CLIM is the same as the conventions used by X11:" (:PAR)
     (:UL (:LI "A pixel is a addressed by its upper-left corner." (:PAR))
      (:LI "A pixel is considered to be " (:CONCEPT "inside")
       " a shape, and hence affected by the rendering of that shape, if the center of the pixel is inside the shape. If the center of the pixel lies exactly on the boundary of the shape, it is considered to be inside if the inside of the shape is immediately to the right (increasing "
       (:MATH "x")
       " direction on the display device) of the center point of the pixel. If the center of the pixel lies exactly on a horizontal boundary, it is considered to be inside if the inside of the shape is immediately below (increasing "
       (:MATH "y") " direction on the display device) the center point of the pixel." (:PAR))
      (:LI
       "An unfilled shape is drawn by taking the filled shape consisting of those points that are within 1/2 the line thickness from the outline curve (using a normal distance function, that is, the length of the line drawn at right angles to the tangent to the outline curve at the nearest point), and applying the second rule, above. "))
     (:PAR)
     "It is important to note that these rules imply that the decision point used for insideness checking is offset from the point used for addressing the pixel by half a device unit in both the "
     (:MATH "x") " and " (:MATH "y") " directions. It is worth considering the motivations for these conventions."
     (:PAR)
     "When two shapes share a common edge, it is important that only one of the shapes own any pixel. The two triangles in Figure "
     (:REF :NAME "two-triangles")
     " illustrate this. The pixels along the diagonal belong to the lower figure. When the decision point of the pixel (its center) lies to one side of the line or the other, there is no issue. When the boundary passes through a decision point, which side the inside of the figure is on is used to decide. These are the triangles that CLIM implementations should attempt to draw in this case."
     (:PAR)
     (:FIGURE :NUMBER "12.1" :CAPTION
      ((:LABEL :NAME "two-triangles") " Pixel assignment with boundary on decision points.") " "
      (:CENTER (:IMG :SRC "two-triangles.png")) "  ")
     (:PAR)
     "The reason for choosing the decision point half a pixel offset from the address point is to reduce the number of common figures (such as rectilinear lines and rectangles with integral coordinates) that invoke the boundary condition rule. This usually leads to more symmetrical results. For instance, in Figure "
     (:REF :NAME "corner-circle")
     ", we see a circle drawn when the decision point is the same as the address point. The four lighter points are indeterminate: it is not clear whether they are inside or outside the shape. Since we want to have each boundary case determined according to which side has the figure on it, and since we must apply the same rule uniformly for all figures, we have no choice but to pick only two of the four points, leading to an undesirable lopsided figure."
     (:PAR)
     (:FIGURE :NUMBER "12.2" :CAPTION
      ((:LABEL :NAME "corner-circle") " Choosing any two of the shaded pixels causes asymmetry.") " "
      (:CENTER (:IMG :SRC "corner-circle.png")) "  ")
     (:PAR)
     "If we had instead chosen to take all four boundary points, we would have a nice symmetrical figure. However, since this figure is symmetrical about a whole pixel, it is one pixel wider than it ought to be. The problem with this can be seen clearly in Figure "
     (:REF :NAME "inscribed-circle") " if we attempt to draw a rectangle and circle overlaid with the following code:"
     (:PAR)
     (:PRE "
(defun draw-test (medium radius)
  (draw-circle* medium 0 0 radius :ink +foreground-ink+)
  (draw-rectangle* medium (- radius) (- radius) (+ radius) (+ radius)
                   :ink +flipping-ink+))
")
     (:PAR)
     (:FIGURE :NUMBER "12.3" :CAPTION
      ((:LABEL :NAME "inscribed-circle") " Two forms of a circle inscribed in a rectangle.") " "
      (:CENTER (:IMG :SRC "inscribed-circle.png")) "  ")
     (:PAR)
     "It is for this reason that we choose to have the decision point at the center of the pixel. This draws circles that look like the one in Figure "
     (:REF :NAME "correct-circle") ". It is this shape that CLIM implementations should attempt to draw." (:PAR)
     (:FIGURE :NUMBER "12.4" :CAPTION ((:LABEL :NAME "correct-circle") " An aesthetically pleasing circle.") " "
      (:CENTER (:IMG :SRC "correct-circle.png")) "  ")
     (:PAR)
     "A consequence of these rendering conventions is that, when the start or end coordinate (minus 1/2 the line thickness, if the shape is a path) is not an integer, then rendering is not symmetric under reflection transformations. Thus to correctly and portably draw an outline of thickness 1 around a (rectilinear) rectangular area with integral coordinates, the outline path must have half-integral coordinates. Drawing rectilinear areas whose boundaries are not on pixel boundaries cannot be guaranteed to be portable. Another way to say the same thing is that the \"control points\" for a rectangular area are at the corners, while the control points for a rectilinear path are in the center of the path, not at the corners. Therefore, in order for a path and an area to abut seamlessly, the coordinates of the path must be offset from the coordinates of the area by half the path's thickness."
     (:PAR)
     (:SECTION :TITLE ("12.4.1 " "Permissible Alternatives During Rendering") :KIND :SUBSECTION :NAME (1 7 5 10) (:PAR)
      "Some platforms may distinguish between lines of the minimum thinness from lines that are thicker than that. The two rasterizations depicted in Figure "
      (:REF :NAME "thin-lines")
      " are both perfectly reasonable rasterizations of tilted lines that are a single device unit wide. The right-hand line is drawn as a tilted rectangle, the left as the \"thinnest visible\" line."
      (:PAR)
      (:FIGURE :NUMBER "12.5" :CAPTION ((:LABEL :NAME "thin-lines") " Two examples of lines of thickness 1.") " "
       (:CENTER (:IMG :SRC "thin-lines.png")) "  ")
      (:PAR)
      "For thick lines, a platform may choose to draw the exact tilted fractional rectangle, or the coordinates of that rectangle might be rounded so that it is distorted into another polygonal shape. The latter case may be prove to be faster on some platforms. The two rasterizations depicted in Figure "
      (:REF :NAME "thick-lines") " are both reasonable." (:PAR)
      (:FIGURE :NUMBER "12.6" :CAPTION ((:LABEL :NAME "thick-lines") " Two examples of lines of thickness 2.") " "
       (:CENTER (:IMG :SRC "thick-lines.png")) "  ")
      (:PAR)
      "The decision about which side of the shape to take when a boundary line passes through the decision point is made arbitrarily, although we have chosen to be compatible with the X11 definition. This is not necessarily the most convenient decision. The main problem with this is illustrated by the case of a horizontal line (see Figure "
      (:REF :NAME "horizontal-lines")
      "). Our definition chooses to draw the rectangular slice above the coordinates, since those pixels are the ones whose centers have the figure immediately above them. This definition makes it simpler to draw rectilinear borders around rectilinear areas."
      (:PAR)
      (:FIGURE :NUMBER "12.7" :CAPTION
       ((:LABEL :NAME "horizontal-lines")
        " Two possible definitions of horizontal lines. Left figure is X11 definition.")
       " " (:CENTER (:IMG :SRC "horizontal-lines.png")) "  ")
      (:PAR) " "))
    (:SECTION :TITLE ("12.5 " "Drawing Functions" (:LABEL :NAME "drawing-functions")) :KIND :SECTION :NAME (7 5 10)
     (:PAR) "     " (:PAR)
     "Each drawing function takes keyword arguments allowing any drawing option or suboption to be supplied separately in the call to the function. In some implementations of CLIM, the drawing functions may ignore drawing options that are irrelevant to that function; in other implementations, an error may be signalled. See Chapter "
     (:REF :NAME "drawing-options")
     " for a more complete discussion of the drawing options. An error will be signalled if any drawing function is called on a sheet that is mute for output."
     (:PAR)
     "While the functions in this section are specified to be called on mediums, they can also be called on sheets and streams. CLIM implementations will typically implement the method on a medium, and write a \"trampoline\" on the various sheet and stream classes that trampolines to the medium."
     (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
     " The drawing functions are all specified as ordinary functions, not as generic functions. This is intended to ease the task of writing compile-time optimizations that avoid keyword argument taking, check for such things as constant drawing options, and so forth. If you need to specialize any of the drawing methods, use "
     (:CL "define-graphics-method") "." (:PAR)
     "Each drawing function comes in two forms, a \"structured\" version and a \"spread\" version. The structured version passes points, whereas the spread version passes coordinates. See Section "
     (:REF :NAME "spread-vs-point") " for more information on this." (:PAR) "Any drawing functions may create an "
     (:TERM "output record") " that corresponds to the figure being drawn. See Chapter " (:REF :NAME "extended-output")
     " for a complete discussion of output recording. During output recording, none of these functions capture any arguments that are points, point sequences, coordinate sequences, or text strings. Line styles, text styles, transformations, and clipping regions may be captured."
     (:PAR)
     "Note that the CLIM specification does not specify more complex shapes such as cubic splines and Bézier curves. These are suitable candidates for extensions to CLIM."
     (:PAR) " "
     (:SECTION :TITLE ("12.5.1 " "Basic Drawing Functions") :KIND :SUBSECTION :NAME (2 7 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-point")) :PARAMS
        ((:I "medium point " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-point*")) :PARAMS
        ((:I "medium x y " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit"))
        :KIND ("Function"))
       (:PAR) "These functions (structured and spread arguments, respectively) draw a single point on the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " at the " (:TERM "point") " "
       (:GROUP (:FONT :FACE :I) "point") " (or the position " (:MATH "(x,y)") ")." (:PAR)
       "The unit and thickness components of the current line style (see Chapter " (:REF :NAME "drawing-options")
       ") affect the drawing of the point by controlling the size on the display device of the \"blob\" that is used to render the point."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-points")) :PARAMS
        ((:I "medium points " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-points*")) :PARAMS
        ((:I "medium position-seq " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit"))
        :KIND ("Function"))
       (:PAR) "These functions (structured and spread arguments, respectively) draw a set of points on the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". " (:GROUP (:FONT :FACE :I) "points")
       " is a sequence of point objects; " (:GROUP (:FONT :FACE :I) "position-seq")
       " is a sequence of coordinate pairs, which are real numbers. It is an error if "
       (:GROUP (:FONT :FACE :I) "position-seq") " does not contain an even number of elements." (:PAR)
       "Ignoring the drawing options, these functions exist as equivalents to "
       (:PRE "
(map nil #`(lambda (point) (draw-point medium point)) points)
")
       " and "
       (:PRE "
(do ((i 0 (+ i 2)))
    ((= i (length position-seq)))
  (draw-point* medium (elt position-seq i) (elt position-seq (+ i 1))))
")
       " for convenience and efficiency." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-line")) :PARAMS
        ((:I "medium point1 point2 " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-line*")) :PARAMS
        ((:I "medium x1 y1 x2 y2 " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:PAR) "These functions (structured and spread arguments, respectively) draw a line segment on the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " from the " (:TERM "point") " "
       (:GROUP (:FONT :FACE :I) "point1") " to " (:GROUP (:FONT :FACE :I) "point2") " (or from the position ("
       (:GROUP (:FONT :FACE :I) "x1") "," (:GROUP (:FONT :FACE :I) "y1") ") to (" (:GROUP (:FONT :FACE :I) "x2") ","
       (:GROUP (:FONT :FACE :I) "y2") "))." (:PAR) "The current line style (see Chapter "
       (:REF :NAME "drawing-options")
       ") affects the drawing of the line in the obvious way, except that the joint shape has no effect. Dashed lines start dashing at "
       (:GROUP (:FONT :FACE :I) "point1") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-lines")) :PARAMS
        ((:I "medium points " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-lines*")) :PARAMS
        ((:I "medium position-seq " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:PAR)
       "These functions (structured and spread arguments, respectively) draw a set of disconnected line segments. "
       (:GROUP (:FONT :FACE :I) "points") " is a sequence of point objects; " (:GROUP (:FONT :FACE :I) "position-seq")
       " is a sequence of coordinate pairs. It is an error if " (:GROUP (:FONT :FACE :I) "position-seq")
       " does not contain an even number of elements." (:PAR)
       "Ignoring the drawing options, these functions are equivalent to "
       (:PRE "
(do ((i 0 (+ i 2)))
    ((= i (length points)))
  (draw-line medium (elt points i) (elt points (1+ i))))
")
       " and "
       (:PRE "
(do ((i 0 (+ i 4)))
    ((= i (length position-seq)))
  (draw-line* medium (elt position-seq i)       (elt position-seq (+ i 1))
                     (elt position-seq (+ i 2)) (elt position-seq (+ i 3))))
")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-polygon")) :PARAMS
        ((:I "medium point-seq " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t") ") (closed " (:CL "t")
          ")  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape line-cap-shape"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-polygon*")) :PARAMS
        ((:I "medium coord-seq " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t") ") (closed " (:CL "t")
          ")  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape line-cap-shape"))
        :KIND ("Function"))
       (:PAR) "Draws a polygon or polyline on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". When "
       (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "false")
       ", this draws a set of connected lines, otherwise it draws a filled polygon. If "
       (:GROUP (:FONT :FACE :I) "closed") " is " (:TERM "true") " (the default) and "
       (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "false")
       ", it ensures that a segment is drawn that connects the ending point of the last segment to the starting point of the first segment. The current line style (see Chapter "
       (:REF :NAME "drawing-options")
       ") affects the drawing of unfilled polygons in the obvious way. The cap shape affects only the \"open\" vertices in the case when "
       (:GROUP (:FONT :FACE :I) "closed") " is " (:TERM "false")
       ". Dashed lines start dashing at the starting point of the first segment, and may or may not continue dashing across vertices, depending on the window system."
       (:PAR) (:GROUP (:FONT :FACE :I) "point-seq") " is a sequence of point objects; "
       (:GROUP (:FONT :FACE :I) "coord-seq") " is a sequence of coordinate pairs. It is an error if "
       (:GROUP (:FONT :FACE :I) "coord-seq") " does not contain an even number of elements." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "true")
       ", a closed polygon is drawn and filled in. In this case, " (:GROUP (:FONT :FACE :I) "closed")
       " is assumed to be " (:TERM "true") " as well." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-rectangle")) :PARAMS
        ((:I "medium point1 point2 " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t")
          ")  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape"))
        :KIND ("Function")))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-rectangle*")) :PARAMS
        ((:I "medium x1 y1 x2 y2 " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t")
          ")  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape"))
        :KIND ("Function"))
       (:PAR) "Draws either a filled or unfilled rectangle on the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium")
       " that has its sides aligned with the coordinate axes of the native coordinate system. One corner of the rectangle is at the position ("
       (:GROUP (:FONT :FACE :I) "x1") "," (:GROUP (:FONT :FACE :I) "y1") ") and the opposite corner is at ("
       (:GROUP (:FONT :FACE :I) "x2") "," (:GROUP (:FONT :FACE :I) "y2") "). The arguments "
       (:GROUP (:FONT :FACE :I) "x1") ", " (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and "
       (:GROUP (:FONT :FACE :I) "y1") " are real numbers that are canonicalized in the same way as for "
       (:CL "make-bounding-rectangle") ". " (:GROUP (:FONT :FACE :I) "filled") " is as for " (:CL "draw-polygon*") "."
       (:PAR) "The current line style (see Chapter " (:REF :NAME "drawing-options")
       ") affects the drawing of unfilled rectangles in the obvious way, except that the cap shape has no effect."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-rectangles")) :PARAMS
        ((:I "medium points " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-rectangles*")) :PARAMS
        ((:I "medium position-seq " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape"))
        :KIND ("Function"))
       (:PAR) "These functions (structured and spread arguments, respectively) draw a set of rectangles. "
       (:GROUP (:FONT :FACE :I) "points") " is a sequence of point objects; " (:GROUP (:FONT :FACE :I) "position-seq")
       " is a sequence of coordinate pairs. It is an error if " (:GROUP (:FONT :FACE :I) "position-seq")
       " does not contain an even number of elements." (:PAR)
       "Ignoring the drawing options, these functions are equivalent to "
       (:PRE "
(do ((i 0 (+ i 2)))
    ((= i (length points)))
  (draw-rectangle medium (elt points i) (elt points (1+ i))))
")
       " and "
       (:PRE "
(do ((i 0 (+ i 4)))
    ((= i (length position-seq)))
  (draw-rectangle* medium (elt position-seq i)       (elt position-seq (+ i 1))
                          (elt position-seq (+ i 2)) (elt position-seq (+ i 3))))
")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-ellipse")) :PARAMS
        ((:I "medium center-pt radius-1-dx radius-1-dy radius-2-dx radius-2-dy  " (:GROUP (:FONT :FACE :TT) "&key ")
          "(filled " (:CL "t")
          ") start-angle end-angle  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-ellipse*")) :PARAMS
        ((:I "medium center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy  "
          (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t")
          ") start-angle end-angle  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:PAR) "These functions (structured and spread arguments, respectively) draw an ellipse (when "
       (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "true") ", the default) or an elliptical arc (when "
       (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "false") ") on the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium") ". The center of the ellipse is the " (:TERM "point") " "
       (:GROUP (:FONT :FACE :I) "center-pt") " (or the position (" (:GROUP (:FONT :FACE :I) "center-x") ","
       (:GROUP (:FONT :FACE :I) "center-y") "))." (:PAR) "Two vectors, (" (:GROUP (:FONT :FACE :I) "radius-1-dx") ","
       (:GROUP (:FONT :FACE :I) "radius-1-dy") ") and (" (:GROUP (:FONT :FACE :I) "radius-2-dx") ","
       (:GROUP (:FONT :FACE :I) "radius-2-dy")
       ") specify the bounding parallelogram of the ellipse as explained in Chapter " (:REF :NAME "regions")
       ". All of the radii are real numbers. If the two vectors are collinear, the ellipse is not well-defined and the "
       (:CL "ellipse-not-well-defined")
       " error will be signalled. The special case of an ellipse with its major axes aligned with the coordinate axes can be obtained by setting both "
       (:GROUP (:FONT :FACE :I) "radius-1-dy") " and " (:GROUP (:FONT :FACE :I) "radius-2-dx") " to 0." (:PAR)
       (:GROUP (:FONT :FACE :I) "start-angle") " and " (:GROUP (:FONT :FACE :I) "end-angle")
       " are real numbers that specify an arc rather than a complete ellipse. Angles are measured with respect to the positive "
       (:MATH "x") " axis. The elliptical arc runs positively (counter-clockwise) from "
       (:GROUP (:FONT :FACE :I) "start-angle") " to " (:GROUP (:FONT :FACE :I) "end-angle") ". The default for "
       (:GROUP (:FONT :FACE :I) "start-angle") " is " (:MATH (:RM "0")) "; the default for "
       (:GROUP (:FONT :FACE :I) "end-angle") " is " (:MATH (:RM "2") (:ENTITY :NAME "pi")) "." (:PAR)
       "In the case of a \"filled arc\" (that is when " (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "true")
       " and " (:GROUP (:FONT :FACE :I) "start-angle") " or " (:GROUP (:FONT :FACE :I) "end-angle")
       " are supplied and are not " (:MATH (:RM "0")) " and " (:MATH (:RM "2") (:ENTITY :NAME "pi"))
       "), the figure drawn is the \"pie slice\" area swept out by a line from the center of the ellipse to a point on the boundary as the boundary point moves from "
       (:GROUP (:FONT :FACE :I) "start-angle") " to " (:GROUP (:FONT :FACE :I) "end-angle") "." (:PAR)
       "When drawing unfilled ellipses, the current line style (see Chapter " (:REF :NAME "drawing-options")
       ") affects the drawing in the obvious way, except that the joint shape has no effect. Dashed elliptical arcs start \"dashing\" at "
       (:GROUP (:FONT :FACE :I) "start-angle") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-circle")) :PARAMS
        ((:I "medium center-pt radius " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t")
          ") start-angle end-angle  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-circle*")) :PARAMS
        ((:I "medium center-x center-y radius " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t")
          ") start-angle end-angle  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:PAR) "These functions (structured and spread arguments, respectively) draw a circle (when "
       (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "true") ", the default) or a circular arc (when "
       (:GROUP (:FONT :FACE :I) "filled") " is " (:TERM "false") ") on the " (:TERM "medium") " "
       (:GROUP (:FONT :FACE :I) "medium") ". The center of the circle is " (:GROUP (:FONT :FACE :I) "center-pt")
       " or (" (:GROUP (:FONT :FACE :I) "center-x") "," (:GROUP (:FONT :FACE :I) "center-y") ") and the radius is "
       (:GROUP (:FONT :FACE :I) "radius") ". These are just special cases of " (:CL "draw-ellipse") " and "
       (:CL "draw-ellipse*") ". " (:GROUP (:FONT :FACE :I) "filled") " is as for " (:CL "draw-ellipse*") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "start-angle") " and " (:GROUP (:FONT :FACE :I) "end-angle")
       " allow the specification of an arc rather than a complete circle in the same manner as that of the ellipse functions, above."
       (:PAR) "The \"filled arc\" behavior is the same as that of an ellipse, above." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-text")) :PARAMS
        ((:I "medium string-or-char point  " (:GROUP (:FONT :FACE :TT) "&key ") "text-style (start " (:CL "0")
          ") end  (align-x " (:CL ":left") ") (align-y " (:CL ":baseline")
          ")  toward-point transform-glyphs  ink clipping-region transformation text-style text-family text-face text-size"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-text*")) :PARAMS
        ((:I "medium string-or-char x y  " (:GROUP (:FONT :FACE :TT) "&key ") "text-style (start " (:CL "0")
          ") end  (align-x " (:CL ":left") ") (align-y " (:CL ":baseline")
          ")  toward-x toward-y transform-glyphs  ink clipping-region transformation text-style text-family text-face text-size"))
        :KIND ("Function"))
       (:PAR) "The text specified by " (:GROUP (:FONT :FACE :I) "string-or-char") " is drawn on the " (:TERM "medium")
       " " (:GROUP (:FONT :FACE :I) "medium") " starting at the position specified by the " (:TERM "point") " "
       (:GROUP (:FONT :FACE :I) "point") " (or the position " (:MATH "(x,y)")
       "). The exact definition of \"starting at\" is dependent on " (:GROUP (:FONT :FACE :I) "align-x") " and "
       (:GROUP (:FONT :FACE :I) "align-y") ". " (:GROUP (:FONT :FACE :I) "align-x") " is one of " (:CL ":left") ", "
       (:CL ":center") ", or " (:CL ":right") ". " (:GROUP (:FONT :FACE :I) "align-y") " is one of " (:CL ":baseline")
       ", " (:CL ":top") ", " (:CL ":center") ", or " (:CL ":bottom") ". " (:GROUP (:FONT :FACE :I) "align-x")
       " defaults to " (:CL ":left") " and " (:GROUP (:FONT :FACE :I) "align-y") " defaults to " (:CL ":baseline")
       "; with these defaults, the first glyph is drawn with its left edge and its baseline at "
       (:GROUP (:FONT :FACE :I) "point") "." (:PAR) (:GROUP (:FONT :FACE :I) "text-style") " defaults to " (:CL "nil")
       ", meaning that the text will be drawn using the current text style of the medium." (:PAR)
       (:GROUP (:FONT :FACE :I) "start") " and " (:GROUP (:FONT :FACE :I) "end")
       " specify the start and end of the string, in the case where " (:GROUP (:FONT :FACE :I) "string-or-char")
       " is a string. If " (:GROUP (:FONT :FACE :I) "start")
       " is supplied, it must be an integer that is less than the length of the string. If "
       (:GROUP (:FONT :FACE :I) "end")
       " is supplied, it must be an integer that is less than the length of the string, but greater than or equal to "
       (:GROUP (:FONT :FACE :I) "start") "." (:PAR)
       "Normally, glyphs are drawn from left to right no matter what transformation is in effect. "
       (:GROUP (:FONT :FACE :I) "toward-x") " or " (:GROUP (:FONT :FACE :I) "toward-y") " (derived from "
       (:GROUP (:FONT :FACE :I) "toward-point") " in the case of " (:CL "draw-text")
       ") can be used to change the direction from one glyph to the next one. For example, if "
       (:GROUP (:FONT :FACE :I) "toward-x") " is less than the " (:MATH "x") " position of "
       (:GROUP (:FONT :FACE :I) "point") ", then the glyphs will be drawn from right to left. If "
       (:GROUP (:FONT :FACE :I) "toward-y") " is greater than the " (:MATH "y") " position of "
       (:GROUP (:FONT :FACE :I) "point")
       ", then the glyphs' baselines will be positioned one above another. More precisely, the reference point in each glyph lies on a line from "
       (:GROUP (:FONT :FACE :I) "point") " to " (:GROUP (:FONT :FACE :I) "toward-point")
       ", and the spacing of each glyph is determined by packing rectangles along that line, where each rectangle is \"char-width\" wide and \"char-height\" high."
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "transform-glyphs") " is " (:TERM "true")
       ", then each glyph is transformed as an image before it is drawn. That is, if a rotation transformation is in effect, then each glyph will be rotated individually. If "
       (:GROUP (:FONT :FACE :I) "transform-glyphs")
       " is not supplied, then the individual glyphs are not subject to the current transformation. It is permissible for CLIM implementations to ignore "
       (:GROUP (:FONT :FACE :I) "transform-glyphs") " if it is too expensive to implement." (:PAR) " "))
     (:SECTION :TITLE ("12.5.2 " "Compound Drawing Functions") :KIND :SUBSECTION :NAME (2 7 5 10) (:PAR)
      "CLIM also provides a few compound drawing functions. The compound drawing functions could be composed by a programmer from the basic drawing functions, but are provided by CLIM because they are commonly used."
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-arrow")) :PARAMS
        ((:I "medium point-1 point-2 " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape  to-head from-head head-length head-width"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-arrow*")) :PARAMS
        ((:I "medium x1 y1 x2 y2 " (:GROUP (:FONT :FACE :TT) "&key ")
          "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape  from-head to-head head-length head-width"))
        :KIND ("Function"))
       (:PAR) "These functions (structured and spread arguments, respectively) draw a line segment on the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") " from the " (:TERM "point") " "
       (:GROUP (:FONT :FACE :I) "point1") " to " (:GROUP (:FONT :FACE :I) "point2") " (or from the position ("
       (:GROUP (:FONT :FACE :I) "x1") "," (:GROUP (:FONT :FACE :I) "y1") ") to (" (:GROUP (:FONT :FACE :I) "x2") ","
       (:GROUP (:FONT :FACE :I) "y2") ")). If " (:GROUP (:FONT :FACE :I) "to-head") " is " (:TERM "true")
       " (the default), then the \"to\" end of the line is capped by an arrowhead. If "
       (:GROUP (:FONT :FACE :I) "from-head") " is " (:TERM "true") " (the default is " (:TERM "false")
       "), then the \"from\" end of the line is capped by an arrowhead. The arrowhead has length "
       (:GROUP (:FONT :FACE :I) "head-length") " (default 10) and width " (:GROUP (:FONT :FACE :I) "head-width")
       " (default 5)." (:PAR) "The current line style (see Chapter " (:REF :NAME "drawing-options")
       ") affects the drawing of the line portion of the arrow in the obvious way, except that the joint shape has no effect. Dashed arrows start dashing at "
       (:GROUP (:FONT :FACE :I) "point1") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "draw-oval")) :PARAMS
        ((:I "medium center-pt x-radius y-radius " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t")
          ")  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:SIGNATURE :NAME ((:CL "draw-oval*")) :PARAMS
        ((:I "medium center-x center-y x-radius y-radius " (:GROUP (:FONT :FACE :TT) "&key ") "(filled " (:CL "t")
          ")  ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape"))
        :KIND ("Function"))
       (:PAR)
       "These functions (structured and spread arguments, respectively) draw a filled or unfilled oval (that is, a \"race-track\" shape) on the "
       (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". The oval is centered on "
       (:GROUP (:FONT :FACE :I) "center-pt") " (or (" (:GROUP (:FONT :FACE :I) "center-x") ","
       (:GROUP (:FONT :FACE :I) "center-y") ")). If " (:GROUP (:FONT :FACE :I) "x-radius") " or "
       (:GROUP (:FONT :FACE :I) "y-radius") " is " (:MATH (:RM "0"))
       ", then a circle is drawn with the specified non-zero radius. Other, a figure is drawn that results from drawing a rectangle with dimension "
       (:GROUP "x-radius") " by " (:GROUP (:FONT :FACE :I) "y-radius")
       ", and the replacing the two short sides with a semicircular arc of the appropriate size." (:PAR) " ")))
    (:SECTION :TITLE ("12.6 " "Pixmaps") :KIND :SECTION :NAME (7 5 10) (:PAR) "A " (:CONCEPT "pixmap")
     " can be thought of as an \"off-screen window\", that is, a medium that can be used for graphical output, but is not visible on any display device. Pixmaps are provided to allow a programmer to generate a piece of output associated with some display device that can then be rapidly drawn on a real display device. For example, an electrical CAD system might generate a pixmap that corresponds to a complex, frequently used part in a VLSI schematic, and then use "
     (:CL "copy-from-pixmap") " to draw the part as needed." (:PAR)
     "The exact representation of a pixmap is explicitly unspecified. There is no interaction between the pixmap operations and output recording, that is, displaying a pixmap on a sheet or medium is a pure drawing operation that affects only the display, not the output history. Some mediums may not support pixmaps; in this case, an error will be signalled."
     (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "allocate-pixmap")) :PARAMS ((:I "medium width height")) :KIND ("Generic Function"))
      (:PAR)
      "Allocates and returns a pixmap object that can be used on any medium that shares the same characteristics as "
      (:GROUP (:FONT :FACE :I) "medium")
      ". (The exact definition of \"shared characteristics\" will vary from host to host.) "
      (:GROUP (:FONT :FACE :I) "medium") " can be a medium, a sheet, or a stream." (:PAR)
      "The resulting pixmap will be at least " (:GROUP (:FONT :FACE :I) "width") " units wide, "
      (:GROUP (:FONT :FACE :I) "height")
      " units high, and as deep as is necessary to store the information for the medium. The exact representation of pixmaps is explicitly unspecified."
      (:PAR) "The returned value is the pixmap." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "deallocate-pixmap")) :PARAMS ((:I "pixmap")) :KIND ("Generic Function")) (:PAR)
      "Deallocates the pixmap " (:GROUP (:FONT :FACE :I) "pixmap") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "pixmap-width")) :PARAMS ((:I "pixmap")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "pixmap-height")) :PARAMS ((:I "pixmap")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "pixmap-depth")) :PARAMS ((:I "pixmap")) :KIND ("Generic Function")) (:PAR)
      "These functions return, respectively, the width, height, and depth of the pixmap "
      (:GROUP (:FONT :FACE :I) "pixmap")
      ". These values may be different from the programmer-specified values, since some window systems need to allocate pixmaps only of particular sizes."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "copy-to-pixmap")) :PARAMS
       ((:I "medium medium-x medium-y width height  " (:GROUP (:FONT :FACE :TT) "&optional ") "pixmap (pixmap-x "
         (:CL "0") ") (pixmap-y " (:CL "0") ")"))
       :KIND ("Function"))
      (:PAR) "Copies the pixels from the medium " (:GROUP (:FONT :FACE :I) "medium")
      " starting at the position specified by (" (:GROUP (:FONT :FACE :I) "medium-x") ","
      (:GROUP (:FONT :FACE :I) "medium-y") ") into the pixmap " (:GROUP (:FONT :FACE :I) "pixmap")
      " at the position specified by (" (:GROUP (:FONT :FACE :I) "pixmap-x") "," (:GROUP (:FONT :FACE :I) "pixmap-y")
      "). A rectangle whose width and height is specified by " (:GROUP (:FONT :FACE :I) "width") " and "
      (:GROUP (:FONT :FACE :I) "height") " is copied. " (:GROUP (:FONT :FACE :I) "medium-x") " and "
      (:GROUP (:FONT :FACE :I) "medium-y") " are specified in user coordinates. (If "
      (:GROUP (:FONT :FACE :I) "medium") " is a medium or a stream, then " (:GROUP (:FONT :FACE :I) "medium-x") " and "
      (:GROUP (:FONT :FACE :I) "medium-y") " are transformed by the user transformation.) The copying must be done by "
      (:CL "medium-copy-copy") "." (:PAR) "If " (:GROUP (:FONT :FACE :I) "pixmap")
      " is not supplied, a new pixmap will be allocated. Otherwise, " (:GROUP (:FONT :FACE :I) "pixmap")
      " must be an object returned by " (:CL "allocate-pixmap") " that has the appropriate characteristics for "
      (:GROUP (:FONT :FACE :I) "medium") "." (:PAR) "The returned value is the pixmap." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "copy-from-pixmap")) :PARAMS
       ((:I "pixmap pixmap-x pixmap-y width height  medium medium-x medium-y")) :KIND ("Function"))
      (:PAR) "Copies the pixels from the pixmap " (:GROUP (:FONT :FACE :I) "pixmap")
      " starting at the position specified by (" (:GROUP (:FONT :FACE :I) "pixmap-x") ","
      (:GROUP (:FONT :FACE :I) "pixmap-y") ") into the medium " (:GROUP (:FONT :FACE :I) "medium") " at the position ("
      (:GROUP (:FONT :FACE :I) "medium-x") "," (:GROUP (:FONT :FACE :I) "medium-y")
      "). A rectangle whose width and height is specified by " (:GROUP (:FONT :FACE :I) "width") " and "
      (:GROUP (:FONT :FACE :I) "height") " is copied. " (:GROUP (:FONT :FACE :I) "medium-x") " and "
      (:GROUP (:FONT :FACE :I) "medium-y") " are specified in user coordinates. (If "
      (:GROUP (:FONT :FACE :I) "medium") " is a medium or a stream, then " (:GROUP (:FONT :FACE :I) "medium-x") " and "
      (:GROUP (:FONT :FACE :I) "medium-y") " are transformed by the user transformation.) The copying must be done by "
      (:CL "medium-copy-copy") "." (:PAR) (:GROUP (:FONT :FACE :I) "pixmap") " must be an object returned by "
      (:CL "allocate-pixmap") " that has the appropriate characteristics for " (:GROUP (:FONT :FACE :I) "medium") "."
      (:PAR) "The returned value is the pixmap." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "copy-area")) :PARAMS ((:I "medium from-x from-y width height to-x to-y")) :KIND
       ("Generic Function"))
      (:PAR) "Copies the pixels from the medium " (:GROUP (:FONT :FACE :I) "medium")
      " starting at the position specified by (" (:GROUP (:FONT :FACE :I) "from-x") ","
      (:GROUP (:FONT :FACE :I) "from-y") ") to the position (" (:GROUP (:FONT :FACE :I) "to-x") ","
      (:GROUP (:FONT :FACE :I) "to-y") ") on the same medium. A rectangle whose width and height is specified by "
      (:GROUP (:FONT :FACE :I) "width") " and " (:GROUP (:FONT :FACE :I) "height") " is copied. "
      (:GROUP (:FONT :FACE :I) "from-x") ", " (:GROUP (:FONT :FACE :I) "from-y") ", " (:GROUP (:FONT :FACE :I) "to-x")
      ", and " (:GROUP (:FONT :FACE :I) "to-y") " are specified in user coordinates. (If "
      (:GROUP (:FONT :FACE :I) "medium") " is a medium or a stream, then the " (:MATH "x") " and " (:MATH "y")
      " values are transformed by the user transformation.) The copying must be done by " (:CL "medium-copy-copy") "."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "medium-copy-area")) :PARAMS
       ((:I "from-drawable from-x from-y width height  to-drawable to-x to-y")) :KIND ("Generic Function"))
      (:PAR) "Copies the pixels from the source drawable " (:GROUP (:FONT :FACE :I) "from-drawable")
      " at the position (" (:GROUP (:FONT :FACE :I) "from-x") "," (:GROUP (:FONT :FACE :I) "from-y")
      ") to the destination drawable " (:GROUP (:FONT :FACE :I) "to-drawable") " at the position ("
      (:GROUP (:FONT :FACE :I) "to-x") "," (:GROUP (:FONT :FACE :I) "to-y")
      "). A rectangle whose width and height is specified by " (:GROUP (:FONT :FACE :I) "width") " and "
      (:GROUP (:FONT :FACE :I) "height") " is copied. " (:GROUP (:FONT :FACE :I) "from-x") ", "
      (:GROUP (:FONT :FACE :I) "from-y") ", " (:GROUP (:FONT :FACE :I) "to-x") ", and "
      (:GROUP (:FONT :FACE :I) "to-y") " are specified in user coordinates. The " (:MATH "x") " and " (:MATH "y")
      " are transformed by the user transformation." (:PAR) "This is intended to specialize on both the "
      (:GROUP (:FONT :FACE :I) "from-drawable") " and " (:GROUP (:FONT :FACE :I) "to-drawable") " arguments. "
      (:GROUP (:FONT :FACE :I) "from-drawable") " and " (:GROUP (:FONT :FACE :I) "to-drawable")
      " may be either mediums or pixmaps." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-output-to-pixmap")) :PARAMS
       ((:I "(medium-var medium " (:GROUP (:FONT :FACE :TT) "&key ") "width height) "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Binds " (:GROUP (:FONT :FACE :I) "medium-var")
      " to a \"pixmap medium\", that is, a medium that does output to a pixmap with the characteristics appropriate to the medium "
      (:GROUP (:FONT :FACE :I) "medium") ", and then evaluates " (:GROUP (:FONT :FACE :I) "body")
      " in that context. All the output done to the medium designated by " (:GROUP (:FONT :FACE :I) "medium-var")
      " inside of " (:GROUP (:FONT :FACE :I) "body")
      " is drawn on the pixmap stream. The pixmap medium must support the medium output protocol, including all of the graphics function. CLIM implementations are permitted, but not required, to have pixmap mediums support the stream output protocol ("
      (:CL "write-char") " and " (:CL "write-string") ")." (:PAR) (:GROUP (:FONT :FACE :I) "width") " and "
      (:GROUP (:FONT :FACE :I) "height")
      " are integers that give the width and height of the pixmap. If they are unsupplied, the result pixmap will be large enough to contain all of the output done by "
      (:GROUP (:FONT :FACE :I) "body") "." (:PAR) (:GROUP (:FONT :FACE :I) "medium-var")
      " must be a symbol; it is not evaluated." (:PAR) "The returned value is a pixmap that can be drawn onto "
      (:GROUP (:FONT :FACE :I) "medium") " using " (:CL "copy-from-pixmap") "." (:PAR) " "))
    (:SECTION :TITLE ("12.7 " "Graphics Protocols" (:LABEL :NAME "graphics-protocols")) :KIND :SECTION :NAME (7 5 10)
     (:PAR)
     "Every medium must implement methods for the various graphical drawing generic functions. Furthermore, every sheet that supports the standard output protocol must implement these methods as well; often, the sheet methods will trampoline to the methods on the sheet's medium. All of these generic functions take the same arguments as the non-generic spread function equivalents, except the arguments that are keyword arguments in the non-generic functions are positional arguments in the generic functions."
     (:PAR)
     "Every medium must implement methods for the various graphical drawing generic functions. All of these generic functions take as (specialized) arguments the medium, followed by the drawing function-specific arguments, followed by the ink, line style (or text style), and clipping region."
     (:PAR) "The drawing function-specific arguments will either be " (:MATH "x") " and " (:MATH "y")
     " positions, or a sequence of " (:MATH "x") " and " (:MATH "y")
     " positions. These positions will be in medium coordinates, and must be transformed by applying the medium's device transformation in order to produce device coordinates. Note that the user transformation will have already been applied to the positions when the medium-specific drawing function is called. However, the medium-specific drawing function will still need to apply the device transformation to the positions in order to draw the graphics in the appopriate place on the host window."
     (:PAR)
     "The ink, line style, text style, and clipping regions arguments are not part of the medium-specific drawing functions. They must be extracted from the medium object. Each medium-specific method will decode the ink, line (or text) style, and clipping region in a port-specific way and communicate it to the underlying port."
     (:PAR) " "
     (:SECTION :TITLE ("12.7.1 " "General Behavior of Drawing Functions") :KIND :SUBSECTION :NAME (3 7 5 10) (:PAR)
      "Using " (:CL "draw-line*")
      " as an example, calling any of the drawing functions specified above results in the following series of function calls on a non-output recording sheet:"
      (:PAR)
      (:UL
       (:LI "A program calls " (:CL "draw-line*") " on either a sheet or a medium, " (:GROUP (:FONT :FACE :I) "x1")
        ", " (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and " (:GROUP (:FONT :FACE :I) "y2")
        ", and perhaps some drawing options." (:PAR))
       (:LI (:CL "draw-line*") " merges the supplied drawing options into the medium, and then calls "
        (:CL "medium-draw-line*")
        " on the sheet or medium. (Note that a compiler macro could detect the case where there are no drawing options or constant drawing options, and do this at compile time.)"
        (:PAR))
       (:LI "If " (:CL "draw-line*") " was called on a sheet, the " (:CL "medium-draw-line*")
        " on the sheet trampolines to the medium's " (:CL "medium-draw-line*") " method." (:PAR))
       (:LI "An " (:CL ":around") " method for " (:CL "medium-draw-line*")
        " performs the necessary user transformations by applying the medium transformation to "
        (:GROUP (:FONT :FACE :I) "x1") ", " (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and "
        (:GROUP (:FONT :FACE :I) "y2") ", and to the clipping region, and then calls the medium-specific method."
        (:PAR))
       (:LI "The \"real\" " (:CL "medium-draw-line*")
        " transforms the start and end coordinates of the line by the sheet's device transformation, decodes the ink and line style into port-specific objects, and finally invokes a port-specific function (such as "
        (:CL "xlib:draw-line") ") to do the actual drawing. "))
      (:PAR) " ")
     (:SECTION :TITLE ("12.7.2 " "Medium-specific Drawing Functions") :KIND :SUBSECTION :NAME (3 7 5 10) (:PAR)
      "All mediums and all sheets that support the standard output protocol must implement methods for the following generic functions."
      (:PAR)
      "The method for each of these drawing functions on the most specific, implementation-dependent medium class will transform the coordinates by the device transformation of the medium's sheet, extract the medium's port-specific \"drawable\", and then invoke a port-specific drawing function (such as "
      (:CL "xlib:draw-line") ") to do the actual drawing." (:PAR) "An " (:CL ":around") " on " (:CL "basic-medium")
      " for each of the drawing functions will have already transformed the user coordinates to medium coordinates before the most specific, implementation-dependent method is called."
      (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
      " CLIM implementations should provide \"trampoline\" methods on sheets that support the standard output protocol that simply call the same generic function on the medium. Sheets that support output recording will require extra mechanism before delegating to the medium in order to implement such functionality as creating output records and handling scrolling."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-draw-point*")) :PARAMS ((:I "medium x y")) :KIND ("Generic Function"))
       (:PAR) "Draws a point on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-points*")) :PARAMS ((:I "medium coord-seq")) :KIND ("Generic Function"))
       (:PAR) "Draws a set of points on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". "
       (:GROUP (:FONT :FACE :I) "coord-seq")
       " is a sequence of coordinate pairs, which are real numbers. It is an error if "
       (:GROUP (:FONT :FACE :I) "coord-seq") " does not contain an even number of elements." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-line*")) :PARAMS ((:I "medium x1 y1 x2 y2")) :KIND ("Generic Function"))
       (:PAR) "Draws a line on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
       ". The line is drawn from " (:MATH "(x" (:RM "1") ",y" (:RM "1") ")") " to "
       (:MATH "(x" (:RM "2") ",y" (:RM "2") ")") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-lines*")) :PARAMS ((:I "stream position-seq")) :KIND ("Generic Function"))
       (:PAR) "Draws a set of disconnected lines on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". "
       (:GROUP (:FONT :FACE :I) "coord-seq")
       " is a sequence of coordinate pairs, which are real numbers. Each successive pair of coordinate pairs is taken as the start and end position of each line. It is an error if "
       (:GROUP (:FONT :FACE :I) "coord-seq") " does not contain an even number of elements." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-polygon*")) :PARAMS ((:I "medium coord-seq closed")) :KIND
        ("Generic Function"))
       (:PAR) "Draws a polygon or polyline on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". "
       (:GROUP (:FONT :FACE :I) "coord-seq")
       " is a sequence of coordinate pairs, which are real numbers. It is an error if "
       (:GROUP (:FONT :FACE :I) "coord-seq")
       " does not contain an even number of elements. Each successive coordinate pair is taken as the position of one vertex of the polygon."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-rectangle*")) :PARAMS ((:I "medium x1 y1 x2 y2")) :KIND
        ("Generic Function"))
       (:PAR) "Draws a rectangle on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
       ". The corners of the rectangle are at " (:MATH "(x" (:RM "1") ",y" (:RM "1") ")") " and "
       (:MATH "(x" (:RM "2") ",y" (:RM "2") ")") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-rectangles*")) :PARAMS ((:I "medium coord-seq")) :KIND
        ("Generic Function"))
       (:PAR) "Draws a set of rectangles on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium") ". "
       (:GROUP (:FONT :FACE :I) "coord-seq")
       " is a sequence of coordinate pairs, which are real numbers. It is an error if "
       (:GROUP (:FONT :FACE :I) "coord-seq")
       " does not contain an even number of elements. Each successive pair of coordinate pairs is taken as the upper-left and lower-right corner of the rectangle."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-ellipse*")) :PARAMS
        ((:I "medium center-x center-y  radius-1-dx radius-1-dy radius-2-dx radius-2-dy  start-angle end-angle")) :KIND
        ("Generic Function"))
       (:PAR) " Draws an ellipse or elliptical arc on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
       ". The center of the ellipse is at " (:MATH "(x,y)") ", and the radii are specified by the two vectors ("
       (:GROUP (:FONT :FACE :I) "radius-1-dx") "," (:GROUP (:FONT :FACE :I) "radius-1-dy") ") and ("
       (:GROUP (:FONT :FACE :I) "radius-2-dx") "," (:GROUP (:FONT :FACE :I) "radius-2-dy") ")." (:PAR)
       (:GROUP (:FONT :FACE :I) "start-angle") " and " (:GROUP (:FONT :FACE :I) "end-angle")
       " are real numbers that specify an arc rather than a complete ellipse. Note that the medium and device transformations must be applied to the angles as well."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-draw-text*")) :PARAMS
        ((:I "medium text x y  (start " (:CL "0") ") end  (align-x " (:CL ":left") ") (align-y " (:CL ":baseline")
          ")  toward-x toward-y transform-glyphs"))
        :KIND ("Generic Function"))
       (:PAR) "Draws a character or a string on the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
       ". The text is drawn starting at " (:MATH "(x,y)") ", and towards (" (:GROUP (:FONT :FACE :I) "toward-x") ","
       (:GROUP (:FONT :FACE :I) "toward-y") "). In Some implementations of CLIM, " (:CL "medium-draw-text*")
       " may call either " (:CL "medium-draw-string*") " or " (:CL "medium-draw-character*")
       " in order to draw the text." (:PAR)))
     (:SECTION :TITLE ("12.7.3 " "Other Medium-specific Output Functions") :KIND :SUBSECTION :NAME (3 7 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-finish-output")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:PAR) "Ensures that all the output sent to " (:GROUP (:FONT :FACE :I) "medium")
       " has reached its destination, and only then return " (:TERM "false") ". This is used by " (:CL "finish-output")
       "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-force-output")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
       (:PAR) "Like " (:CL "medium-finish-output") ", except that it may return " (:TERM "false")
       " without waiting for the output to complete. This is used by " (:CL "force-output") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "medium-clear-area")) :PARAMS ((:I "medium left top right bottom")) :KIND
        ("Generic Function"))
       (:PAR) "Clears an area on the " (:GROUP "medium") " " (:GROUP (:FONT :FACE :I) "medium")
       " by filling the rectangle whose edges are at " (:GROUP (:FONT :FACE :I) "left") ", "
       (:GROUP (:FONT :FACE :I) "top") ", " (:GROUP (:FONT :FACE :I) "right") ", and "
       (:GROUP (:FONT :FACE :I) "bottom") " with the medium's background ink. " (:GROUP (:FONT :FACE :I) "left") ", "
       (:GROUP (:FONT :FACE :I) "top") ", " (:GROUP (:FONT :FACE :I) "right") ", and "
       (:GROUP (:FONT :FACE :I) "bottom") " are in thed medium's coordinate system." (:PAR) "The default method on "
       (:CL "basic-medium") " simply uses " (:CL "draw-rectangle*")
       " to clear the area. Some host window systems has special functions that are faster than "
       (:CL "draw-rectangle*") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "medium-beep")) :PARAMS ((:I "medium")) :KIND ("Generic Function")) (:PAR)
       "Causes an audible sound to be played on the medium. The default method does nothing." (:PAR)))))
   " "
   (:SECTION :TITLE ("13 " "Drawing in Color") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "color") (:PAR)
    "This chapter describes the " (:CL ":ink")
    " drawing option and the simpler values that can be supplied for that option, such as colors. More complex values that have a regular or irregular pattern in the ink are described in Chapter "
    (:REF :NAME "designs") "." (:PAR) (:GROUP (:FONT :FACE :B) "Major issue: ") " "
    (:GROUP (:FONT :FACE :SL)
     "We need to add a thing called a \"palette\", which is simply an abstract color map. Palettes are primarily used as a resource for the limited number of colors on most hosts. Do we need to be able to used them to more directly control color maps, to do \"color map animation\", for example? --- SWM")
    (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
    (:GROUP (:FONT :FACE :SL)
     "We need to add a thing called a \"raster ink\", which includes things like plane masks, pixel values, etc. Be clear that this is platform and device dependent. --- SWM")
    (:PAR) " "
    (:SECTION :TITLE ("13.1 " "The " (:GROUP (:FONT :FACE :TT) ":ink") " Drawing Option") :KIND :SECTION :NAME (8 5 10)
     (:PAR) "The " (:CL ":ink") " drawing option, used with the drawing functions described in Chapter "
     (:REF :NAME "graphics") ", can take as its value: "
     (:UL (:LI "a color," (:PAR)) (:LI "an opacity or the constant " (:CL "+transparent-ink+") "," (:PAR))
      (:LI "the constant " (:CL "+foreground-ink+") "," (:PAR))
      (:LI "the constant " (:CL "+background-ink+") "," (:PAR)) (:LI "a flipping ink, or" (:PAR))
      (:LI "other values described in Chapter " (:REF :NAME "designs") " "))
     (:PAR) "More exactly, an ink can be any member of the class " (:CL "design")
     ". For now you may think of a design as a possibly translucent color. More general designs are described in Chapter "
     (:REF :NAME "designs") "." (:PAR)
     "The drawing functions work by selecting a region of the drawing plane and painting it with color. The region to be painted is the intersection of the shape specified by the drawing function and the "
     (:CL ":clipping-region") " drawing option, which is then transformed by the " (:CL ":transformation")
     " drawing option. The " (:CL ":ink")
     " drawing option is a design that specifies a new arrangement of colors (and opacities) in this region of the medium's drawing plane. Any viewports or dataports attached to this drawing plane are updated accordingly. The "
     (:CL ":ink") " drawing option is never affected by the " (:CL ":transformation")
     " drawing option nor by the medium's transformation; this ensures that stipple patterns on adjacent sheets join seamlessly."
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "The description of how the clipping region and transformations contribute isn't good enough. It is true if there are no other transformations and clipping regions present, and both are specified in the current drawing operation. But it doesn't say what happens if things are nested. I'm not sure it needs to. Rather, I think it should just say that the the region is clipped by the current clipping region in effect, then transformed by the current transform in effect, and that the rules for these are discussed in the drawing options section. --- DCPL")
     (:PAR)
     "Drawing consists conceptually of the following sequence of operations, performed in parallel at every point in the drawing plane. Of course, the actual implementation does not involve an infinite (or large parallel) computation."
     (:PAR)
     (:OL
      (:LI
       "The design specifies a color and an opacity at the point. These can depend on the drawing plane's current color and opacity, on the medium's foreground color, and on the medium's background color."
       (:PAR))
      (:LI
       "The color blending function is applied to the design's color and opacity and the drawing plane's color and opacity, returning a new color and opacity for the point."
       (:PAR))
      (:LI "The drawing plane's color and opacity at that point are set to the new color and opacity. "))
     (:PAR))
    (:SECTION :TITLE ("13.2 " "Basic Designs") :KIND :SECTION :NAME (8 5 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "design")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "A design is an object that represents a way of arranging colors and opacities in the drawing plane. The "
      (:CL "design")
      " class is the protocol class for designs. If you want to create a new class that behaves like a design, it should be a subclass of "
      (:CL "design") ". All instantiable subclasses of " (:CL "design") " must obey the design protocol. " (:PAR)
      "The fundamental operation of the CLIM graphic drawing model is to draw a design onto a drawing plane, thus drawing is always controlled by designs. The designs discussed in this chapter do the same thing at each point in the drawing plane. Chapter "
      (:REF :NAME "designs") " discusses more general designs and reveals that regions are also designs." (:PAR)
      "A design can be characterized in several different ways:" (:PAR) "All designs are either " (:CONCEPT "bounded")
      " or " (:CONCEPT "unbounded")
      ". Bounded designs are transparent everywhere beyond a certain distance from a certain point. Drawing a bounded design has no effect on the drawing plane outside that distance. Unbounded designs have points of non-zero opacity arbitrarily far from the origin. Drawing an unbounded design affects the entire drawing plane."
      (:PAR) "All designs are either " (:CONCEPT "uniform") " or " (:CONCEPT "non-uniform")
      ". Uniform designs have the same color and opacity at every point in the drawing plane. Uniform designs are always unbounded, unless they are completely transparent."
      (:PAR) "All designs are either " (:CONCEPT "solid") " or " (:CONCEPT "translucent")
      ". At each point a solid design is either completely opaque or completely transparent. A solid design can be opaque at some points and transparent at others. In translucent designs, at least one point has an opacity that is intermediate between completely opaque and transparent."
      (:PAR) "All designs are either " (:CONCEPT "colorless") " or " (:CONCEPT "colored")
      ". Drawing a colorless design uses a default color specified by the medium's foreground design. This is done by drawing with "
      (:CL "(compose-in") " " (:CL "+foreground-ink+") " the-colorless-design" (:CL ")") ". See Chapter "
      (:REF :NAME "designs") " for the details of " (:CL "compose-in") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "designp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "design")
      ", otherwise returns " (:TERM "false") "." (:PAR) " "))
    (:SECTION :TITLE ("13.3 " "Color") :KIND :SECTION :NAME (8 5 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "color")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR) "A member of the class "
      (:CL "color")
      " is a completely opaque design that represents the intuitive definition of color: white, black, red, pale yellow, and so forth. The visual appearance of a single point is completely described by its color. Drawing a color sets the color of every point in the drawing plane to that color, and sets the opacity to 1. The "
      (:CL "color") " class is the protocol class for a color, and is a subclass of " (:CL "design")
      ". If you want to create a new class that behaves like a color, it should be a subclass of " (:CL "color")
      ". All instantiable subclasses of " (:CL "color") " must obey the color protocol. " (:PAR)
      "All of the standard instantiable color classes provided by CLIM are immutable." (:PAR)
      "A color can be specified by three real numbers between 0 and 1 (inclusive), giving the amounts of red, green, and blue. Three 0's mean black; three 1's mean white. The intensity-hue-saturation color model is also supported, but the red-green-blue color model is the primary model we will use in the specification."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "colorp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "color") ", otherwise returns "
      (:TERM "false") "." (:PAR)
      " The following functions create colors. These functions produce objects that have equivalent effects; the only difference is in how the color components are specified. The resulting objects are indistinguishable when drawn. Whether these functions use the specified values exactly or approximate them because of limited color resolution is unspecified. Whether these functions create a new object or return an existing object with equivalent color component values is unspecified."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-rgb-color")) :PARAMS ((:I "red green blue")) :KIND ("Function")) (:PAR)
      "Returns a member of class " (:CL "color") ". The " (:GROUP (:FONT :FACE :I) "red") ", "
      (:GROUP (:FONT :FACE :I) "green") ", and " (:GROUP (:FONT :FACE :I) "blue")
      " arguments are real numbers between 0 and 1 (inclusive) that specify the values of the corresponding color components."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-ihs-color")) :PARAMS ((:I "intensity hue saturation")) :KIND ("Function"))
      (:PAR) "Returns a member of class " (:CL "color") ". The " (:GROUP (:FONT :FACE :I) "intensity")
      " argument is a real number between 0 and " (:MATH "sqrt(" (:RM "3") ")") " (inclusive). The "
      (:GROUP (:FONT :FACE :I) "hue") " and " (:GROUP (:FONT :FACE :I) "saturation")
      " arguments are real numbers between 0 and 1 (inclusive)." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-gray-color")) :PARAMS ((:I "luminance")) :KIND ("Function")) (:PAR)
      "Returns a member of class " (:CL "color") ". " (:GROUP (:FONT :FACE :I) "luminance")
      " is a real number between 0 and 1 (inclusive). On a black-on-white display device, 0 means black, 1 means white, and the values in between are shades of gray. On a white-on-black display device, 0 means white, 1 means black, and the values in between are shades of gray."
      (:PAR)
      " The following two functions comprise the color protocol. Both of them return the components of a color. All subclasses of "
      (:CL "color") " must implement methods for these generic functions." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "color-rgb")) :PARAMS ((:I "color")) :KIND ("Generic Function")) (:PAR)
      "Returns three values, the " (:GROUP (:FONT :FACE :I) "red") ", " (:GROUP (:FONT :FACE :I) "green") ", and "
      (:GROUP (:FONT :FACE :I) "blue") " components of the " (:TERM "color") " " (:GROUP (:FONT :FACE :I) "color")
      ". The values are real numbers between 0 and 1 (inclusive)." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "color-ihs")) :PARAMS ((:I "color")) :KIND ("Generic Function")) (:PAR)
      "Returns three values, the " (:GROUP (:FONT :FACE :I) "intensity") ", " (:GROUP (:FONT :FACE :I) "hue") ", and "
      (:GROUP (:FONT :FACE :I) "saturation") " components of the " (:TERM "color") " "
      (:GROUP (:FONT :FACE :I) "color") ". The first value is a real number between 0 andn "
      (:MATH "sqrt(" (:RM "3") ")")
      " (inclusive). The second and third values are real numbers between 0 and 1 (inclusive)." (:PAR) " ")
     (:SECTION :TITLE ("13.3.1 " "Standard Color Names and Constants") :KIND :SUBSECTION :NAME (2 8 5 10) (:PAR)
      "Table " (:REF :NAME "color-names") " lists the commonly provided color names that can be looked up with "
      (:CL "find-named-color")
      ". Application programs can define other colors; these are provided because they are commonly used in the X Windows community, not because there is anything special about these particular colors. This table is a subset of the color listed in the file "
      (:CL "/X11/R4/mit/rgb/rgb.txt") ", from the X11 R4 distribution." (:PAR)
      (:TABLE :NUMBER "13.1" :CAPTION ((:LABEL :NAME "color-names") " Standard color names.") " " (:HR) "  "
       (:CL " "
            (:TABULAR
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " alice-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " antique-white "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " aquamarine ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " azure "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " beige "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " bisque ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " black "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " blanched-almond "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " blue ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " blue-violet "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " brown "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " burlywood ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " cadet-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " chartreuse "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " chocolate ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " coral "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " cornflower-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " cornsilk ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " cyan "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-goldenrod "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-green ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-khaki "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-olive-green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-orange ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-orchid "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-salmon "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-sea-green ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-slate-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-slate-gray "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-turquoise ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dark-violet "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " deep-pink "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " deep-sky-blue ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dim-gray "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " dodger-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " firebrick ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " floral-white "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " forest-green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " gainsboro ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " ghost-white "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " gold "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " goldenrod ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " gray "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " green-yellow ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " honeydew "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " hot-pink "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " indian-red ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " ivory "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " khaki "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " lavender ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " lavender-blush "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " lawn-green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " lemon-chiffon ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-coral "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-cyan ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-goldenrod "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-goldenrod-yellow "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-gray ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-pink "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-salmon "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-sea-green ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-sky-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-slate-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-slate-gray ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-steel-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " light-yellow "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " lime-green ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " linen "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " magenta "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " maroon ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-aquamarine "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-orchid ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-purple "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-sea-green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-slate-blue ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-spring-green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-turquoise "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " medium-violet-red ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " midnight-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " mint-cream "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " misty-rose ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " moccasin "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " navajo-white "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " navy-blue ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " old-lace "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " olive-drab "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " orange ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " orange-red "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " orchid "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " pale-goldenrod ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " pale-green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " pale-turquoise "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " pale-violet-red ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " papaya-whip "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " peach-puff "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " peru ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " pink "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " plum "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " powder-blue ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " purple "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " red "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " rosy-brown ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " royal-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " saddle-brown "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " salmon ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " sandy-brown "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " sea-green "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " seashell ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " sienna "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " sky-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " slate-blue ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " slate-gray "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " snow "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " spring-green ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " steel-blue "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " tan "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " thistle ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " tomato "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " turquoise "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " violet ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " violet-red "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " wheat "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " white ")))
             (:TR
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " white-smoke "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " yellow "))
              (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
               (:GROUP " yellow-green ")))))
       "   " (:HR) " ")
      (:PAR) "In addition, the following color constants are provided." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "+red+")) :PARAMS ((:I)) :KIND ("Constant"))
       (:SIGNATURE :NAME ((:CL "+green+")) :PARAMS ((:I)) :KIND ("Constant"))
       (:SIGNATURE :NAME ((:CL "+blue+")) :PARAMS ((:I)) :KIND ("Constant"))
       (:SIGNATURE :NAME ((:CL "+cyan+")) :PARAMS ((:I)) :KIND ("Constant"))
       (:SIGNATURE :NAME ((:CL "+magenta+")) :PARAMS ((:I)) :KIND ("Constant"))
       (:SIGNATURE :NAME ((:CL "+yellow+")) :PARAMS ((:I)) :KIND ("Constant"))
       (:SIGNATURE :NAME ((:CL "+black+")) :PARAMS ((:I)) :KIND ("Constant"))
       (:SIGNATURE :NAME ((:CL "+white+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
       "Constants corresponding to the usual definitions of red, green, blue, cyan, magenta, yellow, black, and white."
       (:PAR) " "))
     (:SECTION :TITLE ("13.3.2 " "Contrasting Colors") :KIND :SUBSECTION :NAME (2 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-contrasting-inks")) :PARAMS
        ((:I "n " (:GROUP (:FONT :FACE :TT) "&optional ") "k")) :KIND ("Function"))
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "k") " is not supplied, this returns a vector of "
       (:GROUP (:FONT :FACE :I) "n")
       " designs with recognizably different appearance. Elements of the vector are guaranteed to be acceptable values for the "
       (:CL ":ink") " argument to the drawing functions, and will not include " (:CL "+foreground-ink+") ", "
       (:CL "+background-ink+") ", or " (:CL "nil")
       ". Their class is otherwise unspecified. The vector is a fresh object that may be modified." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "k") " is supplied, it must be an integer between 0 and "
       (:MATH (:GROUP (:FONT :FACE :I) "n") " - " (:RM "1")) " (inclusive), in which case "
       (:CL "make-contrasting-inks") " returns the " (:GROUP (:FONT :FACE :I) "k")
       "'th design rather than returning a vector of designs." (:PAR) "If the implementation does not have "
       (:GROUP (:FONT :FACE :I) "n") " different contrasting inks, " (:CL "make-contrasting-inks")
       " signals an error. This will not happen unless " (:GROUP (:FONT :FACE :I) "n") " is greater than eight." (:PAR)
       "The rendering of the design may be a color or a stippled pattern, depending on whether the output medium supports color."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "contrasting-inks-limit")) :PARAMS ((:I "port")) :KIND ("Generic Function"))
       (:PAR) "Returns the number of contrasting colors (or stipple patterns if " (:GROUP (:FONT :FACE :I) "port")
       " is monochrome or grayscale) that can be rendered on any medium on the " (:TERM "port") " "
       (:GROUP (:FONT :FACE :I) "port")
       ". Implementations are encouraged to make this as large as possible, but it must be at least 8. All classes that obey the medium protocol must implement a method for this generic function."
       (:PAR) " ")))
    (:SECTION :TITLE ("13.4 " "Opacity") :KIND :SECTION :NAME (8 5 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "opacity")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "A member of the class " (:CL "opacity")
      " is a completely colorless design that is typically used as the second argument to " (:CL "compose-in")
      " to adjust the opacity of another design. See Chapter " (:REF :NAME "designs") " for the details of "
      (:CL "compose-in") ". The " (:CL "opacity") " class is the protocol class for an opacity, and is a subclass of "
      (:CL "design") ". If you want to create a new class that behaves like an opacity, it should be a subclass of "
      (:CL "opacity") ". All instantiable subclasses of " (:CL "opacity") " must obey the opacity protocol. " (:PAR)
      "All of the standard instantiable opacity classes provided by CLIM are immutable." (:PAR)
      "Opacity controls how graphical output covers previous output. Opacity can vary from totally opaque to totally transparent. Intermediate opacity values result in color blending so that the earlier picture shows through what is drawn on top of it."
      (:PAR)
      "An opacity may be specified by a real number between 0 and 1 (inclusive). 0 is completely transparent, 1 is completely opaque, fractions are translucent. The opacity of a design is the degree to which it hides the previous contents of the drawing plane when it is drawn."
      (:PAR)
      "The fully transparent and fully opaque opacity levels (that is, opacities 0 and 1) must always be supported, but a valid CLIM implementation might only support a handful of opacity levels in between (including none). A valid CLIM implementation might implement color blending and unsaturated colors by stippling, although it is preferred, when possible, for a viewport to display a uniform color as a uniform color rather than as a perceptible stipple."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "opacityp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an " (:TERM "opacity")
      ", otherwise returns " (:TERM "false") "." (:PAR) " The following function returns an opacity:" (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-opacity")) :PARAMS ((:I "value")) :KIND ("Function")) (:PAR)
      "Returns a member of class " (:CL "opacity") " whose opacity is " (:GROUP (:FONT :FACE :I) "value")
      ", which is a real number in the range from 0 to 1 (inclusive), where 0 is fully transparent and 1 is fully opaque."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "+transparent-ink+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "An fully transparent ink, that is, an opacity whose value is 0. This is typically used as the \"background\" ink in a call to "
      (:CL "make-pattern") "." (:PAR)
      " The following function returns the sole component of an opacity. This is the only function in the opacity protocol. All subclasses of "
      (:CL "opacity") " must implement methods for this generic function." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "opacity-value")) :PARAMS ((:I "opacity")) :KIND ("Generic Function")) (:PAR)
      "Returns the opacity value of the " (:TERM "opacity") " " (:GROUP (:FONT :FACE :I) "opacity")
      ", which is a real number in the range from 0 to 1 (inclusive)." (:PAR) " "))
    (:SECTION :TITLE ("13.5 " "Color Blending") :KIND :SECTION :NAME (8 5 10) (:PAR)
     "Drawing a design that is not completely opaque at all points allows the previous contents of the drawing plane to show through. The simplest case is drawing a solid design: where the design is opaque, it replaces the previous contents of the drawing plane; where the design is transparent, it leaves the drawing plane unchanged. In the more general case of drawing a translucent design, the resulting color is a blend of the design's color and the previous color of the drawing plane. For purposes of color blending, the drawn design is called the foreground and the drawing plane is called the background."
     (:PAR) "The function " (:CL "compose-over")
     " performs a similar operation: it combines two designs to produce a design, rather than combining a design and the contents of the drawing plane to produce the new contents of the drawing plane. For purposes of color blending, the first argument to "
     (:CL "compose-over") " is called the foreground and the second argument is called the background. See Chapter "
     (:REF :NAME "designs") " for the details of " (:CL "compose-over") "." (:PAR)
     "Color blending is defined by an ideal function "
     (:MATH (:GROUP "F") ":(r" (:SUB (:RM "1")) ",g" (:SUB (:RM "1")) ",b" (:SUB (:RM "1")) ",o" (:SUB (:RM "1")) ",r"
      (:SUB (:RM "2")) ",g" (:SUB (:RM "2")) ",b" (:SUB (:RM "2")) ",o" (:SUB (:RM "2")) ")" (:ENTITY :NAME "rarr")
      "(r" (:SUB (:RM "3")) ",g" (:SUB (:RM "3")) ",b" (:SUB (:RM "3")) ",o" (:SUB (:RM "3")) ")")
     " that operates on the color and opacity at a single point. "
     (:MATH "(r" (:SUB (:RM "1")) ",g" (:SUB (:RM "1")) ",b" (:SUB (:RM "1")) ",o" (:SUB (:RM "1")) ")")
     " are the foreground color and opacity. "
     (:MATH "(r" (:SUB (:RM "2")) ",g" (:SUB (:RM "2")) ",b" (:SUB (:RM "2")) ",o" (:SUB (:RM "2")) ")")
     " are the background color and opacity. "
     (:MATH "(r" (:SUB (:RM "3")) ",g" (:SUB (:RM "3")) ",b" (:SUB (:RM "3")) ",o" (:SUB (:RM "3")) ")")
     " are the resulting color and opacity. The color blending function " (:MATH (:GROUP "F"))
     " is conceptually applied at every point in the drawing plane." (:PAR) (:MATH (:GROUP "F"))
     " performs linear interpolation on all four components: "
     (:DISPMATH
      (:TABULAR
       (:TR
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "o" (:SUB (:RM "3"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " = "))
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "o" (:SUB (:RM "1"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " + "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "(" (:RM "1") " - o" (:SUB (:RM "1")) ")*o" (:SUB (:RM "2")))))
       (:TR
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "r" (:SUB (:RM "3"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " = "))
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "(o" (:SUB (:RM "1")) "*r" (:SUB (:RM "1"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " + "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "(" (:RM "1") " - o" (:SUB (:RM "1")) ")*o" (:SUB (:RM "2")) "*r" (:SUB (:RM "2")) ")/o"
          (:SUB (:RM "3")))))
       (:TR
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "g" (:SUB (:RM "3"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " = "))
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "(o" (:SUB (:RM "1")) "*g" (:SUB (:RM "1"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " + "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "(" (:RM "1") " - o" (:SUB (:RM "1")) ")*o" (:SUB (:RM "2")) "*g" (:SUB (:RM "2")) ")/o"
          (:SUB (:RM "3")))))
       (:TR
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "b" (:SUB (:RM "3"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " = "))
        (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "(o" (:SUB (:RM "1")) "*b" (:SUB (:RM "1"))))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " + "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP "(" (:RM "1") " - o" (:SUB (:RM "1")) ")*o" (:SUB (:RM "2")) "*b" (:SUB (:RM "2")) ")/o"
          (:SUB (:RM "3")))))))
     " Note that if " (:MATH "o" (:SUB (:RM "3"))) " is zero, these equations would divide zero by zero. In that case "
     (:MATH "r" (:SUB (:RM "3"))) ", " (:MATH "g" (:SUB (:RM "3"))) ", and " (:MATH "b" (:SUB (:RM "3")))
     " are defined to be zero." (:PAR) "CLIM requires that " (:MATH (:GROUP "F")) " be implemented exactly if "
     (:MATH "o" (:SUB (:RM "1"))) " is zero or one or if " (:MATH "o" (:SUB (:RM "2"))) " is zero. If "
     (:MATH "o" (:SUB (:RM "1"))) " is zero, the result is the background. If " (:MATH "o" (:SUB (:RM "1")))
     " is one or " (:MATH "o" (:SUB (:RM "2")))
     " is zero, the result is the foreground. For fractional opacity values, an implementation can deviate from the ideal color blending function either because the implementation has limited opacity resolution or because the implementation can compute a different color blending function much more quickly."
     (:PAR)
     "If a medium's background design is not completely opaque at all points, the consequences are unspecified. Consequently, a drawing plane is always opaque and drawing can use simplified color blending that assumes "
     (:MATH "o" (:SUB (:RM "2")) " = " (:RM "1")) " and " (:MATH "o" (:SUB (:RM "3")) " = " (:RM "1")) ". However, "
     (:CL "compose-over") " must handle a non-opaque background correctly." (:PAR) "Note that these "
     (:MATH "(r,g,b,o)")
     " quadruples of real numbers between 0 and 1 are mathematical and an implementation need not store information in this form. Most implementations are expected to use a different representation."
     (:PAR) " ")
    (:SECTION :TITLE ("13.6 " "Indirect Inks") :KIND :SECTION :NAME (8 5 10) (:PAR) "Drawing with an "
     (:CONCEPT "indirect ink") " is the same as drawing another design named directly. For example, "
     (:CL "+foreground-ink+") " is a design that draws the medium's foreground design and is the default value of the "
     (:CL ":ink")
     " drawing option. Indirect inks exist for the benefit of output recording. For example, one can draw with "
     (:CL "+foreground-ink+") ", change to a different " (:CL "medium-foreground")
     ", and replay the output record; the replayed output will come out in the new color." (:PAR)
     "You can change the foreground or background design of a medium at any time. This changes the contents of the medium's drawing plane. The effect is as if everything on the drawing plane is erased, the background design is drawn onto the drawing plane, and then everything that was ever drawn (provided it was saved in the output history) is drawn over again, using the medium's new foreground and background."
     (:PAR)
     "If an infinite recursion is created using an indirect ink, an error is signalled when the recursion is created, when the design is used for drawing, or both."
     (:PAR) "Two indirect inks are defined, but no advertised way is provided to create more of them." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "+foreground-ink+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "An indirect ink that uses the medium's foreground design." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "+background-ink+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "An indirect ink that uses the medium's background design." (:PAR) " "))
    (:SECTION :TITLE ("13.7 " "Flipping Ink") :KIND :SECTION :NAME (8 5 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-flipping-ink")) :PARAMS ((:I "design1 design2")) :KIND ("Function")) (:PAR)
      "Returns a design that interchanges occurrences of the two " (:TERM "designs") " "
      (:GROUP (:FONT :FACE :I) "design1") " and " (:GROUP (:FONT :FACE :I) "design2")
      ". Drawing the resulting design over a background (either by drawing or with " (:CL "compose-over")
      ") is defined to change the color in the background that would have been drawn by "
      (:GROUP (:FONT :FACE :I) "design1") " at that point into the color that would have been drawn by "
      (:GROUP (:FONT :FACE :I) "design2")
      " at that point, and vice versa. The effect on any color other than the colors determined by those two designs is unspecified; however, drawing the same figure twice using the same flipping ink is guaranteed to be an \"identity\" operation. If either "
      (:GROUP (:FONT :FACE :I) "design1") " or " (:GROUP (:FONT :FACE :I) "design2")
      " is not solid, the consequences are unspecified. The purpose of flipping is to allow the use of \"XOR hacks\" for temporary changes to the display."
      (:PAR) "The opacity of a flipping ink is zero at points where the opacity of either "
      (:GROUP (:FONT :FACE :I) "design1") " or " (:GROUP (:FONT :FACE :I) "design2")
      " is zero. Otherwise the opacity of a flipping ink is 1. If " (:GROUP (:FONT :FACE :I) "design1") " or "
      (:GROUP (:FONT :FACE :I) "design2") " is translucent, the consequences are unspecified. If " (:CL "compose-in")
      " or " (:CL "compose-out") " is used to make a flipping ink translucent, the consequences are unspecified."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "design1") " and " (:GROUP (:FONT :FACE :I) "design2")
      " are equivalent, the result can be " (:CL "+nowhere+") "." (:PAR) "In Release 2, " (:CL "make-flipping-ink")
      " might require " (:GROUP (:FONT :FACE :I) "design1") " and " (:GROUP (:FONT :FACE :I) "design2")
      " to be colors." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "+flipping-ink+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "A flipping ink that flips " (:CL "+foreground-ink+") " and " (:CL "+background-ink+") "." (:PAR) " "))
    (:SECTION :TITLE ("13.8 " "Examples of Simple Drawing Effects") :KIND :SECTION :NAME (8 5 10) (:PAR)
     (:SECTION :TITLE ("Drawing in the foreground color.") :KIND :PARAGRAPH (:PAR) "Use the default, or specify "
      (:CL ":ink +foreground-ink+") "." (:PAR))
     (:SECTION :TITLE ("Erasing.") :KIND :PARAGRAPH (:PAR) "Specify " (:CL ":ink +background-ink+") "." (:PAR))
     (:SECTION :TITLE ("Drawing in color.") :KIND :PARAGRAPH (:PAR) "Specify " (:CL ":ink +green+") ", "
      (:CL ":ink (make-rgb-color 0.6 0.0 0.4)") ", and so forth." (:PAR))
     (:SECTION :TITLE ("Drawing an opaque gray.") :KIND :PARAGRAPH (:PAR) "Specify "
      (:CL ":ink (make-gray-color 0.25)")
      " to draw in a shade of gray independent of the window's foreground color. On a non-color, non-grayscale display this will generally turn into a stipple."
      (:PAR))))
   " "
   (:SECTION :TITLE ("14 " "General Designs") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "designs") (:PAR)
    "This chapter discusses more general designs than Chapter " (:REF :NAME "color")
    " and reveals that regions are also designs. This chapter generalizes to those designs that do not have the same color and opacity at every point in the drawing plane. These include:"
    (:PAR)
    (:UL (:LI "composite designs," (:PAR)) (:LI "patterns," (:PAR)) (:LI "stencils," (:PAR))
     (:LI "tiled designs," (:PAR)) (:LI "transformed designs," (:PAR)) (:LI "output record designs, and" (:PAR))
     (:LI "regions "))
    (:PAR) "Several of the features described in this chapter may not be fully supported in Release 2 of CLIM." (:PAR)
    (:GROUP (:FONT :FACE :B) "Note:")
    " A design is a unification of both a shape and a color and opacity. As such, a design can serve multiple roles. For example, the same design can play the role of an ink that colors the drawing plane, a shape that specifies where to draw another design, a stencil that controls the compositing of two designs, the background of a window, or a region that defines clipping. It is important not to get confused between "
    (:TERM "type") ", which is inherent in an object, and " (:TERM "role")
    ", which is determined by how an object is used in a particular function call." (:PAR) " "
    (:SECTION :TITLE ("14.1 " "The Compositing Protocol") :KIND :SECTION :NAME (7 5 10) (:PAR) (:CONCEPT "Compositing")
     " creates a design whose appearance at each point is a composite of the appearances of two other designs at that point. Three varieties of compositing are provided: "
     (:CONCEPT "composing over") ", " (:CONCEPT "composing in") ", and " (:CONCEPT "composing out") "." (:PAR)
     "The methods for " (:CL "compose-over") ", " (:CL "compose-in") ", and " (:CL "compose-out")
     " will typically specialize both of the design arguments." (:PAR)
     (:GROUP (:FONT :FACE :SL) "In Release 2, compositing might only be supported for uniform designs.") (:PAR) " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "compose-over")) :PARAMS ((:I "design1 design2")) :KIND ("Generic Function"))
      (:PAR) "Composes a new design that is equivalent to the " (:TERM "design") " "
      (:GROUP (:FONT :FACE :I) "design1") " on top of the " (:TERM "design") " " (:GROUP (:FONT :FACE :I) "design2")
      ". Drawing the resulting design produces the same visual appearance as drawing "
      (:GROUP (:FONT :FACE :I) "design2") " and then drawing " (:GROUP (:FONT :FACE :I) "design1")
      ", but might be faster and might not allow the intermediate state to be visible on the screen." (:PAR)
      "If both arguments are regions, " (:CL "compose-over") " is the same as " (:CL "region-union") "." (:PAR)
      "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified.  The result returned by "
      (:CL "compose-over") " might be freshly constructed or might be an existing object." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "compose-in")) :PARAMS ((:I "ink mask")) :KIND ("Generic Function")) (:PAR)
      "Composes a new design by clipping the " (:TERM "design") " " (:GROUP (:FONT :FACE :I) "ink")
      " to the inside of the " (:TERM "design") " " (:GROUP (:FONT :FACE :I) "mask") ". The first design, "
      (:GROUP (:FONT :FACE :I) "ink") ", supplies the color, while the second design, "
      (:GROUP (:FONT :FACE :I) "mask") ", changes the shape of the design by adjusting the opacity." (:PAR)
      "More precisely, at each point in the drawing plane the resulting design specifies a color and an opacity as follows: the color is the same color that "
      (:GROUP (:FONT :FACE :I) "ink") " specifies. The opacity is the opacity that " (:GROUP (:FONT :FACE :I) "ink")
      " specifies, multiplied by the stencil opacity of " (:GROUP (:FONT :FACE :I) "mask") "." (:PAR) "The "
      (:CONCEPT "stencil opacity")
      " of a design at a point is defined as the opacity that would result from drawing the design onto a fictitious medium whose drawing plane is initially completely transparent black (opacity and all color components are zero), and whose foreground and background are both opaque black. With this definition, the stencil opacity of a member of class "
      (:CL "opacity") " is simply its value." (:PAR) "If " (:GROUP (:FONT :FACE :I) "mask")
      " is a solid design, the effect of " (:CL "compose-in") " is to clip " (:GROUP (:FONT :FACE :I) "ink") " to "
      (:GROUP (:FONT :FACE :I) "mask") ". If " (:GROUP (:FONT :FACE :I) "mask")
      " is translucent, the effect is a soft matte." (:PAR) "If both arguments are regions, " (:CL "compose-in")
      " is the same as " (:CL "region-intersection") "." (:PAR)
      "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified.  The result returned by "
      (:CL "compose-in") " might be freshly constructed or might be an existing object." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "compose-out")) :PARAMS ((:I "ink mask")) :KIND ("Generic Function")) (:PAR)
      "Composes a new design by clipping the " (:TERM "design") " " (:GROUP (:FONT :FACE :I) "ink")
      " to the outside of the " (:TERM "design") " " (:GROUP (:FONT :FACE :I) "mask") ". The first design, "
      (:GROUP (:FONT :FACE :I) "ink") ", supplies the color, while the second design, "
      (:GROUP (:FONT :FACE :I) "mask") ", changes the shape of the design by adjusting the opacity." (:PAR)
      "More precisely, at each point in the drawing plane the resulting design specifies a color and an opacity as follows: the color is the same color that "
      (:GROUP (:FONT :FACE :I) "ink") " specifies. The opacity is the opacity that " (:GROUP (:FONT :FACE :I) "ink")
      " specifies, multiplied by 1 minus the stencil opacity of " (:GROUP (:FONT :FACE :I) "mask") "." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "mask") " is a solid design, the effect of " (:CL "compose-out") " is to clip "
      (:GROUP (:FONT :FACE :I) "ink") " to the complement of " (:GROUP (:FONT :FACE :I) "mask") ". If "
      (:GROUP (:FONT :FACE :I) "mask") " is translucent, the effect is a soft matte." (:PAR)
      "If both arguments are regions, " (:CL "compose-out") " is the same as " (:CL "region-difference") " of "
      (:GROUP (:FONT :FACE :I) "mask") " and " (:GROUP (:FONT :FACE :I) "ink") "." (:PAR)
      "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified.  The result returned by "
      (:CL "compose-out") " might be freshly constructed or might be an existing object." (:PAR) " "))
    (:SECTION :TITLE ("14.2 " "Patterns and Stencils") :KIND :SECTION :NAME (7 5 10) (:PAR) (:CONCEPT "Patterning")
     " creates a bounded rectangular arrangement of designs, like a checkerboard. Drawing a pattern draws a different design in each rectangular cell of the pattern. To create an infinite pattern, apply "
     (:CL "make-rectangular-tile") " to a pattern." (:PAR) "A " (:CONCEPT "stencil")
     " is a special kind of pattern that contains only opacities." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-pattern")) :PARAMS ((:I "array designs")) :KIND ("Function")) (:PAR)
      "Returns a pattern design that has " (:CL "(array-dimension " (:GROUP (:FONT :FACE :I) "array") " 0)")
      " cells in the vertical direction and " (:CL "(array-dimension " (:GROUP (:FONT :FACE :I) "array") " 1)")
      " cells in the horizontal direction. " (:GROUP (:FONT :FACE :I) "array")
      " must be a two-dimensional array of non-negative integers less than the length of "
      (:GROUP (:FONT :FACE :I) "designs") ". " (:GROUP (:FONT :FACE :I) "designs") " must be a sequence of "
      (:TERM "designs") ". The design in cell " (:MATH "(i,j)") " of the resulting pattern is the " (:MATH "n")
      "th element of " (:GROUP (:FONT :FACE :I) "designs") ", if " (:MATH "n") " is the value of "
      (:CL "(aref " (:GROUP (:FONT :FACE :I) "array") " i j)") ". For example, " (:GROUP (:FONT :FACE :I) "array")
      " can be a bit-array and " (:GROUP (:FONT :FACE :I) "designs")
      " can be a list of two designs, the design drawn for 0 and the one drawn for 1." (:PAR)
      "Each cell of a pattern can be regarded as a hole that allows the design in it to show through. Each cell might have a different design in it. The portion of the design that shows through a hole is the portion on the part of the drawing plane where the hole is located. In other words, incorporating a design into a pattern does not change its alignment to the drawing plane, and does not apply a coordinate transformation to the design. Drawing a pattern collects the pieces of designs that show through all the holes and draws the pieces where the holes lie on the drawing plane. The pattern is completely transparent outside the area defined by the array."
      (:PAR) "Each cell of a pattern occupies a 1 by 1 square. You can use " (:CL "transform-region")
      " to scale the pattern to a different cell size and shape, or to rotate the pattern so that the rectangular cells become diamond-shaped. Applying a coordinate transformation to a pattern does not affect the designs that make up the pattern. It only changes the position, size, and shape of the cells' holes, allowing different portions of the designs in the cells to show through. Consequently, applying "
      (:CL "make-rectangular-tile")
      " to a pattern of nonuniform designs can produce a different appearance in each tile. The pattern cells' holes are tiled, but the designs in the cells are not tiled and a different portion of each of those designs shows through in each tile."
      (:PAR)
      "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pattern-width")) :PARAMS ((:I "pattern")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "pattern-height")) :PARAMS ((:I "pattern")) :KIND ("Generic Function")) (:PAR)
      "These functions return the width and height, respectively, of the " (:TERM "pattern") " "
      (:GROUP (:FONT :FACE :I) "pattern") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-stencil")) :PARAMS ((:I "array")) :KIND ("Function")) (:PAR)
      "Returns a pattern design that has " (:CL "(array-dimension " (:GROUP (:FONT :FACE :I) "array") " 0)")
      " cells in the vertical direction and " (:CL "(array-dimension " (:GROUP (:FONT :FACE :I) "array") " 1)")
      " cells in the horizontal direction. " (:GROUP (:FONT :FACE :I) "array")
      " must be a two-dimensional array of real numbers between 0 and 1 (inclusive) that represent opacities. The design in cell "
      (:MATH "(i,j)") " of the resulting pattern is the value of "
      (:CL "(make-opacity (aref " (:GROUP (:FONT :FACE :I) "array") " i j))") "." (:PAR)
      "This function is permitted to capture its mutable inputs; the consequences of modifying those objects are unspecified. "
      (:PAR) " "))
    (:SECTION :TITLE ("14.3 " "Tiling") :KIND :SECTION :NAME (7 5 10) (:PAR) (:CONCEPT "Tiling")
     " repeats a rectangular portion of a design throughout the drawing plane. This is most commonly used with patterns."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "make-rectangular-tile")) :PARAMS ((:I "design width height")) :KIND ("Function"))
      (:PAR) "Returns a design that, when used as an ink, tiles a rectangular portion of the " (:TERM "design") " "
      (:GROUP (:FONT :FACE :I) "design")
      " across the entire drawing plane. The resulting design repeats with a period of "
      (:GROUP (:FONT :FACE :I) "width") " horizontally and " (:GROUP (:FONT :FACE :I) "height") " vertically. "
      (:GROUP (:FONT :FACE :I) "width") " and " (:GROUP (:FONT :FACE :I) "height")
      " must both be integers. The portion of " (:GROUP (:FONT :FACE :I) "design")
      " that appears in each tile is a rectangle whose top-left corner is at " (:MATH "(" (:RM "0") "," (:RM "0") ")")
      " and whose bottom-right corner is at " (:MATH "(width,height)") ". The repetition of "
      (:GROUP (:FONT :FACE :I) "design") " is accomplished by applying a coordinate transformation to shift "
      (:GROUP (:FONT :FACE :I) "design") " into position for each tile, and then extracting a "
      (:GROUP (:FONT :FACE :I) "width") " by " (:GROUP (:FONT :FACE :I) "height") " portion of that design." (:PAR)
      "Applying a coordinate transformation to a rectangular tile does not change the portion of the argument "
      (:GROUP (:FONT :FACE :I) "design")
      " that appears in each tile. However, it can change the period, phase, and orientation of the repeated pattern of tiles. This is so that adjacent figures drawn using the same tile have their inks \"line up\"."
      (:PAR) " "))
    (:SECTION :TITLE ("14.4 " "Regions as Designs") :KIND :SECTION :NAME (7 5 10) (:PAR) "Any member of the class "
     (:CL "region")
     " is a solid, colorless design. The design is opaque at points in the region and transparent elsewhere. Figure "
     (:REF :NAME "design-classes") " shows how the design and region classes relate to each other." (:PAR)
     (:FIGURE :NUMBER "14.1" :CAPTION
      ((:LABEL :NAME "design-classes")
       " The class structure for all designs and regions. Entries in bold correspond to real CLIM classes.")
      " " (:CENTER (:IMG :SRC "design-classes.png")) "  ")
     (:PAR) "Since bounded designs obey the region protocol, the functions " (:CL "transform-region") " and "
     (:CL "untransform-region")
     " accept any design as their second argument and apply a coordinate transformation to the design. The result is a design that might be freshly constructed or might be an existing object."
     (:PAR)
     "Transforming a uniform design simply returns the argument. Transforming a composite, flipping, or indirect design applies the transformation to the component design(s). Transforming a pattern, tile, or output record design is described in the sections on those designs."
     (:PAR) " ")
    (:SECTION :TITLE ("14.5 " "Arbitrary Designs") :KIND :SECTION :NAME (7 5 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "draw-design")) :PARAMS
       ((:I "medium design " (:GROUP (:FONT :FACE :TT) "&key ")
         "ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape line-cap-shape text-style text-family text-face text-size"))
       :KIND ("Generic Function"))
      (:PAR) "Draws the " (:TERM "design") " " (:GROUP (:FONT :FACE :I) "design") " onto the " (:TERM "medium") " "
      (:GROUP (:FONT :FACE :I) "medium")
      ". This is defined to work for all types of regions and designs, although in practice some implementations may be more restrictive. "
      (:GROUP (:FONT :FACE :I) "ink") ", " (:GROUP (:FONT :FACE :I) "transformation") ", and "
      (:GROUP (:FONT :FACE :I) "clipping-region")
      " are used to modify the medium. The other drawing arguments control the drawing of the design, depending on what sort of design is being drawn. For instance, if "
      (:GROUP (:FONT :FACE :I) "design") " is a path, then line style options may be supplied." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "design") " is an area, " (:CL "draw-design")
      " paints the specified region of the drawing plane with medium's current ink. If "
      (:GROUP (:FONT :FACE :I) "design") " is a path, " (:CL "draw-design")
      " strokes the path with medium's current ink under control of the line-style. If "
      (:GROUP (:FONT :FACE :I) "design") " is a point, " (:CL "draw-design") " is the same as " (:CL "draw-point") "."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "design") " is a color or an opacity, " (:CL "draw-design")
      " paints the entire drawing plane (subject to the clipping region of the medium)." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "design") " is " (:CL "+nowhere+") ", " (:CL "draw-design") " has no effect." (:PAR)
      "If " (:GROUP (:FONT :FACE :I) "design") " is a non-uniform design (see Chapter " (:REF :NAME "designs") "), "
      (:CL "draw-design") " paints the design, positioned at coordinates " (:MATH "(" (:RM "0") "," (:RM "0") ")") "."
      (:PAR) "CLIM implementations are required to support " (:CL "draw-design") " for the following cases:" (:PAR)
      (:UL
       (:LI "Designs created by the geometric object constructors, such as " (:CL "make-line") " and "
        (:CL "make-ellipse") ", in conjunction with drawing arguments that supply the drawing ink." (:PAR))
       (:LI "Designs created by calling " (:CL "compose-in")
        " on a color and an object created by a geometric object constructor." (:PAR))
       (:LI "Designs created by calling " (:CL "compose-over") " on any of the cases above." (:PAR))
       (:LI "Designs returned by " (:CL "make-design-from-output-record") ". "))
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "draw-pattern*")) :PARAMS
       ((:I "medium pattern x y " (:GROUP (:FONT :FACE :TT) "&key ") "clipping-region transformation")) :KIND
       ("Function"))
      (:PAR) "Draws the pattern " (:GROUP (:FONT :FACE :I) "pattern") " on the " (:TERM "medium") " "
      (:GROUP (:FONT :FACE :I) "medium") " at the position " (:MATH "(x,y)") ". " (:GROUP (:FONT :FACE :I) "pattern")
      " is any design created by " (:CL "make-pattern") ". " (:GROUP (:FONT :FACE :I) "clipping-region") " and "
      (:GROUP (:FONT :FACE :I) "transformation") " are as for " (:CL "with-drawing-options")
      " or any of the drawing functions." (:PAR) "Note that " (:GROUP (:FONT :FACE :I) "transformation")
      " only affects the position at which the pattern is drawn, not the pattern itself. If a programmer wishes to affect the pattern, he should explicity call "
      (:CL "transform-region") " on the pattern." (:PAR)
      "Drawing a bitmap consists of drawing an appropriately aligned and scaled pattern constructed from the bitmap's bits. A 1 in the bitmap corresponds to "
      (:CL "+foreground-ink+") ", while a 0 corresponds to " (:CL "+background-ink+")
      " if an opaque drawing operation is desired, or to " (:CL "+nowhere+")
      " if a transparent drawing operation is desired." (:PAR)
      "Drawing a (colored) raster image consists of drawing an appropriately aligned and scaled pattern constructed from the raster array and raster color map."
      (:PAR) (:CL "draw-pattern*") " could be implemented as follows, assuming that the functions "
      (:CL "pattern-width") " and " (:CL "pattern-height") " return the width and height of the pattern." (:PAR)
      (:PRE "
(defun draw-pattern* (medium pattern x y &key clipping-region transformation)
  (check-type pattern pattern)
  (let ((width (pattern-width pattern))
        (height (pattern-height pattern)))
    (if (or clipping-region transformation)
        (with-drawing-options (medium :clipping-region clipping-region
                                      :transformation transformation)
          (draw-rectangle* medium x y (+ x width) (+ y height)
                           :filled t :ink pattern))
        (draw-rectangle* medium x y (+ x width) (+ y height)
                         :filled t :ink pattern))))
")
      (:PAR) " "))
    (:SECTION :TITLE ("14.6 " "Examples of More Complex Drawing Effects") :KIND :SECTION :NAME (7 5 10) (:PAR)
     (:SECTION :TITLE ("Painting a gray or colored wash over a display.") :KIND :PARAGRAPH (:PAR)
      "Specify a translucent design as the ink, such as " (:CL ":ink (compose-in +black+ (make-opacity 0.25))") ", "
      (:CL ":ink (compose-in +red+ (make-opacity 0.1))") ", or "
      (:CL ":ink (compose-in +foreground-ink+ (make-opacity 0.75))") ". The last example can be abbreviated as "
      (:CL ":ink (make-opacity 0.75)") ". On a non-color, non-grayscale display this will usually turn into a stipple."
      (:PAR))
     (:SECTION :TITLE ("Drawing a faded but opaque version of the foreground color.") :KIND :PARAGRAPH (:PAR)
      "Specify " (:CL ":ink (compose-over (compose-in +foreground-ink+ (make-opacity 0.25)) +background-ink+)")
      " to draw at 25% of the normal contrast. On a non-color, non-grayscale display this will probably turn into a stipple."
      (:PAR))
     (:SECTION :TITLE ("Drawing a tiled pattern.") :KIND :PARAGRAPH (:PAR) "Specify "
      (:CL ":ink (make-rectangular-tile (make-pattern "
           (:GROUP (:FONT :FACE :I) "array")
           " "
           (:GROUP (:FONT :FACE :I) "colors")
           "))")
      "." (:PAR))
     (:SECTION :TITLE ("Drawing a \"bitmap\".") :KIND :PARAGRAPH (:PAR) "Use "
      (:CL "(draw-design "
           (:GROUP (:FONT :FACE :I) "medium")
           " (make-pattern "
           (:GROUP (:FONT :FACE :I) "bit-array")
           " (list +background-ink+ +foreground-ink+)) :transformation (make-translation-transformation "
           (:GROUP (:FONT :FACE :I) "x")
           " "
           (:GROUP (:FONT :FACE :I) "y")
           "))")
      "." (:PAR) " "))
    (:SECTION :TITLE ("14.7 " "Design Protocol") :KIND :SECTION :NAME (7 5 10) (:PAR)
     (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "The generic functions underlying the functions described in this and the preceding chapter will be documented later. This will allow for programmer-defined design classes. This also needs to describe how to decode designs into inks. --- SWM")
     (:PAR)))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part V: " "Extended Stream Output Facilities") :NAME (10) " " " "
   (:SECTION :TITLE ("15 " "Extended Stream Output") :KIND :CHAPTER :NAME (7 10) " " (:LABEL :NAME "extended-output")
    (:PAR)
    "CLIM provides a stream-oriented output layer that is implemented on top of the sheet output architecture. The basic CLIM output stream protocol is based on the character output stream protocol proposal submitted to the ANSI Common Lisp committee by David Gray. This proposal was not approved by the committee, but has been implemented by most Lisp vendors."
    (:PAR)
    (:SECTION :TITLE ("15.1 " "Basic Output Streams") :KIND :SECTION :NAME (6 7 10) (:PAR)
     "CLIM provides an implementation of the basic output stream facilities (described in more detail in Appendix "
     (:REF :NAME "gray-streams")
     "), either by directly using the underlying Lisp implementation, or by implementing the facilities itself." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-output-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "This class provides an implementation of the CLIM basic output stream protocol, based on the CLIM output kernel. Members of this class are mutable. "
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-write-char")) :PARAMS ((:I "stream character")) :KIND ("Generic Function"))
      (:PAR) "Writes the character " (:GROUP (:FONT :FACE :I) "character") " to the " (:TERM "output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ", and returns " (:GROUP (:FONT :FACE :I) "character") " as its value."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-write-string")) :PARAMS
       ((:I "stream string " (:GROUP (:FONT :FACE :TT) "&optional ") "(start " (:CL "0") ") end")) :KIND
       ("Generic Function"))
      (:PAR) "Writes the string " (:GROUP (:FONT :FACE :I) "string") " to the " (:TERM "output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ". If " (:GROUP (:FONT :FACE :I) "start") " and "
      (:GROUP (:FONT :FACE :I) "end") " are supplied, they are integers that specify what part of "
      (:GROUP (:FONT :FACE :I) "string") " to output. " (:GROUP (:FONT :FACE :I) "string") " is returned as the value."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-terpri")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Writes an end of line character on the " (:TERM "output stream") " " (:GROUP (:FONT :FACE :I) "stream")
      ", and returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-fresh-line")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Writes an end of line character on the " (:TERM "output stream") " " (:GROUP (:FONT :FACE :I) "stream")
      " only if the stream is not at the beginning of the line." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-finish-output")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:PAR) "Ensures that all the output sent to the " (:TERM "output stream") " " (:GROUP (:FONT :FACE :I) "stream")
      " has reached its destination, and only then return " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-force-output")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Like " (:CL "stream-finish-output") ", except that it may immediately return " (:TERM "false")
      " without waiting for the output to complete." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-clear-output")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Aborts any outstanding output operation in progress on the " (:TERM "output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ", and returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-line-column")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "This function returns the column number where the next character will be written on the "
      (:TERM "output stream") " " (:GROUP (:FONT :FACE :I) "stream") ". The first column on a line is numbered 0."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-start-line-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:TERM "true") " if the " (:TERM "output stream") " " (:GROUP (:FONT :FACE :I) "stream")
      " is positioned at the beginning of a line (that is, column 0), otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-advance-to-column")) :PARAMS ((:I "stream column")) :KIND ("Generic Function"))
      (:PAR) "Writes enough blank space on the " (:TERM "output stream") " " (:GROUP (:FONT :FACE :I) "stream")
      " so that the next character will be written at the position specified by " (:GROUP (:FONT :FACE :I) "column")
      ", which is an integer." (:PAR) " "))
    (:SECTION :TITLE ("15.2 " "Extended Output Streams") :KIND :SECTION :NAME (6 7 10) (:PAR)
     "In addition to the basic output stream protocol, CLIM defines an extended output stream protocol. This protocol extends the stream model to maintain the state of a text cursor, margins, text styles, inter-line spacing, and so forth."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "extended-output-stream")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class for CLIM extended output streams. This is a subclass of " (:CL "output-stream")
      ". If you want to create a new class that behaves like an extended output stream, it should be a subclass of "
      (:CL "extended-output-stream") ". All instantiable subclasses of " (:CL "extended-output-stream")
      " must obey the extended output stream protocol. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "extended-output-stream-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a CLIM "
      (:TERM "extended output stream") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":foreground")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":background")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":text-style")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":vertical-spacing")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":text-margin")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":end-of-line-action")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":end-of-page-action")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":default-view")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "extended-output-stream")
      " must handle these initargs, which are used to specify, respectively, the medium foreground and background, default text style, vertical spacing, default text margin, end of line and end of page actions, and the default view for the stream."
      (:PAR) (:CL ":foreground") ", " (:CL ":background") ", and " (:CL ":text-style")
      " are handled via the usual pane initialize options (see Section " (:REF :NAME "pane-init") ")." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-extended-output-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "This class provides an implementation of the CLIM extended output stream protocol, based on the CLIM output kernel."
      (:PAR) "Members of this class are mutable. " (:PAR) " "))
    (:SECTION :TITLE ("15.3 " "The Text Cursor") :KIND :SECTION :NAME (6 7 10) (:PAR)
     "In the days when display devices displayed only two dimensional arrays of fixed width characters, the text cursor was a simple thing. A discrete position was selected in integer character units, and a character could go there and noplace else. Even for variable width fonts, simply addressing a character by the pixel position of one of its corners is sufficient. However, variable height fonts with variable baselines on pixel-addressable displays upset this simple model. The \"logical\" vertical reference point is the baseline, as it is in typesetting. In typesetting, however, an entire line of text is created with baselines aligned and padded to the maximum ascent and descent, then the entire line is put below the previous line."
     (:PAR)
     "It is clearly desirable to have the characters on a line aligned with their baselines, but when the line on the display is formed piece by piece, it is impossible to pick in advance the proper baseline. The solution CLIM adopts is to choose a baseline, but not commit to it."
     (:PAR) "The CLIM model says that text has at least 6 properties. With a reference point of "
     (:MATH "(" (:RM "0") "," (:RM "0") ")")
     " at the upper left of the text, it has a bounding box consisting of ascent, descent, left kerning, right extension, and a displacement to the next reference point in both "
     (:MATH "x") " and " (:MATH "y")
     ". CLIM determines the position of the reference point and draws the text relative to that, and then the cursor position is adjusted by the displacement. In this way, text has width and height, but the "
     (:MATH "x") " and " (:MATH "y") " displacements need not equal the width and height." (:PAR)
     "CLIM adopts the following approach to the actual rendering of a glyph. Textual output using the stream functions ("
     (:GROUP (:FONT :FACE :SL) "not")
     " the graphics functions) maintains text on a \"line\". Note that a line is not an output record, but is rather a collection of \"text so far\", a top (which is positioned at the bottom of the previous line plus the stream's vertical spacing), a baseline, a bottom, and a \"cursor position\". The cursor position is defined to be at the top of the line, not at the baseline. The reason for this is that the baseline can move, but the top is relative to the previous line, which has been completed and therefore doesn't move. If text is drawn on the current line whose ascent is greater than the current ascent of the line, then the line is moved down to make room. This can be done easily using the output records for the existing text on the line. When there is enough room, the reference point for the text is the "
     (:MATH "x") " position of the cursor at the baseline, and the cursor position is adjusted by the displacement."
     (:PAR)
     "The following figures show this in action before and after each of three characters are drawn. In all three figure, the small circle is the \"cursor position\". At first, there is nothing on the line. The first character establishes the initial baseline, and is then drawn. The upper left corner of the character is where the cursor was (as in the traditional model), but this will not remain the case. Drawing the second character, which is larger than the first, requires moving the first character down in order to get the baselines to align; during this time, the top of the line remains the same. Again, the upper left of the second character is where the cursor was, but that is no longer the case for the first character (which has moved down). The third character is smaller than the second, so no moving of characters needs to be done. However, the character is drawn to align the baselines, which in this case means the upper left is "
     (:GROUP (:FONT :FACE :SL) "not")
     " where the cursor was. Nor is the cursor at the upper right of the character as it was for the previous two characters. It is, however, at the upper right of the collective line."
     (:PAR)
     (:GROUP "     " (:PAR) "(50,60)(-4,0)  (0,30)"
      (:GROUP "  (10,30)(0,-20)  (0,0)" (:GROUP "(1,0)" (:GROUP "4")) "  (-2,2)" (:GROUP "(0,0)[r]" (:GROUP "(0,y)"))
       "  (-2,2)" (:GROUP "(1,-1)" (:GROUP "2")) "  (0,0)" (:GROUP (:GROUP ".5")) "    ")
      "  (10,30)"
      (:GROUP "  (10,30)(0,-20)  (0,0)" (:GROUP "(1,0)" (:GROUP "12")) "  (-2,2)" (:GROUP "(0,0)[r]" (:GROUP "(0,y)"))
       "  (-2,2)" (:GROUP "(1,-1)" (:GROUP "2")) "  (0,-12)" (:GROUP "(8,12)" (:GROUP "small")) "  (4,4)"
       (:GROUP "(0,0)[r]" (:GROUP "(w1,y)")) "  (4,4)" (:GROUP "(1,-1)" (:GROUP "4")) "  (8,0)" (:GROUP (:GROUP ".5"))
       "  (-2,-16)" (:GROUP "(0,0)[r]" (:GROUP "bl-small")) "  (-2,-16)" (:GROUP "(1,3)" (:GROUP "2")) "  (0,-10)"
       (:GROUP "(1,0)" (:GROUP "10")) "    ")
      "  (30,30)"
      (:GROUP "  (10,30)(0,-20)  (0,0)" (:GROUP "(1,0)" (:GROUP "22")) "  (-2,2)" (:GROUP "(0,0)[r]" (:GROUP "(0,y)"))
       "  (-2,2)" (:GROUP "(1,-1)" (:GROUP "2")) "  (0,-14)" (:GROUP "(8,12)" (:GROUP "small")) "  (4,4)"
       (:GROUP "(0,0)[r]" (:GROUP "(w1,y)")) "  (4,4)" (:GROUP "(1,-1)" (:GROUP "4")) "  (8,-16)"
       (:GROUP "(10,16)" (:GROUP "BIG")) "  (12,6)" (:GROUP "(0,0)[r]" (:GROUP "(w1+w2,y)")) "  (12,6)"
       (:GROUP "(1,-1)" (:GROUP "6")) "  (18,0)" (:GROUP (:GROUP ".5")) "  (-2,-18)"
       (:GROUP "(0,0)[r]" (:GROUP "bl-BIG")) "  (-2,-18)" (:GROUP "(1,3)" (:GROUP "2")) "  (0,-12)"
       (:GROUP "(1,0)" (:GROUP "20")) "    ")
      "  (10,0)"
      (:GROUP "  (10,30)(0,-20)  (0,0)" (:GROUP "(1,0)" (:GROUP "30")) "  (-2,2)" (:GROUP "(0,0)[r]" (:GROUP "(0,y)"))
       "  (-2,2)" (:GROUP "(1,-1)" (:GROUP "2")) "  (0,-14)" (:GROUP "(8,12)" (:GROUP "small")) "  (4,4)"
       (:GROUP "(0,0)[r]" (:GROUP "(w1,y)")) "  (4,4)" (:GROUP "(1,-1)" (:GROUP "4")) "  (8,-16)"
       (:GROUP "(10,16)" (:GROUP "BIG")) "  (12,6)" (:GROUP "(0,0)[r]" (:GROUP "(w1+w2,y)")) "  (12,6)"
       (:GROUP "(1,-1)" (:GROUP "6")) "  (18,-14)" (:GROUP "(8,12)" (:GROUP "small")) "  (18,8)"
       (:GROUP "(0,0)[r]" (:GROUP "(w1+w2+w3,y)")) "  (18,8)" (:GROUP "(1,-1)" (:GROUP "8")) "  (26,0)"
       (:GROUP (:GROUP ".5")) "  (-2,-18)" (:GROUP "(0,0)[r]" (:GROUP "bl-BIG")) "  (-2,-18)"
       (:GROUP "(1,3)" (:GROUP "2")) "  (0,-12)" (:GROUP "(1,0)" (:GROUP "28")) "    ")
      " " (:PAR))
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "The above may be too simplistic. The displacement probably wants to depend not only on language but language rendering mode. For example, Japanese can apparently go either vertically or horizontally. It may be necessary to have the bounding box and perhaps the reference point dispatch as well. Similarly, \"newline\" could mean \"down one line, all the way to the left\" for English, \"down one line, all the way to the right\" for Arabic, or \"to the left one line, all the way to the top.\" \"Home cursor\" is another ditty to consider. We need to discuss this on a larger scale with people who know multi-lingual rendering issues. --- DCPL")
     (:PAR) " "
     (:SECTION :TITLE ("15.3.1 " "Text Cursor Protocol") :KIND :SUBSECTION :NAME (2 6 7 10) (:PAR)
      "Many streams that maintain a text cursor display some visible indication of the text cursor. The object that represents this display is (somewhat confusingly) also called a cursor."
      (:PAR) "An " (:CONCEPT "active")
      " cursor is one that is being actively maintained by its owning sheet. A active cursor has a " (:CONCEPT "state")
      " that is either on or off. An active cursor can also has a state that indicates the the owning sheet has the input focus."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursor")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to cursors. If you want to create a new class that behaves like a cursor, it should be a subclass of "
       (:CL "cursor") ". All instantiable subclasses of " (:CL "cursor")
       " must obey the cursor protocol. Members of this class are mutable. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursorp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "cursor")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":sheet")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "The " (:CL ":sheet")
       " initarg is used to specify the sheet with which the cursor is associated." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-text-cursor")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a text cursor. Typically, ports will further specialize this class."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursor-sheet")) :PARAMS ((:I "cursor")) :KIND ("Generic Function")) (:PAR)
       "Returns the sheet with which the " (:TERM "cursor") " " (:GROUP (:FONT :FACE :I) "cursor") " is associated."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursor-position")) :PARAMS ((:I "cursor")) :KIND ("Generic Function")) (:PAR)
       "Returns the " (:MATH "x") " and " (:MATH "y") " position of the " (:TERM "cursor") " "
       (:GROUP (:FONT :FACE :I) "cursor") " as two values. " (:MATH "x") " and " (:MATH "y")
       " are in the coordinate system of the cursor's sheet." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf* cursor-position)")) :PARAMS ((:I "x y cursor")) :KIND ("Generic Function"))
       (:PAR) "Sets the " (:MATH "x") " and " (:MATH "y") " position of the " (:TERM "cursor") " "
       (:GROUP (:FONT :FACE :I) "cursor") " to the specified position. " (:MATH "x") " and " (:MATH "y")
       " are in the coordinate system of the cursor's sheet." (:PAR) "For CLIM implementations that do not support "
       (:CL "setf*") ", the \"setter\" function for this is " (:CL "cursor-set-position") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursor-active")) :PARAMS ((:I "cursor")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf cursor-active)")) :PARAMS ((:I "value cursor")) :KIND ("Generic Function"))
       (:PAR) "Returns (or sets) the \"active\" attribute of the cursor. When " (:TERM "true")
       ", the cursor is active." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursor-state")) :PARAMS ((:I "cursor")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf cursor-state)")) :PARAMS ((:I "value cursor")) :KIND ("Generic Function")) (:PAR)
       "Returns (or sets) the \"state\" attribute of the cursor. When " (:TERM "true") ", the cursor is visible. When "
       (:TERM "false") ", the cursor is not visible." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursor-focus")) :PARAMS ((:I "cursor")) :KIND ("Generic Function")) (:PAR)
       "Returns the \"focus\" attribute of the cursor. When " (:TERM "true")
       ", the sheet owning the cursor has the input focus." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cursor-visibility")) :PARAMS ((:I "cursor")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf cursor-visibility)")) :PARAMS ((:I "visibility cursor")) :KIND
        ("Generic Function"))
       (:PAR) "These are convenience functions that combine the functionality of " (:CL "cursor-active") " and "
       (:CL "cursor-state") ". The visibility can be either " (:CL ":on")
       " (meaning that the cursor is active and visible at its current position), " (:CL ":off")
       " (meaning that the cursor is active, but not visible at its current position), or " (:CL "nil")
       " (meaning that the cursor is not activate)." (:PAR) " "))
     (:SECTION :TITLE ("15.3.2 " "Stream Text Cursor Protocol") :KIND :SUBSECTION :NAME (2 6 7 10) (:PAR)
      "The following generic functions comprise the stream text cursor protocol. Any extended output stream class must implement methods for these generic functions."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-text-cursor")) :PARAMS ((:I "stream")) :KIND ("Generic Function")))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf stream-text-cursor)")) :PARAMS ((:I "cursor stream")) :KIND ("Generic Function"))
       (:PAR) "Returns (or sets) the text cursor object for the stream " (:GROUP (:FONT :FACE :I) "stream") "." (:PAR)
       " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-cursor-position")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "Returns the current text cursor position for the " (:TERM "extended output stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " as two integer values, the " (:MATH "x") " and " (:MATH "y") " positions."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf* stream-cursor-position)")) :PARAMS ((:I "x y stream")) :KIND
        ("Generic Function"))
       (:PAR) "Sets the text cursor position of the " (:TERM "extended output stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " to " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       ". " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       " are in device units, and must be integers." (:PAR) "For CLIM implementations that do not support "
       (:CL "setf*") ", the \"setter\" function for this is " (:CL "stream-set-cursor-position") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-increment-cursor-position")) :PARAMS ((:I "stream dx dy")) :KIND
        ("Generic Function"))
       (:PAR) "Moves the text cursor position of the " (:TERM "extended output stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " relatively, adding " (:GROUP (:FONT :FACE :I) "dx") " to the " (:MATH "x")
       " coordinate and " (:GROUP (:FONT :FACE :I) "dy") " to the " (:MATH "y") " coordinate. Either of "
       (:GROUP (:FONT :FACE :I) "dx") " or " (:GROUP (:FONT :FACE :I) "dy") " may be " (:CL "nil") ", meaning the the "
       (:MATH "x") " or " (:MATH "y") " cursor position will be unaffected. Otherwise, " (:GROUP (:FONT :FACE :I) "dx")
       " and " (:GROUP (:FONT :FACE :I) "dy") " must be integers." (:PAR) " ")))
    (:SECTION :TITLE ("15.4 " "Text Protocol") :KIND :SECTION :NAME (6 7 10) (:PAR)
     "The following generic functions comprise the text protocol. Any extended output stream class must implement methods for these generic functions."
     (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-character-width")) :PARAMS
       ((:I "stream character " (:GROUP (:FONT :FACE :TT) "&key ") "text-style")) :KIND ("Generic Function"))
      (:PAR)
      "Returns a rational number corresponding to the amount of horizontal motion of the cursor position that would occur if the character "
      (:GROUP (:FONT :FACE :I) "character") " were output to the " (:TERM "extended output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") " in the " (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style")
      " (which defaults to the current text style for the stream). This ignores the stream's text margin." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-string-width")) :PARAMS
       ((:I "stream character " (:GROUP (:FONT :FACE :TT) "&key ") "start end text-style")) :KIND ("Generic Function"))
      (:PAR) "Computes how the cursor position would move horizontally if the string "
      (:GROUP (:FONT :FACE :I) "string") " were output to the " (:TERM "extended output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") " in the " (:TERM "text style") " " (:GROUP (:FONT :FACE :I) "text-style")
      " (which defaults to the current text style for the stream) starting at the left margin. This ignores the stream's text margin."
      (:PAR) "The first returned value is the " (:MATH "x")
      " coordinate that the cursor position would move to. The second returned value is the maximum " (:MATH "x")
      " coordinate the cursor would visit during the output. (This is the same as the first value unless the string contains a "
      (:CODE "#\\Newline") " character.)" (:PAR) (:GROUP (:FONT :FACE :I) "start") " and "
      (:GROUP (:FONT :FACE :I) "end") " are integers, and default to 0 and the length of the string, respectively."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-text-margin")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf stream-text-margin)")) :PARAMS ((:I "margin stream")) :KIND ("Generic Function"))
      (:PAR) "The " (:MATH "x") " coordinate at which text wraps around on the " (:TERM "extended output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") " (see " (:CL "stream-end-of-line-action")
      "). The default setting is the width of the viewport, which is the right-hand edge of the viewport when it is horizontally scrolled to the \"initial position\"."
      (:PAR) "You can use " (:CL "setf") " with " (:CL "stream-text-margin") " to establish a new text margin. If "
      (:GROUP (:FONT :FACE :I) "margin") " is " (:CL "nil")
      ", then the width of the viewport will be used. If the width of the viewport is later changed, the text margin will change, too."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-line-height")) :PARAMS
       ((:I "stream " (:GROUP (:FONT :FACE :TT) "&key ") "text-style")) :KIND ("Generic Function"))
      (:PAR) "Returns what the line height of a line on the " (:TERM "extended output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") " containing text in the " (:TERM "text style") " "
      (:GROUP (:FONT :FACE :I) "text-style")
      " would be, as a rational number. The height of the line is measured from the baseline of the text style to its ascent. "
      (:GROUP (:FONT :FACE :I) "text-style") " defaults to the current text style for the stream." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-vertical-spacing")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:PAR) "Returns the current inter-line spacing (as a rational number) for the " (:TERM "extended output stream")
      " " (:GROUP (:FONT :FACE :I) "stream") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-baseline")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns the current text baseline (as a rational number) for the " (:TERM "extended output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") "." (:PAR) " ")
     (:SECTION :TITLE ("15.4.1 " "Mixing Text and Graphics") :KIND :SUBSECTION :NAME (2 6 7 10) (:PAR)
      "The following macro provides a convenient way to mix text and graphics on the same output stream." (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-room-for-graphics")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ")
          "(first-quadrant " (:CL "t") ") height (move-cursor " (:CL "t") ")  record-type)  "
          (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR)
       "Binds the dynamic environment to establish a local coordinate system for doing graphics output onto the "
       (:TERM "extended output stream") " designated by " (:GROUP (:FONT :FACE :I) "stream") ". If "
       (:GROUP (:FONT :FACE :I) "first-quadrant") " is " (:TERM "true")
       " (the default), a local Cartesian coordinate system is established with the origin "
       (:MATH "(" (:RM "0") "," (:RM "0") ")")
       " of the local coordinate system placed at the current cursor position; "
       (:MATH "(" (:RM "0") "," (:RM "0") ")") " is in the lower left corner of the area created. If the boolean "
       (:GROUP (:FONT :FACE :I) "move-cursor") " is " (:TERM "true")
       " (the default), then after the graphic output is completed, the cursor is positioned past (immediately below) this origin. The bottom of the vertical block allocated is at this location (that is, just below point "
       (:MATH "(" (:RM "0") "," (:RM "0") ")") ", not necessarily at the bottom of the output done)." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "stream")
       " argument is not evaluated, and must be a symbol that is bound to a stream. If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "height")
       " is supplied, it must be a rational number that specifies the amount of vertical space to allocate for the output, in device units. If it is not supplied, the height is computed from the output."
       (:PAR) (:GROUP (:FONT :FACE :I) "record-type")
       " specifies the class of output record to create to hold the graphical output. The default is "
       (:CL "standard-sequence-output-record") "." (:PAR) " "))
     (:SECTION :TITLE ("15.4.2 " "Wrapping of Text Lines") :KIND :SUBSECTION :NAME (2 6 7 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-end-of-line-action")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf stream-end-of-line-action)")) :PARAMS ((:I "action stream")) :KIND
        ("Generic Function"))
       (:PAR)
       "The end-of-line action controls what happens if the text cursor position moves horizontally out of the viewport, or if text output reaches the text margin. (By default the text margin is the width of the viewport, so these are usually the same thing.)"
       (:PAR) (:CL "stream-end-of-line-action") " returns the end-of-line action for the "
       (:TERM "extended output stream") " " (:GROUP (:FONT :FACE :I) "stream") ". It can be changed by using "
       (:CL "setf") " on " (:CL "stream-end-of-line-action") "." (:PAR) "The end-of-line action is one of:" (:PAR)
       (:UL
        (:LI (:CL ":wrap")
         "---when doing text output, wrap the text around (that is, break the text line and start another line). When setting the cursor position, scroll the window horizontally to keep the cursor position inside the viewport. This is the default."
         (:PAR))
        (:LI (:CL ":scroll")
         "---scroll the window horizontally to keep the cursor position inside the viewport, then keep doing the output."
         (:PAR))
        (:LI (:CL ":allow")
         "---ignore the text margin and do the output on the drawing plane beyond the visible part of the viewport. "))
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-end-of-line-action")) :PARAMS
        ((:I "(stream action) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Temporarily changes " (:GROUP (:FONT :FACE :I) "stream")
       "'s end-of-line action for the duration of execution of body. " (:GROUP (:FONT :FACE :I) "action")
       " must be one of the actions described in " (:CL "stream-end-of-line-action") "." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "stream")
       " argument is not evaluated, and must be a symbol that is bound to a stream. If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-end-of-page-action")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf stream-end-of-page-action)")) :PARAMS ((:I "action stream")) :KIND
        ("Generic Function"))
       (:PAR)
       "The end-of-page action controls what happens if the text cursor position moves vertically out of the viewport."
       (:PAR) (:CL "stream-end-of-page-action") " returns the end-of-page action for the "
       (:TERM "extended output stream") " " (:GROUP (:FONT :FACE :I) "stream") ". It can be changed by using "
       (:CL "setf") " on " (:CL "stream-end-of-page-action") "." (:PAR) "The end-of-page action is one of:" (:PAR)
       (:UL
        (:LI (:CL ":scroll")
         "---scroll the window vertically to keep the cursor position inside the viewport, then keep doing output. This is the default."
         (:PAR))
        (:LI (:CL ":allow")
         "---ignore the viewport and do the output on the drawing plane beyond the visible part of the viewport."
         (:PAR))
        (:LI (:CL ":wrap")
         "---when doing text output, wrap the text around (that is, go back to the top of the viewport). "))
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-end-of-page-action")) :PARAMS
        ((:I "(stream action) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Temporarily changes " (:GROUP (:FONT :FACE :I) "stream")
       "'s end-of-page action for the duration of execution of body. " (:GROUP (:FONT :FACE :I) "action")
       " must be one of the actions described in " (:CL "stream-end-of-page-action") "." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "stream")
       " argument is not evaluated, and must be a symbol that is bound to a stream. If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) " ")))
    (:SECTION :TITLE ("15.5 " "Attracting the User's Attention") :KIND :SECTION :NAME (6 7 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "beep")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "medium")) :KIND
       ("Generic Function"))
      (:PAR) "Attracts the user's attention, usually with an audible sound." (:PAR) " "))
    (:SECTION :TITLE ("15.6 " "Buffering of Output") :KIND :SECTION :NAME (6 7 10) (:PAR)
     "Some mediums that support the output protocol may buffer output. When buffering is enabled on a medium, the time at which output is actually done on the medium is unpredictable. "
     (:CL "force-output") " or " (:CL "finish-output")
     " can be used to ensure that all pending output gets completed. If the medium is a bidirectional stream, a "
     (:CL "force-output") " is performed whenever any sort of input is requested on the stream." (:PAR)
     (:CL "with-buffered-output")
     " provides a way to control when buffering is enabled on a medium. By default, CLIM's interactive streams are buffered if the underlying window system supports buffering."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "medium-buffering-output-p")) :PARAMS ((:I "medium")) :KIND ("Generic Function"))
      (:PAR) "Returns " (:TERM "true") " if the " (:TERM "medium") " " (:GROUP (:FONT :FACE :I) "medium")
      " is currently buffering output, otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf medium-buffering-output-p)")) :PARAMS ((:I "buffer-p medium")) :KIND
       ("Generic Function"))
      (:PAR) "Sets " (:CL "medium-buffering-output-p") " of the " (:TERM "medium") " "
      (:GROUP (:FONT :FACE :I) "medium") " to " (:GROUP (:FONT :FACE :I) "buffer-p") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-output-buffered")) :PARAMS
       ((:I "(medium " (:GROUP (:FONT :FACE :TT) "&optional ") "(buffer-p " (:CL "t") "))  "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "buffer-p") " is " (:TERM "true") " (the default), this causes the "
      (:TERM "medium") " designated by " (:GROUP (:FONT :FACE :I) "medium")
      " to start buffering output, and evaluates " (:GROUP (:FONT :FACE :I) "body") " in that context. If "
      (:GROUP (:FONT :FACE :I) "buffer-p") " is " (:TERM "false") ", " (:CL "force-output") " will be called before "
      (:GROUP (:FONT :FACE :I) "body") " is evaluated. When " (:GROUP (:FONT :FACE :I) "body")
      " is exited (or aborted from), " (:CL "force-output")
      " will be called if output buffering will be disabled after " (:CL "with-output-buffered") " is exited." (:PAR)
      "The " (:GROUP (:FONT :FACE :I) "medium")
      " argument is not evaluated, and must be a symbol that is bound to a medium. If "
      (:GROUP (:FONT :FACE :I) "medium") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))))
   " "
   (:SECTION :TITLE ("16 " "Output Recording") :KIND :CHAPTER :NAME (7 10) " " (:LABEL :NAME "output-recording") (:PAR)
    (:SECTION :TITLE ("16.1 " "Overview of Output Recording") :KIND :SECTION :NAME (4 7 10) (:PAR)
     "CLIM provides a mechanism whereby output (textual and graphical) may be captured into an "
     (:CONCEPT "output history")
     " for later replay on the same stream. This mechanism serves as the basis for many other tools, such as the formatted output and presentation mechanisms described elsewhere."
     (:PAR)
     "The output recording facility is layered on top of the graphics and text output protocols. It works by intercepting the operations in the graphics and text output protocols, and saving information about these operations in objects called "
     (:CONCEPT "output records")
     ". In general, an output record is a kind of display list, that is, a collection of instructions for drawing something on a stream. Some output records may have "
     (:CONCEPT "children")
     ", that is, a collection of inferior output records. Other output records, which are called "
     (:CONCEPT "displayed output records")
     ", correspond directly to displayed information on the stream, and do not have children. If you think of output records being arranged in a tree, displayed output records are all of the leaf nodes in the tree, for example, displayed text and graphics records."
     (:PAR)
     "Displayed output records must record the state of the supplied drawing options at the instant the output record is created, as follows. The ink supplied by the programmer must be captured without resolving indirect inks; this is so that a user can later change the default foreground and background ink of the medium and have that change affect the already-created output records during replay. The effect of the specified \"user\" transformation (composed with the medium transformation) must be captured; CLIM implementations are free to do this either by saving the transformation object or by saving the transformed values of all objects that are affected by the transformation. The user clipping region and line style must be captured in the output record as well. Subsequent replaying of the record under a new user transformation, clipping region, or line style will not affect the replayed output. CLIM implementation are permitted to capture the text style either fully merged against the medium's default, or not; in the former case, subsequent changes to the medium's default text style will not affect replaying the record, but in the latter case changing the default text style will affect replaying."
     (:PAR)
     "A CLIM stream that supports output recording has an output history object, which is a special kind of output record that supports some other operations. CLIM defines a standard set of output history implementations and a standard set of output record types."
     (:PAR)
     "The output recording mechanism is defined so as to permit application specific or host window system specific implementations of the various recording protocols. CLIM implementations should provide several types of standard output records with different characteristics for search, storage, and retrieval. Two examples are \"sequence\" output records (which store elements in a sequence, and whose insertion and retrieval complexity is O(n)) and \"tree\" output records (which store elements in some sort of tree based on the location of the element, and whose insertion and retrieval complexity is O(log n))."
     (:PAR) (:GROUP (:FONT :FACE :B) "Major issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "There is a proposal on the table to unify the sheet and output record protocols, not by unifying the class structure, but by making them implement the same generic functions where that makes sense. For instance, sheets and output records both have regions, transformations (that relate sheets to their parents), both support a repainting operation, and so forth."
      (:PAR) "In particular, " (:CL "sheet-parent") " and " (:CL "output-record-parent") " are equivalent, as are "
      (:CL "sheet-children") " and " (:CL "output-record-children") ", " (:CL "sheet-adopt-child") " and "
      (:CL "add-output-record") ", " (:CL "sheet-disown-child") " and " (:CL "delete-output-record") ", and "
      (:CL "repaint-sheet") " and " (:CL "replay-output-record") ", and the mapping functions. "
      (:CL "output-record-position") " and its " (:CL "setf")
      " function have sheet analogs. The sheet and output record notification functions are also equivalent." (:PAR)
      "This simplifies the conceptual framework of CLIM, and could eventually simplify the implementation as well. Doing this work now opens the door for later unifications, such unifying the pane layout functionality with table formatting. --- York, SWM")
     (:PAR) " ")
    (:SECTION :TITLE ("16.2 " "Output Records") :KIND :SECTION :NAME (4 7 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that is used to indicate that an object is an output record, that is, an object that contains other output records. This is a subclass of "
      (:CL "bounding-rectangle")
      ", and as such, output records obey the bounding rectangle protocol. If you want to create a new class that behaves like an output record, it should be a subclass of "
      (:CL "output-record") ". All instantiable subclasses of " (:CL "output-record")
      " must obey the output record protocol. " (:PAR) "All output records are mutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an " (:TERM "output record")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "displayed-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that is used to indicate that an object is a displayed output record, that is, an object that represents a visible piece of output on some output stream. This is a subclass of "
      (:CL "bounding-rectangle")
      ". If you want to create a new class that behaves like a displayed output record, it should be a subclass of "
      (:CL "displayed-output-record") ". All instantiable subclasses of " (:CL "displayed-output-record")
      " must obey the displayed output record protocol. " (:PAR) "All displayed output records are mutable." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "displayed-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a "
      (:TERM "displayed output record") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":x-position")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":y-position")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":parent")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of either "
      (:CL "output-record") " or " (:CL "displayed-output-record")
      " must handle these three initargs, which are used to specify, respectively, the " (:MATH "x") " and "
      (:MATH "y") " position of the output record, and the parent of the output record." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":size")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "output-record") " must handle the " (:CL ":size")
      " initarg. It is used to specify how much room should be left for child output records (if, for example, the children are stored in a vector). It is permissible for "
      (:CL ":size")
      " to be ignored, provided that the resulting output record is able to store the specified number of child output records."
      (:PAR) " ")
     (:SECTION :TITLE ("16.2.1 " "The Basic Output Record Protocol") :KIND :SUBSECTION :NAME (3 4 7 10) (:PAR)
      "All subclasses of " (:CL "output-record") " and " (:CL "displayed-output-record")
      " must inherit or implement methods for the following generic functions." (:PAR)
      "When the generic functions in this section take both " (:GROUP (:FONT :FACE :I) "record") " and a "
      (:GROUP (:FONT :FACE :I) "stream") " arguments, CLIM implementations will specialize the "
      (:GROUP (:FONT :FACE :I) "stream") " argument for the " (:CL "standard-output-recording-stream")
      " class and the " (:GROUP (:FONT :FACE :I) "record")
      " argument for all of the implementation-specific output record classes." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-position")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
       (:PAR) "Returns the " (:MATH "x") " and " (:MATH "y") " position of the " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "record")
       " as two rational numbers. The position of an output record is the position of the upper-left corner of its bounding rectangle. The position is relative to the stream, where "
       (:MATH "(" (:RM "0") "," (:RM "0") ")") " is (initially) the upper-left corner of the stream." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf* output-record-position)")) :PARAMS ((:I "x y record")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the " (:MATH "x") " and " (:MATH "y") " position of the " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "record") " to be " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       " (which are rational numbers), and updates the bounding rectangle to reflect the new position (and saved cursor positions, if the output record stores it). If "
       (:GROUP (:FONT :FACE :I) "record")
       " has any children, all of the children (and their descendants as well) will be moved by the same amount as "
       (:GROUP (:FONT :FACE :I) "record") " was moved. The bounding rectangles of all of "
       (:GROUP (:FONT :FACE :I) "record") "'s ancestors will also be updated to be large enough to contain "
       (:GROUP (:FONT :FACE :I) "record")
       ". This does not replay the output record, but the next time the output record is replayed it will appear at the new position."
       (:PAR) "For CLIM implementations that do not support " (:CL "setf*") ", the \"setter\" function for this is "
       (:CL "output-record-set-position") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "output-record-start-cursor-position")) :PARAMS ((:I "record")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the " (:MATH "x") " and " (:MATH "y") " starting cursor position of the "
       (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " as two integer values. The positions are relative to the stream, where "
       (:MATH "(" (:RM "0") "," (:RM "0") ")") " is (initially) the upper-left corner of the stream." (:PAR)
       "Text output records and updating output records maintain the cursor position. Graphical output records and other output records that do not require or affect the cursor position will return "
       (:CL "nil") " as both of the values." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf* output-record-start-cursor-position)")) :PARAMS ((:I "x y record")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the " (:MATH "x") " and " (:MATH "y") " starting cursor position of the "
       (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record") " to be " (:GROUP (:FONT :FACE :I) "x") " and "
       (:GROUP (:FONT :FACE :I) "y") " (which are integers). This does not affect the bounding rectangle of "
       (:GROUP (:FONT :FACE :I) "record")
       ", nor does it replay the output record. For those output records that do not require or affect the cursor position, the method for this function is a no-op."
       (:PAR) "For CLIM implementations that do not support " (:CL "setf*") ", the \"setter\" function for this is "
       (:CL "output-record-set-start-cursor-position") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "output-record-end-cursor-position")) :PARAMS ((:I "record")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the " (:MATH "x") " and " (:MATH "y") " ending cursor position of the " (:TERM "output record")
       " " (:GROUP (:FONT :FACE :I) "record")
       " as two integer values. The positions are relative to the stream, where "
       (:MATH "(" (:RM "0") "," (:RM "0") ")")
       " is (initially) the upper-left corner of the stream. Graphical output records do not track the cursor position, so only text output record (and some others) will return meaningful values for this."
       (:PAR)
       "Text output records and updating output records maintain the cursor position. Graphical output records and other output records that do not require or affect the cursor position will return "
       (:CL "nil") " as both of the values." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf* output-record-end-cursor-position)")) :PARAMS ((:I "x y record")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the " (:MATH "x") " and " (:MATH "y") " ending cursor position of the " (:TERM "output record")
       " " (:GROUP (:FONT :FACE :I) "record") " to be " (:GROUP (:FONT :FACE :I) "x") " and "
       (:GROUP (:FONT :FACE :I) "y") " (which are integers). This does not affect the bounding rectangle of "
       (:GROUP (:FONT :FACE :I) "record")
       ", nor does it replay the output record. For those output records that do not require or affect the cursor position, the method for this function is a no-op."
       (:PAR) "For CLIM implementations that do not support " (:CL "setf*") ", the \"setter\" function for this is "
       (:CL "output-record-set-end-cursor-position") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-parent")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
       (:PAR) "Returns the output record that is the parent of the " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "record") ", or " (:CL "nil") " if the record has no parent." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "replay")) :PARAMS
        ((:I "record stream " (:GROUP (:FONT :FACE :TT) "&optional ") "region")) :KIND ("Function"))
       (:PAR) "This function bind " (:CL "stream-recording-p") " of " (:GROUP (:FONT :FACE :I) "stream") " to "
       (:TERM "false") ", and then calls " (:CL "replay-output-record") " on the arguments "
       (:GROUP (:FONT :FACE :I) "record") ", " (:GROUP (:FONT :FACE :I) "stream") ", and "
       (:GROUP (:FONT :FACE :I) "region") ". If " (:CL "stream-drawing-p") " of " (:GROUP (:FONT :FACE :I) "stream")
       " is " (:TERM "false") ", " (:CL "replay") " does nothing. " (:CL "replay")
       " is typically called during scrolling, by repaint handlers, and so on." (:PAR)
       "CLIM implementations are permitted to default " (:GROUP (:FONT :FACE :I) "region") " either to " (:CL "nil")
       " or to the region corresponding to viewport of " (:GROUP (:FONT :FACE :I) "stream") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "replay-output-record")) :PARAMS
        ((:I "record stream " (:GROUP (:FONT :FACE :TT) "&optional ") "region x-offset y-offset")) :KIND
        ("Generic Function"))
       (:PAR) "Displays the output captured by the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " on the " (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
       ", exactly as it was originally captured (subject to subsequent modifications). The current user transformation, line style, text style, ink, and clipping region of "
       (:GROUP (:FONT :FACE :I) "stream")
       " are all ignored during the replay operation. Instead, these are gotten from the output record." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "record")
       " is not a displayed output record, then replaying it involves replaying all of its children. If "
       (:GROUP (:FONT :FACE :I) "record")
       " is a displayed output record, then replaying it involves redoing the graphics operation captured in the record."
       (:PAR) (:GROUP (:FONT :FACE :I) "region")
       " is a region that can be supplied to limit what records are displayed. Only those records that overlap "
       (:GROUP (:FONT :FACE :I) "region") " are replayed. The default for " (:GROUP (:FONT :FACE :I) "region") " is "
       (:CL "+everywhere+") "." (:PAR) "It is permissible for implementations to restrict "
       (:CL "replay-output-record") " such that " (:GROUP (:FONT :FACE :I) "stream")
       " must be the same stream on which the output records were originally recorded." (:PAR)
       (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL)
        "How does replaying a text output record (or any record that maintains the cursor position) affect the cursor position of the stream? It is probably that case that "
        (:CL "replay") " should not affect the cursor position. --- SWM")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "output-record-hit-detection-rectangle*")) :PARAMS ((:I "record")) :KIND
        ("Generic Function"))
       (:PAR) "This method is used to establish the usual \"effective size\" of " (:GROUP (:FONT :FACE :I) "record")
       " for hit detection queries. Four values are returned corresponding to the edges of the bounding rectangle that is the hit detection rectangle. The default method (on CLIM's standard output record class) is equivalent to calling calling "
       (:CL "bounding-rectangle*") " on " (:GROUP (:FONT :FACE :I) "record")
       ", but this method can be specialized to return a larger bounding rectangle in order to implement a form of hysteresis."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "output-record-refined-position-test")) :PARAMS ((:I "record x y")) :KIND
        ("Generic Function"))
       (:PAR) "This is used to definitively answer hit detection queries, that is, determining that the point "
       (:MATH "(x,y)") " is contained within the output record " (:GROUP (:FONT :FACE :I) "record")
       ". Once the position " (:MATH "(x,y)") " has been determined to lie within "
       (:CL "output-record-hit-detection-rectangle*") ", " (:CL "output-record-refined-sensitivity-test")
       " is invoked. Output record subclasses can provide a method that provides a more precise definition of a hit, for example, output records for elliptical rings will implement a method that detects whether the pointing device is on the elliptical ring."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "highlight-output-record")) :PARAMS ((:I "record stream state")) :KIND
        ("Generic Function"))
       (:PAR) "This method is called in order to draw a highlighting box around the " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "record") " on the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") ". " (:GROUP (:FONT :FACE :I) "state") " will be either " (:CL ":highlight")
       " (meaning to draw the highlighting) or " (:CL ":unhighlight")
       " (meaning to erase the highlighting). The default method (on CLIM's standard output record class) will simply draw a rectangle that corresponds the the bounding rectangle of "
       (:GROUP (:FONT :FACE :I) "record") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "displayed-output-record-ink")) :PARAMS ((:I "displayed-output-record")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the ink used by the " (:TERM "displayed output record") " "
       (:GROUP (:FONT :FACE :I) "displayed-output-record") "." (:PAR) " "))
     (:SECTION :TITLE ("16.2.2 " "The Output Record \"Database\" Protocol") :KIND :SUBSECTION :NAME (3 4 7 10) (:PAR)
      "All classes that are subclasses of " (:CL "output-record")
      " must implement methods for the following generic functions." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-children")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
       (:PAR) "Returns a sequence of all of the children of the " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "record")
       ". It is unspecified whether the sequence is a freshly created object or a \"live\" object representing the state of "
       (:GROUP (:FONT :FACE :I) "record") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "add-output-record")) :PARAMS ((:I "child record")) :KIND ("Generic Function"))
       (:PAR) "Adds the new " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "child") " to the "
       (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record") ". The bounding rectangle for "
       (:GROUP (:FONT :FACE :I) "record")
       " (and all its ancestors) must be updated to account for the new child record." (:PAR) "The methods for the "
       (:CL "add-output-record") " will typically specialize only the " (:GROUP (:FONT :FACE :I) "record") " argument."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "delete-output-record")) :PARAMS
        ((:I "child record " (:GROUP (:FONT :FACE :TT) "&optional ") "(errorp " (:CL "t") ")")) :KIND
        ("Generic Function"))
       (:PAR) "Removes the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "child") " from the "
       (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record") ". The bounding rectangle for "
       (:GROUP (:FONT :FACE :I) "record")
       " (and all its ancestors) may be updated to account for the child having been removed, although this is not mandatory."
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") " (the default) and "
       (:GROUP (:FONT :FACE :I) "child") " is not contained within " (:GROUP (:FONT :FACE :I) "record")
       ", then an error is signalled." (:PAR) "The methods for the " (:CL "delete-output-record")
       " will typically specialize only the " (:GROUP (:FONT :FACE :I) "record") " argument." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "clear-output-record")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
       (:PAR) "Removes all of the children from the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       ", and resets the bounding rectangle of " (:GROUP (:FONT :FACE :I) "record") " to its initial state." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-count")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
       (:PAR) "Returns the number of children contained within the " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "record") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-output-records-containing-position")) :PARAMS ((:I)) :KIND
        ("Generic Function"))
       (:GROUP "function record x y " (:GROUP (:FONT :FACE :TT) "&optional ") "x-offset y-offset "
        (:GROUP (:FONT :FACE :TT) "&rest ") "function-args")
       (:PAR) "Maps over all of the children of the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " that contain the point at " (:MATH "(x,y)") ", calling " (:GROUP (:FONT :FACE :I) "function") " on each one. "
       (:GROUP (:FONT :FACE :I) "function")
       " is a function of one or more arguments, the first argument being the record containing the point; it has dynamic extent. "
       (:GROUP (:FONT :FACE :I) "function") " is also called with all of " (:GROUP (:FONT :FACE :I) "function-args")
       " as \"apply\" arguments." (:PAR)
       "If there are multiple records that contain the point and that overlap each other, "
       (:CL "map-over-output-records-containing-position")
       " must hit the uppermost (most recently inserted) record first and the bottommost (least recently inserted) record last. Otherwise, the order in which the records are traversed is unspecified."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-output-records-overlapping-region")) :PARAMS ((:I)) :KIND
        ("Generic Function"))
       (:GROUP "function record region " (:GROUP (:FONT :FACE :TT) "&optional ") "x-offset y-offset "
        (:GROUP (:FONT :FACE :TT) "&rest ") "function-args")
       (:PAR) "Maps over all of the children of the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " that overlap the " (:TERM "region") " " (:GROUP (:FONT :FACE :I) "region") ", calling "
       (:GROUP (:FONT :FACE :I) "function") " on each one. " (:GROUP (:FONT :FACE :I) "function")
       " is a function of one or more arguments, the first argument being the record overlapping the region; it has dynamic extent. "
       (:GROUP (:FONT :FACE :I) "function") " is also called with all of " (:GROUP (:FONT :FACE :I) "function-args")
       " as \"apply\" arguments." (:PAR)
       "If there are multiple records that overlap the region and that overlap each other, "
       (:CL "map-over-output-records-overlapping-region")
       " must hit the bottommost (least recently inserted) record first and the uppermost (most recently inserted) record last. Otherwise, the order in which the records are traversed is unspecified."
       (:PAR) " "))
     (:SECTION :TITLE ("16.2.3 " "Output Record Change Notification Protocol") :KIND :SUBSECTION :NAME (3 4 7 10)
      (:PAR)
      "The following functions are called by programmers and by CLIM itself in order to notify a parent output record when the bounding rectangle of one of its child output record changes."
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "recompute-extent-for-new-child")) :PARAMS ((:I "record child")) :KIND
        ("Generic Function"))
       (:PAR)
       "This function is called whenever a new child is added to an output record. Its contract is to update the bounding rectangle of the "
       (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " to be large enough to completely contain the new child " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "child") ". The parent of " (:GROUP (:FONT :FACE :I) "record")
       " must be notified by calling " (:CL "recompute-extent-for-changed-child") "." (:PAR) (:CL "add-output-record")
       " is required to call " (:CL "recompute-extent-for-new-child") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "recompute-extent-for-changed-child")) :PARAMS
        ((:I "record child  old-min-x old-min-y old-max-x old-max-y")) :KIND ("Generic Function"))
       (:PAR)
       "This function is called whenever the bounding rectangle of one of the childs of a record has been changed. Its contract is to update the bounding rectangle of the "
       (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " to be large enough to completely contain the new bounding rectangle of the child " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "child") ". All of the ancestors of " (:GROUP (:FONT :FACE :I) "record")
       " must be notified by recursively calling " (:CL "recompute-extent-for-changed-child") "." (:PAR)
       "Whenever the bounding rectangle of an output record is changed or " (:CL "delete-output-record") " is called, "
       (:CL "recompute-extent-for-changed-child")
       " must be called to inform the parent of the record that a change has taken place." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "tree-recompute-extent")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
       (:PAR)
       "This function is called whenever the bounding rectangles of a number of children of a record have been changed, such as happens during table and graph formatting. Its contract is to compute the bounding rectangle large enough to contain all of the children of the output record "
       (:GROUP (:FONT :FACE :I) "record") ", adjust the bounding rectangle of the " (:TERM "output record") " "
       (:GROUP (:FONT :FACE :I) "record") " accordingly, and then call " (:CL "recompute-extent-for-changed-child")
       " on " (:GROUP (:FONT :FACE :I) "record") "." (:PAR) " ")))
    (:SECTION :TITLE ("16.3 " "Types of Output Records") :KIND :SECTION :NAME (4 7 10) (:PAR)
     "This section discusses several types of output records, including two standard classes of output records and the displayed output record protocol."
     (:PAR)
     (:SECTION :TITLE ("16.3.1 " "Standard Output Record Classes") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-sequence-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The standard instantiable class provided by CLIM to store a relatively short sequence of output records; a subclass of "
       (:CL "output-record")
       ". The insertion and retrieval complexity of this class is O(n). Most of the formatted output facilities (such as "
       (:CL "formatting-table") ") create output records that are a subclass of "
       (:CL "standard-sequence-output-record") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-tree-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The standard instantiable class provided by CLIM to store longer sequences of output records. Typically, the child records of a tree output record will be maintained in some sort of sorted order, such as a lexicographic ordering on the "
       (:MATH "x") " and " (:MATH "y")
       " coordinates of the children. The insertion and retrieval complexity of this class is O(log n)." (:PAR) " "))
     (:SECTION :TITLE ("16.3.2 " "Graphics Displayed Output Records") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR)
      "Graphics displayed output records are used to record the output produced by the graphics functions, such as "
      (:CL "draw-line*")
      ". Each graphics displayed output record describes the output produced by a call to one of the graphics functions."
      (:PAR)
      "The exact contents of graphics displayed output records is unspecified, but they must store sufficient information to be able to exactly redraw the original output at replay time. The minimum information that must be captured for all graphics displayed output records is as follows:"
      (:PAR)
      (:UL
       (:LI
        "The description of the graphical object itself, for example, the end points of a line or the center point and radius of a circle."
        (:PAR))
       (:LI
        "The programmer-supplied ink at the time the drawing function was called. Indirect inks must not be resolved, so that a user can later change the default foreground and background ink of the medium and have that change affect the already-created output records during replay."
        (:PAR))
       (:LI "For paths, the programmer-supplied line-style at the time the drawing function was called." (:PAR))
       (:LI "The programmer-supplied clipping region at the time the drawing function was called." (:PAR))
       (:LI
        "The user transformation. This may be accomplished by either explicitly storing the transformation, or by transforming the coordinates supplied to the drawing function and capturing the transformed coordinates. "))
      (:PAR) " "
      (:DEFUN (:SIGNATURE :NAME ((:CL "graphics-displayed-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class"))
       (:PAR) "The protocol class that corresponds to output records for the graphics functions, such as "
       (:CL "draw-line*") ". This is a subclass of " (:CL "displayed-output-record")
       ". If you want to create a new class that behaves like a graphics displayed output record, it should be a subclass of "
       (:CL "graphics-displayed-output-record") ". All instantiable subclasses of "
       (:CL "graphics-displayed-output-record") " must obey the graphics displayed output record protocol. " (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "graphics-displayed-output-record-p")) :PARAMS ((:I "object")) :KIND
        ("Protocol Predicate"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a "
       (:TERM "graphics displayed output record") ", otherwise returns " (:TERM "false") "." (:PAR) " "))
     (:SECTION :TITLE ("16.3.3 " "Text Displayed Output Record") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR)
      "Text displayed output records are used to record the textual output produced by such functions as "
      (:CL "stream-write-char") " and " (:CL "stream-write-string")
      ". Each text displayed output record corresponds to no more than one line of textual output (that is, line breaks caused by "
      (:CL "terpri") " and " (:CL "fresh-line")
      " create a new text output record, as do certain other stream operations described below)." (:PAR)
      "The exact contents of text displayed output records is unspecified, but they must store sufficient information to be able to exactly redraw the original output at replay time. The minimum information that must be captured for all text displayed output records is as follows:"
      (:PAR)
      (:UL (:LI "The displayed text strings." (:PAR)) (:LI "The starting and ending cursor positions." (:PAR))
       (:LI
        "The text style in which the text string was written. Depending on the CLIM implementation, this may be either fully merged against the medium's default or not; in the former case, subsequent changes to the medium's default text style will not affect replaying the record, but in the latter case changing the default text style will affect replaying."
        (:PAR))
       (:LI
        "The programmer-supplied ink at the time the drawing function was called. Indirect inks must not be resolved, so that a user can later change the default foreground and background ink of the medium and have that change affect the already-created output records during replay."
        (:PAR))
       (:LI "The programmer-supplied clipping region at the time the drawing function was called. "))
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "text-displayed-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that corresponds to text displayed output records. This is a subclass of "
       (:CL "displayed-output-record")
       ". If you want to create a new class that behaves like a text displayed output record, it should be a subclass of "
       (:CL "text-displayed-output-record") ". All instantiable subclasses of " (:CL "text-displayed-output-record")
       " must obey the text displayed output record protocol. " (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "text-displayed-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a "
       (:TERM "text displayed output record") ", otherwise returns " (:TERM "false") "." (:PAR)
       "The following two generic functions comprise the text displayed output record protocol." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "add-character-output-to-text-record")) :PARAMS
        ((:I "text-record character text-style  width height baseline")) :KIND ("Generic Function"))
       (:PAR) "Adds the character " (:GROUP (:FONT :FACE :I) "character") " to the "
       (:TERM "text displayed output record") " " (:GROUP (:FONT :FACE :I) "text-record") " in the text style "
       (:GROUP (:FONT :FACE :I) "text-style") ". " (:GROUP (:FONT :FACE :I) "width") " and "
       (:GROUP (:FONT :FACE :I) "height")
       " are the width and height of the character in device units, and are used to compute the bounding rectangle for the text record. "
       (:GROUP (:FONT :FACE :I) "baseline") " is the new baseline for characters in the output record." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "add-string-output-to-text-record")) :PARAMS
        ((:I "text-record string start end text-style  width height baseline")) :KIND ("Generic Function"))
       (:PAR) "Adds the string " (:GROUP (:FONT :FACE :I) "string") " to the " (:TERM "text displayed output record")
       " " (:GROUP (:FONT :FACE :I) "text-record") " in the text style " (:GROUP (:FONT :FACE :I) "text-style") ". "
       (:GROUP (:FONT :FACE :I) "start") " and " (:GROUP (:FONT :FACE :I) "end")
       " are integers that specify the substring within " (:GROUP (:FONT :FACE :I) "string")
       " to add to the text output record. " (:GROUP (:FONT :FACE :I) "width") " and "
       (:GROUP (:FONT :FACE :I) "height")
       " are the width and height of the character in device units, and are used to compute the bounding rectangle for the text record. "
       (:GROUP (:FONT :FACE :I) "baseline") " is the new baseline for characters in the output record." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "text-displayed-output-record-string")) :PARAMS ((:I "text-record")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the string contained by the " (:TERM "text displayed output record") " "
       (:GROUP (:FONT :FACE :I) "text-record")
       ". This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR) " "))
     (:SECTION :TITLE ("16.3.4 " "Top-Level Output Records") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR)
      "Top-level output records are similar to ordinary output records, except that they must maintain additional state, such as the information required to display scroll bars."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-output-history-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "This class is mixed into some other output record class to produce a new class that is suitable for use as a a top-level output history. This class is not intended to be instantiated."
       (:PAR)
       "When the bounding rectangle of an member of this class is updated, CLIM implementations must update any window decorations (such as scroll bars) associated with the stream with which the "
       (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "history") " is associated." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-tree-output-history")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The standard instantiable class provided by CLIM to use as the top-level output history. This will typically be a subclass of both "
       (:CL "standard-tree-output-record") " and " (:CL "stream-output-history-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-sequence-output-history")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "Another instantiable class provided by CLIM to use for top-level output records that have only a small number of children. This will typically be a subclass of both "
       (:CL "standard-sequence-output-record") " and " (:CL "stream-output-history-mixin") "." (:PAR) " ")))
    (:SECTION :TITLE ("16.4 " "Output Recording Streams") :KIND :SECTION :NAME (4 7 10) (:PAR)
     "CLIM defines an extension to the stream protocol that supports output recording. The stream has an associated output history record and provides controls to enable and disable output recording."
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "Do we want to support only output recording streams, or do we want to support output recording sheets as well? If the latter, we need to split apart graphics output recording and textual output recording, and rename lots of things. --- SWM")
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-recording-stream")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that indicates that a stream is an output recording stream. If you want to create a new class that behaves like an output recording stream, it should be a subclass of "
      (:CL "output-recording-stream") ". All instantiable subclasses of " (:CL "output-recording-stream")
      " must obey the output recording stream protocol. " (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "output-recording-stream-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an "
      (:TERM "output recording stream") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-output-recording-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The class used by CLIM to implement output record streams. This is a subclass of "
      (:CL "output-recording-stream") ". Members of this class are mutable. " (:PAR) " ")
     (:SECTION :TITLE ("16.4.1 " "The Output Recording Stream Protocol") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR)
      "The following generic functions comprise the output recording stream protocol. All subclasses of "
      (:CL "output-recording-stream") " must implement methods for these generic functions." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-recording-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
       "Returns " (:TERM "true") " when the " (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
       " is recording all output performed to it, otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf stream-recording-p)")) :PARAMS ((:I "recording-p stream")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the state of " (:CL "stream-recording-p") " to be " (:GROUP (:FONT :FACE :I) "recording-p")
       ", which must be either " (:CL "t") " or " (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-drawing-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
       "Returns " (:TERM "true") " when the " (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
       " will actually draw on the viewport when output is being performed to it, otherwise returns " (:TERM "false")
       "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf stream-drawing-p)")) :PARAMS ((:I "drawing-p stream")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the state of " (:CL "stream-recording-p") " to be " (:GROUP (:FONT :FACE :I) "drawing-p")
       ", which must be either " (:CL "t") " or " (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-output-history")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "Returns the history (or top-level output record) for the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-current-output-record")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "The current \"open\" output record for the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") ", the one to which " (:CL "stream-add-output-record")
       " will add a new child record. Initially, this is the same as " (:CL "stream-output-history")
       ". As nested output records are created, this acts as a \"stack\"." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf stream-current-output-record)")) :PARAMS ((:I "record stream")) :KIND
        ("Generic Function"))
       (:PAR) "Sets the current \"open\" output record for the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " to the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record") "."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-add-output-record")) :PARAMS ((:I "stream record")) :KIND ("Generic Function"))
       (:PAR) "Adds the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " to the current output record on the " (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
       " (that is, " (:CL "stream-current-output-record") ")." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-replay")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&optional ") "region")) :KIND ("Generic Function"))
       (:PAR) "Directs the " (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream") " to invoke "
       (:CL "replay") " on its output history. Only those records that overlap the " (:TERM "region") " "
       (:GROUP (:FONT :FACE :I) "region") " (which defaults to the viewport of the stream) are replayed." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "erase-output-record")) :PARAMS
        ((:I "record stream " (:GROUP (:FONT :FACE :TT) "&optional ") "(errorp " (:CL "t") ")")) :KIND
        ("Generic Function"))
       (:PAR) "Erases the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record") " from the "
       (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream") ", removes "
       (:GROUP (:FONT :FACE :I) "record") " from " (:GROUP (:FONT :FACE :I) "stream")
       "'s output history, and ensures that all other output records that were covered by "
       (:GROUP (:FONT :FACE :I) "record")
       " are visible. In effect, this draws background ink over the record, and then redraws all the records that overlap "
       (:GROUP (:FONT :FACE :I) "record") "." (:PAR) "If " (:GROUP (:FONT :FACE :I) "record")
       " is not in the stream's output history, then an error is signalled, unless " (:GROUP (:FONT :FACE :I) "errorp")
       " is " (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "copy-textual-output-history")) :PARAMS
        ((:I "window stream " (:GROUP (:FONT :FACE :TT) "&optional ") "region record")) :KIND ("Function"))
       (:PAR) "Given an " (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "window")
       " and a character output stream " (:GROUP (:FONT :FACE :I) "stream") ", " (:CL "copy-textual-output-history")
       " maps over all of the textual output records in the region " (:GROUP (:FONT :FACE :I) "region")
       " and writes them to " (:GROUP (:FONT :FACE :I) "stream")
       ", in order from the top of the output to the bottom of the output." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "record") " is supplied, it is the top-level record to map over. It defaults to "
       (:CL "stream-output-history") " of " (:GROUP (:FONT :FACE :I) "window") "." (:PAR) " "))
     (:SECTION :TITLE ("16.4.2 " "Graphics Output Recording") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR) "Using "
      (:CL "draw-line*") " as an example, calling any of the drawing functions specified in Section "
      (:REF :NAME "drawing-functions") " and Section " (:REF :NAME "graphics-protocols")
      " on an output recording stream results in the following series of function calls:" (:PAR)
      (:UL
       (:LI "A program calls " (:CL "draw-line*") " on arguments " (:GROUP (:FONT :FACE :I) "stream")
        " (and output recording stream), " (:GROUP (:FONT :FACE :I) "x1") ", " (:GROUP (:FONT :FACE :I) "y1") ", "
        (:GROUP (:FONT :FACE :I) "x2") ", and " (:GROUP (:FONT :FACE :I) "y2") ", and perhaps some drawing options."
        (:PAR))
       (:LI (:CL "draw-line*") " merges the supplied drawing options into the stream's medium, and then calls "
        (:CL "medium-draw-line*")
        " on the stream. (Note that a compiler macro could detect the case where there are no drawing options or constant drawing options, and do this at compile time.)"
        (:PAR))
       (:LI "The " (:CL ":around") " method for " (:CL "medium-draw-line*")
        " on the output recording stream is called. If " (:CL "stream-recording-p") " is " (:TERM "true")
        ", this creates an output record with all of the information necessary to replay the output record. If "
        (:CL "stream-drawing-p") " is " (:TERM "true") ", this then does a " (:CL "call-next-method")
        ". (Note that the " (:CL "call-next-method") " could be replaced by a call to the " (:CL "medium-draw-line*")
        " method on the stream's medium, avoiding the need for a trampolining function call.)" (:PAR))
       (:LI "An " (:CL ":around") " method for " (:CL "medium-draw-line*")
        " performs the necessary user transformations by applying the medium transformation to "
        (:GROUP (:FONT :FACE :I) "x1") ", " (:GROUP (:FONT :FACE :I) "y1") ", " (:GROUP (:FONT :FACE :I) "x2") ", and "
        (:GROUP (:FONT :FACE :I) "y2") ", and to the clipping region, and then calls the medium-specific method."
        (:PAR))
       (:LI "The \"real\" " (:CL "medium-draw-line*")
        " transforms the start and end coordinates of the line by the stream's device transformation, decodes the ink and line style into port-specific objects, and finally invokes a port-specific function (such as "
        (:CL "xlib:draw-line") ") to do the actual drawing. "))
      (:PAR) (:CL "replay-output-record")
      " for a graphics displayed output record simply binds the state of the medium to the state captured in the output record, and calls the medium drawing function (such as "
      (:CL "medium-draw-line*") ") directly on the medium, with " (:CL "stream-recording-p") " of the stream set to "
      (:TERM "false") " and " (:CL "stream-drawing-p") " set to " (:TERM "true") "." (:PAR) " ")
     (:SECTION :TITLE ("16.4.3 " "Text Output Recording") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR)
      (:GROUP (:FONT :FACE :B) "Major issue: ") " "
      (:GROUP (:FONT :FACE :SL) "This is the place where " (:CL "write-string")
       " and friends get captured in order to create output record. The generic functions include things like "
       (:CL "stream-write-string")
       ", which are specialized by output recording streams to do the output recording. Describe exactly what happens. --- SWM")
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-text-output-record")) :PARAMS ((:I "stream text-style")) :KIND
        ("Generic Function"))
       (:PAR) "Returns a text output record for the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " suitable for holding characters in the text style "
       (:GROUP (:FONT :FACE :I) "text-style")
       ". If there is a currently \"open\" text output record that can hold characters in the specified text style, it is simply returned. Otherwise a new text output record is created that can hold characters in that text style, and its starting cursor position set to the cursor position of "
       (:GROUP (:FONT :FACE :I) "stream") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-close-text-output-record")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "Closes the " (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
       "'s currently \"open\" text output record by recording the stream's current cursor position as the ending cursor position of the record and adding the text output record to "
       (:GROUP (:FONT :FACE :I) "stream") "'s current output record by calling " (:CL "stream-add-output-record") "."
       (:PAR) "If there is no \"open\" text output record, " (:CL "stream-close-text-output-record") " does nothing."
       (:PAR) "Calling " (:CL "stream-finish-output") " or " (:CL "stream-force-output") ", calling " (:CL "redisplay")
       ", setting the text cursor position (via " (:CL "stream-set-cursor-position") ", " (:CL "terpri") ", or "
       (:CL "fresh-line") "), creating a new output record (for example, via " (:CL "with-new-output-record")
       "), or changing the state of " (:CL "stream-recording-p")
       " must close the current text output record. Some CLIM implementations may also choose to close the current text output record when the stream's drawing options or text style are changed, depending on the exact implementation of text output records."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-add-character-output")) :PARAMS
        ((:I "stream character text-style  width height baseline")) :KIND ("Generic Function"))
       (:PAR) "Adds the character " (:GROUP (:FONT :FACE :I) "character") " to the " (:TERM "output recording stream")
       " " (:GROUP (:FONT :FACE :I) "stream") "'s text output record in the " (:TERM "text style") " "
       (:GROUP (:FONT :FACE :I) "text-style") ". " (:GROUP (:FONT :FACE :I) "width") " and "
       (:GROUP (:FONT :FACE :I) "height") " are the width and height of the character in device units. "
       (:GROUP (:FONT :FACE :I) "baseline") " is the new baseline for the stream. " (:CL "stream-add-character-output")
       " must be implemented by calling " (:CL "add-character-output-to-text-record") "." (:PAR)
       (:CL "stream-write-char") " on an output recording stream will call " (:CL "stream-add-character-output")
       " when " (:CL "stream-recording-p") " is " (:TERM "true") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-add-string-output")) :PARAMS
        ((:I "stream string start end text-style  width height baseline")) :KIND ("Generic Function"))
       (:PAR) "Adds the string " (:GROUP (:FONT :FACE :I) "string") " to the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") "'s text output record in the " (:TERM "text style") " "
       (:GROUP (:FONT :FACE :I) "text-style") ". " (:GROUP (:FONT :FACE :I) "start") " and "
       (:GROUP (:FONT :FACE :I) "end") " are integers that specify the substring within "
       (:GROUP (:FONT :FACE :I) "string") " to add to the text output record. " (:GROUP (:FONT :FACE :I) "width")
       " and " (:GROUP (:FONT :FACE :I) "height") " are the width and height of the string in device units. "
       (:GROUP (:FONT :FACE :I) "baseline") " is the new baseline for the stream. " (:CL "stream-add-string-output")
       " must be implemented by calling " (:CL "add-string-output-to-text-record") "." (:PAR)
       (:CL "stream-write-string") " on an output recording stream will call " (:CL "stream-add-string-output")
       " when " (:CL "stream-recording-p") " is " (:TERM "true") "." (:PAR) " "))
     (:SECTION :TITLE ("16.4.4 " "Output Recording Utilities") :KIND :SUBSECTION :NAME (4 4 7 10) (:PAR)
      "CLIM provides several helper macros to control the output recording facility." (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-output-recording-options")) :PARAMS
        ((:I "(stream " (:GROUP (:FONT :FACE :TT) "&key ") "record draw) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "Enables or disables output recording and/or drawing on the " (:TERM "output recording stream")
       " designated by " (:GROUP (:FONT :FACE :I) "stream") ", within the extent of " (:GROUP (:FONT :FACE :I) "body")
       "." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
       " argument is not evaluated, and must be a symbol that is bound to an output recording stream. If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
       (:CL "with-output-recording-options") " must be implemented by expanding into a call to "
       (:CL "invoke-with-output-recording-options") ", supplying a function that executes "
       (:GROUP (:FONT :FACE :I) "body") " as the " (:GROUP (:FONT :FACE :I) "continuation") " argument to "
       (:CL "invoke-with-output-recording-options") ". The exact behavior of this macro is described under "
       (:CL "invoke-with-output-recording-options") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "invoke-with-output-recording-options")) :PARAMS
        ((:I "stream continuation record draw")) :KIND ("Generic Function"))
       (:PAR) "Enables or disables output recording and/or drawing on the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") ", and calls the function " (:GROUP (:FONT :FACE :I) "continuation")
       " with the new output recording options in effect. " (:GROUP (:FONT :FACE :I) "continuation")
       " is a function of one argument, the stream; it has dynamic extent." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "draw") " is " (:TERM "false")
       ", output to the stream is not drawn on the viewport, but recording proceeds according to "
       (:GROUP (:FONT :FACE :I) "record") "; if " (:GROUP (:FONT :FACE :I) "draw") " is " (:TERM "true")
       ", the output is drawn. If " (:GROUP (:FONT :FACE :I) "record") " is " (:CL "nil")
       ", output recording is disabled, but output otherwise proceeds according to " (:GROUP (:FONT :FACE :I) "draw")
       "; if " (:GROUP (:FONT :FACE :I) "draw") " is " (:TERM "true") ", output recording is enabled." (:PAR)
       "All output recording streams must implement a method for " (:CL "invoke-with-output-recording-options") "."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-new-output-record")) :PARAMS
        ((:I "(stream " (:GROUP (:FONT :FACE :TT) "&optional ") "record-type record  "
          (:GROUP (:FONT :FACE :TT) "&rest ") "initargs)  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "Creates a new output record of type " (:GROUP (:FONT :FACE :I) "record-type") " (which defaults to "
       (:CL "standard-sequence-output-record") ") and then captures the output of " (:GROUP (:FONT :FACE :I) "body")
       " into the new output record, and inserts the new record into the current \"open\" output record associated with the "
       (:TERM "output recording stream") " designated by " (:GROUP (:FONT :FACE :I) "stream") ". While "
       (:GROUP (:FONT :FACE :I) "body") " is being evaluated, the current output record for "
       (:GROUP (:FONT :FACE :I) "stream") " will be bound to the new output record." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "record")
       " is supplied, it is the name of a variable that will be lexically bound to the new output record inside of body. "
       (:GROUP (:FONT :FACE :I) "initargs") " are CLOS initargs that are passed to " (:CL "make-instance")
       " when the new output record is created." (:PAR) (:CL "with-new-output-record")
       " returns the output record it creates." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
       " argument is not evaluated, and must be a symbol that is bound to an output recording stream. If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
       (:CL "with-new-output-record") " must be implemented by expanding into a call to "
       (:CL "invoke-with-new-output-record") " supplying a function that executes " (:GROUP (:FONT :FACE :I) "body")
       " as the " (:GROUP (:FONT :FACE :I) "continuation") " argument to " (:CL "invoke-with-new-output-record")
       ". The exact behavior of this macro is described under " (:CL "invoke-with-new-output-record") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "invoke-with-new-output-record")) :PARAMS
        ((:I "stream continuation record-type  " (:GROUP (:FONT :FACE :TT) "&rest ") "initargs "
          (:GROUP (:FONT :FACE :TT) "&key ") "parent " (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
        :KIND ("Generic Function"))
       (:PAR) "Creates a new output record of type " (:GROUP (:FONT :FACE :I) "record-type") ". The function "
       (:GROUP (:FONT :FACE :I) "continuation") " is then called, and any output it does to the "
       (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
       " is captured in the new output record. The new record is then inserted into the current \"open\" output record associated with "
       (:GROUP (:FONT :FACE :I) "stream")
       " (or the top-level output record if there is no currently \"open\" one). While "
       (:GROUP (:FONT :FACE :I) "continuation") " is being executed, the current output record for "
       (:GROUP (:FONT :FACE :I) "stream") " will be bound to the new output record." (:PAR)
       (:GROUP (:FONT :FACE :I) "continuation")
       " is a function of two arguments, the stream and the output record; it has dynamic extent." (:PAR)
       (:GROUP (:FONT :FACE :I) "initargs") " are CLOS initargs that are passed to " (:CL "make-instance")
       " when the new output record is created. The " (:GROUP (:FONT :FACE :I) "parent")
       " initarg is handled specially, and specifies what output record should serve as the parent for the newly created record. If unspecified, "
       (:CL "stream-current-output-record") " of " (:GROUP (:FONT :FACE :I) "stream") " will be used as the parent."
       (:PAR) (:CL "invoke-with-new-output-record") " returns the output record it creates." (:PAR)
       "All output recording streams must implement a method for " (:CL "invoke-with-new-output-record") "." (:PAR)
       " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-output-to-output-record")) :PARAMS
        ((:I "(stream " (:GROUP (:FONT :FACE :TT) "&optional ") "record-type record  "
          (:GROUP (:FONT :FACE :TT) "&rest ") "initargs))  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "This is identical to " (:CL "with-new-output-record")
       " except that the new output record is not inserted into the output record hierarchy, and the text cursor position of "
       (:GROUP (:FONT :FACE :I) "stream") " is initially bound to " (:MATH "(" (:RM "0") "," (:RM "0") ")") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "record-type") " is the type of output record to create, which defaults to "
       (:CL "standard-sequence-output-record") ". " (:GROUP (:FONT :FACE :I) "initargs")
       " are CLOS initargs that are passed to " (:CL "make-instance") " when the new output record is created." (:PAR)
       "If " (:GROUP (:FONT :FACE :I) "record")
       " is supplied, it is a variable that will be bound to the new output record while body is evaluated." (:PAR)
       (:CL "with-output-to-output-record") " returns the output record it creates." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "stream")
       " argument is not evaluated, and must be a symbol that is bound to an output recording stream. If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*")
       " is used. Unlike facilities such as " (:CL "with-output-to-string") ", " (:GROUP (:FONT :FACE :I) "stream")
       " must be an actual stream, but no output will be done to it. " (:GROUP (:FONT :FACE :I) "body")
       " may have zero or more declarations as its first forms." (:PAR) (:CL "with-output-to-output-record")
       " must be implemented by expanding into a call to " (:CL "invoke-with-output-to-output-record")
       " supplying a function that executes " (:GROUP (:FONT :FACE :I) "body") " as the "
       (:GROUP (:FONT :FACE :I) "continuation") " argument to " (:CL "invoke-with-output-to-output-record")
       ". The exact behavior of this macro is described under " (:CL "invoke-with-output-to-output-record") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "invoke-with-output-to-output-record")) :PARAMS
        ((:I "stream continuation record-type  " (:GROUP (:FONT :FACE :TT) "&rest ") "initargs "
          (:GROUP (:FONT :FACE :TT) "&key ")))
        :KIND ("Generic Function"))
       (:PAR) "This is similar to " (:CL "invoke-with-new-output-record")
       " except that the new output record is not inserted into the output record hierarchy, and the text cursor position of "
       (:GROUP (:FONT :FACE :I) "stream") " is initially bound to " (:MATH "(" (:RM "0") "," (:RM "0") ")")
       ". That is, when " (:CL "invoke-with-output-to-output-record")
       " is used, no drawing on the stream occurs and nothing is put into the stream's normal output history. The function "
       (:GROUP (:FONT :FACE :I) "continuation") " is called, and any output it does to "
       (:GROUP (:FONT :FACE :I) "stream") " is captured in the output record." (:PAR)
       (:GROUP (:FONT :FACE :I) "continuation")
       " is a function of two arguments, the stream and the output record; it has dynamic extent. "
       (:GROUP (:FONT :FACE :I) "record-type") " is the type of output record to create. "
       (:GROUP (:FONT :FACE :I) "initargs") " are CLOS initargs that are passed to " (:CL "make-instance")
       " when the new output record is created." (:PAR) (:CL "invoke-with-output-to-output-record")
       " returns the output record it creates." (:PAR) "All output recording streams must implement a method for "
       (:CL "invoke-with-output-to-output-record") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-design-from-output-record")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
       (:PAR) "Makes a design that replays the " (:TERM "output record") " " (:GROUP (:FONT :FACE :I) "record")
       " when drawn via " (:CL "draw-design") ". If " (:GROUP (:FONT :FACE :I) "record")
       " is changed after the design is made, the consequences are unspecified. Applying a transformation to the design and calling "
       (:CL "draw-design")
       " on the new design is equivalent to establishing the same transformation before creating the output record."
       (:PAR)
       "It is permissible for implementations to support this only for those output records that correspond to the geometric object classes (for example, the output records created by "
       (:CL "draw-line*") " and " (:CL "draw-ellipse*") ")." (:PAR)))))
   " "
   (:SECTION :TITLE ("17 " "Table Formatting") :KIND :CHAPTER :NAME (7 10) " " (:LABEL :NAME "table-formatting") (:PAR)
    "CLIM provides a mechanism for tabular formatting of arbitrary output." (:PAR)
    "To employ these facilities the programmer annotates some output-generating code with advisory macros that describe the high-level formatting constraints, for example, what parts of code produce a row of the table, what parts of that produce the cells in the row."
    (:PAR)
    "For example, the following produces a table consisting of three columns containing a number, its square, and its cube. The output can be seen in Figure "
    (:REF :NAME "table-example") "." (:PAR)
    (:PRE "
(defun table-test (count stream)
  (fresh-line stream)
  (formatting-table (stream :x-spacing '(3 :character))
    (dotimes (i count)
      (formatting-row (stream)
        (formatting-cell (stream :align-x :right)
          (prin1 i stream))
        (formatting-cell (stream :align-x :right)
          (prin1 (* i i) stream))
        (formatting-cell (stream :align-x :right)
          (prin1 (* i i i) stream))))))
")
    (:PAR)
    (:FIGURE :NUMBER "17.1" :CAPTION ((:LABEL :NAME "table-example") " Example of tabular output.") " "
     (:CENTER (:IMG :SRC "table-example.png")) "  ")
    (:PAR) "The general contract of these facilities is described in the next section." (:PAR) " "
    (:SECTION :TITLE ("17.1 " "Overview of Table Formatting Facilities") :KIND :SECTION :NAME (3 7 10) (:PAR)
     "In general, table formatting involves a sharing of responsibilities between user-written code and CLIM code. Code that employs only the lower level output facilities has full control over \"where every piece of ink goes\" in the output. In contrast, code that employs CLIM's table formatting facilities passes control to CLIM at a higher level. The programmer benefits by being able to specify the appearance of output in more compact abstract terms, and by not having to write the code that constrains the output to appear in proper tabular form."
     (:PAR)
     "Tabular output consists of a rectangular array of pieces of output corresponding to the bounding rectangles of the output. Each piece of output forms the contents of a "
     (:CONCEPT "table cell")
     ". There is no restriction on the contents of a table cell; cells may contain text, graphics, even other tables. For purposes of this discussion, we draw a strong distinction between specifying what goes in a cell, and specifying how the cells are arranged to form a table."
     (:PAR)
     "Specifying the contents of a cell is the responsibility of the programmer. A programmer using the table formatting facilities can predict the appearance of any individual cell by simply looking at the code for that cell. A cell's appearance does not depend upon where in the table it lies, for instance. The only thing about a cell's appearance that cannot be predicted from that cell alone is the amount of space the table formatting has to introduce in order to perform the desired alignment."
     (:PAR)
     "Specifying the relative arrangements of cells to form a table is the responsibility of CLIM based on the advice of the programmer. The programmer advises CLIM about extra space to put between rows or columns, for instance, but does not directly control the absolute positioning of a cell's contents."
     (:PAR) "For purposes of understanding table formatting, the following model may be used. "
     (:UL
      (:LI "The code for a cell draws to a stream that has a \"private\" (local to that cell) drawing plane." (:PAR))
      (:LI
       "After output for a cell has finished, the bounding rectangle of all output on the \"private\" drawing plane is found. The region within that bounding rectangle forms the contents of a cell."
       (:PAR))
      (:LI
       "Additional rectangular regions, containing only background ink, are attached to the edges of the cell contents. These regions ensure that the cells satisfy the tabular constraints that within a row all cells have the same height, and within a column all cells have the same width. CLIM may also introduce additional background for other purposes as described below."
       (:PAR))
      (:LI "The cells are assembled into rows and columns. "))
     (:PAR)
     "Some tables are \"multiple column\" tables, in which two or more rows of the table are placed side by side (usually with intervening spacing) rather than all rows being aligned vertically. Multiple column tables are generally used to produce a table that is more esthetically pleasing, or to make more efficient use of space on the output device. When a table is a multiple column table, one additional step takes place in the formatting of the table: the rows of the table are rearranged into multiple columns in which some rows are placed side by side."
     (:PAR) "The advice that the programmer gives to CLIM on how to assemble the table consists of the following: "
     (:UL
      (:LI
       "How to place the contents of the cell within the cell (such as centered vertically, flush-left, and so forth) The possibilities for this advice are described below."
       (:PAR))
      (:LI "Optionally, how much additional space to insert between columns and between rows of the table." (:PAR))
      (:LI "Optionally, whether to make all columns the same size. "))
     (:PAR)
     "The advice describing how to place the contents of the cell within the cell consists of two pieces---how to constrain the cell contents in the horizontal direction, and how to constrain them in the vertical direction."
     (:PAR))
    (:SECTION :TITLE ("17.2 " "Table Formatting Functions") :KIND :SECTION :NAME (3 7 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "formatting-table")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "x-spacing y-spacing  multiple-columns multiple-columns-x-spacing  equalize-column-widths  (move-cursor "
         (:CL "t") ") record-type " (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ")  "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Binds the local environment in such a way the output of " (:GROUP (:FONT :FACE :I) "body")
      " will be done in a tabular format. This must be used in conjunction with " (:CL "formatting-row") " or "
      (:CL "formatting-column") ", and " (:CL "formatting-cell")
      ". The table is placed so that its upper left corner is at the current text cursor position of "
      (:GROUP (:FONT :FACE :I) "stream") ". If the boolean " (:GROUP (:FONT :FACE :I) "move-cursor") " is "
      (:TERM "true")
      " (the default), then the text cursor will be moved so that it immediately follows the last cell of the table."
      (:PAR) "The returned value is the output record corresponding to the table." (:PAR)
      (:GROUP (:FONT :FACE :I) "stream") " is an output recording stream to which output will be done. The "
      (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "x-spacing")
      " specifies the number of units of spacing to be inserted between columns of the table; the default is the width of a space character in the current text style. "
      (:GROUP (:FONT :FACE :I) "y-spacing")
      " specifies the number of units of spacing to be inserted between rows in the table; the default is the default vertical spacing of the stream. Possible values for these two options option are:"
      (:PAR)
      (:UL (:LI "An integer---a size in the current units to be used for spacing." (:PAR))
       (:LI
        "A string or character---the spacing is the width or height of the string or character in the current text style."
        (:PAR))
       (:LI
        "A function---the spacing is the amount of horizontal or vertical space the function would consume when called on the stream."
        (:PAR))
       (:LI "A list---the list is of the form "
        (:CL "(" (:GROUP (:FONT :FACE :I) "number") " " (:GROUP (:FONT :FACE :I) "unit") ")") ", where "
        (:GROUP (:FONT :FACE :I) "unit") " is one of " (:CL ":point") ", " (:CL ":pixel") ", " (:CL ":mm") ", "
        (:CL ":character") ", or " (:CL ":line") ". When " (:GROUP (:FONT :FACE :I) "unit") " is " (:CL ":character")
        ", the width of an \"M\" in the current text style is used as the width of one character. "))
      (:PAR) (:GROUP (:FONT :FACE :I) "multiple-columns") " is either " (:CL "nil") ", " (:CL "t")
      ", or an integer. If it is " (:CL "t")
      " or an integer, the table rows will be broken up into a multiple columns. If it is " (:CL "t")
      ", CLIM will determine the optimal number of columns. If it is an integer, it will be interpreted as the desired number of columns. "
      (:GROUP (:FONT :FACE :I) "multiple-columns-x-spacing") " has the same format as "
      (:GROUP (:FONT :FACE :I) "x-spacing")
      ". It controls the spacing between the multiple columns. It defaults to the value of the "
      (:GROUP (:FONT :FACE :I) "x-spacing") " option." (:PAR) "When the boolean "
      (:GROUP (:FONT :FACE :I) "equalize-column-widths") " is " (:TERM "true")
      ", CLIM will make all of the columns have the same width (the width of the widest cell in any column in the entire table)."
      (:PAR) (:GROUP (:FONT :FACE :I) "record-type") " specifies the class of output record to create. The default is "
      (:CL "standard-table-output-record")
      ". This argument should only be supplied by a programmer if there is a new class of output record that supports the table formatting protocol."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "formatting-row")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream " (:GROUP (:FONT :FACE :TT) "&key ") "record-type "
         (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ")  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Binds the local environment in such a way the output of " (:GROUP (:FONT :FACE :I) "body")
      " will be grouped into a table row. All of the output performed by " (:GROUP (:FONT :FACE :I) "body")
      " becomes the contents of one row. This must be used inside of " (:CL "formatting-table")
      ", and in conjunction with " (:CL "formatting-cell") "." (:PAR) (:GROUP (:FONT :FACE :I) "stream")
      " is an output recording stream to which output will be done. The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      "Once a table has had a row added to it via " (:CL "formatting-row") ", no columns may be added to it." (:PAR)
      (:GROUP (:FONT :FACE :I) "record-type") " specifies the class of output record to create. The default is "
      (:CL "standard-row-output-record")
      ". This argument should only be supplied by a programmer if there is a new class of output record that supports the row formatting protocol."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "formatting-column")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream " (:GROUP (:FONT :FACE :TT) "&key ") "record-type "
         (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ")  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Binds the local environment in such a way the output of " (:GROUP (:FONT :FACE :I) "body")
      " will be grouped into a table column. All of the output performed by " (:GROUP (:FONT :FACE :I) "body")
      " becomes the contents of one column. This must be used inside of " (:CL "formatting-table")
      ", and in conjunction with " (:CL "formatting-cell") "." (:PAR) (:GROUP (:FONT :FACE :I) "stream")
      " is an output recording stream to which output will be done. The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      "Once a table has had a column added to it via " (:CL "formatting-column") ", no rows may be added to it." (:PAR)
      (:GROUP (:FONT :FACE :I) "record-type") " specifies the class of output record to create. The default is "
      (:CL "standard-column-output-record")
      ". This argument should only be supplied by a programmer if there is a new class of output record that supports the column formatting protocol."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "formatting-cell")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ") "(align-x "
         (:CL "':left") ") (align-y " (:CL "':baseline") ")  min-width min-height record-type "
         (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ")  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Controls the output of a single cell inside a table row or column, or of a single item inside "
      (:CL "formatting-item-list") ". All of the output performed by " (:GROUP (:FONT :FACE :I) "body")
      " becomes the contents of the cell." (:PAR) (:GROUP (:FONT :FACE :I) "stream")
      " is an output recording stream to which output will be done. The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "align-x")
      " specifies how the output in a cell will be aligned relative to other cells in the same table column. The default, "
      (:CL ":left") ", causes the cells to be flush-left in the column. The other possible values are " (:CL ":right")
      " (meaning flush-right in the column) and " (:CL ":center")
      " (meaning centered in the column). Each cell within a column may have a different alignment; thus it is possible, for example, to have centered legends over flush-right numeric data."
      (:PAR) (:GROUP (:FONT :FACE :I) "align-y")
      " specifies how the output in a cell will be aligned vertically. The default, " (:CL ":baseline")
      ", causes textual cells to be aligned along their baselines and graphical cells to be aligned at the bottom. The other possible values are "
      (:CL ":bottom") " (align at the bottom of the output), " (:CL ":top") " (align at the top of the output), and "
      (:CL ":center") " (center the output in the cell)." (:PAR) (:GROUP (:FONT :FACE :I) "min-width") " and "
      (:GROUP (:FONT :FACE :I) "min-height") " are used to specify minimum width or height of the cell. The default, "
      (:CL "nil")
      ", causes the cell to be only as wide or high as is necessary to contain the cell's contents. Otherwise, "
      (:GROUP (:FONT :FACE :I) "min-width") " and " (:GROUP (:FONT :FACE :I) "min-height")
      " are specified in the same way as the " (:CL ":x-spacing") " and " (:CL ":y-spacing") " arguments to "
      (:CL "formatting-table") "." (:PAR) (:GROUP (:FONT :FACE :I) "record-type")
      " specifies the class of output record to create. The default is " (:CL "standard-cell-output-record")
      ". This argument should only be supplied by a programmer if there is a new class of output record that supports the cell formatting protocol."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "formatting-item-list")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "x-spacing y-spacing  n-columns n-rows  stream-width stream-height max-width max-height  initial-spacing (row-wise "
         (:CL "t") ")  (move-cursor " (:CL "t") ") record-type " (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ")  "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Binds the local environment in such a way that the output of " (:GROUP (:FONT :FACE :I) "body")
      " will be done in an item list (that is, menu) format. This must be used in conjunction with "
      (:CL "formatting-cell")
      ", which delimits each item. The item list is placed so that its upper left corner is at the current text cursor position of "
      (:GROUP (:FONT :FACE :I) "stream") ". If the boolean " (:GROUP (:FONT :FACE :I) "move-cursor") " is "
      (:TERM "true")
      " (the default), then the text cursor will be moved so that it immediately follows the last cell of the item list."
      (:PAR)
      "\"Item list output\" is more strictly defined as: each row of the item list consists of a single cell. Rows are placed with the first row on top, and each succeeding row has its top aligned with the bottom of the previous row (plus the specified "
      (:GROUP (:FONT :FACE :I) "y-spacing")
      "). Multiple rows and columns are constructed after laying the item list out in a single column. Item list output takes place in a normalized +"
      (:MATH "y") "-downward coordinate system." (:PAR) "If " (:GROUP (:FONT :FACE :I) "row-wise") " is "
      (:TERM "true")
      " (the default) and the item list requires multiple columns, each successive element in the item list is layed out from left to right. If "
      (:GROUP (:FONT :FACE :I) "row-wise") " is " (:TERM "false")
      " and the item list requires multiple columns, each successive element in the item list is layed out below its predecessor, like in a telephone book."
      (:PAR) "The returned value is the output record corresponding to the table." (:PAR)
      (:GROUP (:FONT :FACE :I) "stream") " is an output recording stream to which output will be done. The "
      (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "x-spacing")
      " specifies the number of units of spacing to be inserted between columns of the item list; the default is the width of a "
      (:CODE "#\\Space") " character in the current text style. " (:GROUP (:FONT :FACE :I) "y-spacing")
      " specifies the number of units of spacing to be inserted between rows in the item list; the default is default vertical spacing of the stream. The format of these arguments is as for "
      (:CL "formatting-table") "." (:PAR) "When the boolean " (:GROUP (:FONT :FACE :I) "equalize-column-widths") " is "
      (:TERM "true")
      ", CLIM will make all of the columns have the same width (the width of the widest cell in any column in the entire item list)."
      (:PAR) (:GROUP (:FONT :FACE :I) "n-columns") " and " (:GROUP (:FONT :FACE :I) "n-rows")
      " specify the number of columns or rows in the item list. The default for both is " (:CL "nil")
      ", which causes CLIM to pick an aesthetically pleasing layout, possibly constrained by the other options. If both "
      (:GROUP (:FONT :FACE :I) "n-columns") " and " (:GROUP (:FONT :FACE :I) "n-rows")
      " are supplied and the item list contains more elements than will fit according to the specification, CLIM will format the item list as if "
      (:GROUP (:FONT :FACE :I) "n-rows") " were supplied as " (:CL "nil") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "max-width") " and " (:GROUP (:FONT :FACE :I) "max-height")
      " constrain the layout of the item list. CLIM will not make the item list any wider than "
      (:GROUP (:FONT :FACE :I) "max-width") ", unless it is overridden by " (:GROUP (:FONT :FACE :I) "n-rows")
      ". It will not make the item list any taller than " (:GROUP (:FONT :FACE :I) "max-height")
      ", unless it is overridden by " (:GROUP (:FONT :FACE :I) "n-columns") "." (:PAR) (:CL "formatting-item-list")
      " normally spaces items across the entire width of the stream. When " (:GROUP (:FONT :FACE :I) "initial-spacing")
      " is " (:TERM "true")
      ", it inserts some whitespace (about half as much space as is between each item) before the first item on each line. When it is "
      (:TERM "false") " (the default), the initial whitespace is not inserted." (:PAR)
      (:GROUP (:FONT :FACE :I) "record-type") " specifies the class of output record to create. The default is "
      (:CL "standard-item-list-output-record")
      ". This argument should only be supplied by a programmer if there is a new class of output record that supports the item list formatting protocol."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "format-items")) :PARAMS
       ((:I "items " (:GROUP (:FONT :FACE :TT) "&key ")
         "stream printer presentation-type  x-spacing y-spacing  n-columns n-rows  max-width max-height  cell-align-x cell-align-y  initial-spacing (row-wise "
         (:CL "t") ")  (move-cursor " (:CL "t") ") record-type"))
       :KIND ("Function"))
      (:PAR) "This is a function interface to the item list formatter. The elements of the sequence "
      (:GROUP (:FONT :FACE :I) "items") " are formatted as separate cells within the item list." (:PAR)
      (:GROUP (:FONT :FACE :I) "stream") " is an output recording stream to which output will be done. It defaults to "
      (:CL "*standard-output*") "." (:PAR) (:GROUP (:FONT :FACE :I) "printer")
      " must be a function that takes two arguments, an item and a stream, and outputs the item on the stream. "
      (:GROUP (:FONT :FACE :I) "printer") " has dynamic extent. The default for " (:GROUP (:FONT :FACE :I) "printer")
      " is " (:CL "prin1") "." (:PAR) (:GROUP (:FONT :FACE :I) "presentation-type") " is a presentation-type. When "
      (:GROUP (:FONT :FACE :I) "printer") " is not supplied, the items will be printed as if "
      (:GROUP (:FONT :FACE :I) "printer") " were "
      (:PRE "
#'(lambda (item stream)
    (present item presentation-type :stream stream))
")
      " When " (:GROUP (:FONT :FACE :I) "printer")
      " is supplied, each item will be enclosed in a presentation whose type is "
      (:GROUP (:FONT :FACE :I) "presentation-type") "." (:PAR) (:GROUP (:FONT :FACE :I) "x-spacing") ", "
      (:GROUP (:FONT :FACE :I) "y-spacing") ", " (:GROUP (:FONT :FACE :I) "n-columns") ", "
      (:GROUP (:FONT :FACE :I) "n-rows") ", " (:GROUP (:FONT :FACE :I) "max-width") ", "
      (:GROUP (:FONT :FACE :I) "max-height") ", " (:GROUP (:FONT :FACE :I) "initial-spacing") ", "
      (:GROUP (:FONT :FACE :I) "row-wise") ", and " (:GROUP (:FONT :FACE :I) "move-cursor") " are as for "
      (:CL "formatting-item-list") "." (:PAR) (:GROUP (:FONT :FACE :I) "cell-align-x") " and "
      (:GROUP (:FONT :FACE :I) "cell-align-y") " are used to supply " (:CL ":align-x") " and " (:CL ":align-y")
      " to an implicitly used " (:CL "formatting-cell") "." (:PAR) (:GROUP (:FONT :FACE :I) "record-type")
      " is as for " (:CL "formatting-item-list") "." (:PAR) " "))
    (:SECTION :TITLE ("17.3 " "The Table and Item List Formatting Protocols") :KIND :SECTION :NAME (3 7 10) (:PAR)
     "Both table and item list formatting is implemented on top of the basic output recording protocol, using "
     (:CL "with-new-output-record") " to specify the appropriate type of output record. For example, "
     (:CL "formatting-table")
     " first collects all the output that belongs in the table into a collection of row, column, and cell output records, all of which are children of a single table output record. During this phase, "
     (:CL "stream-drawing-p") " is bound to " (:CL "nil") " and " (:CL "stream-recording-p") " is bound to " (:CL "t")
     ". When all the output has been generated, the table layout constraint solver (" (:CL "adjust-table-cells") " or "
     (:CL "adjust-item-list-cells")
     ") is called to compute the table layout, taking into account such factors as the widest cell in a given column. If the table is to be split into multiple columns, "
     (:CL "adjust-multiple-columns")
     " is now called. Finally, the table output record is positioned on the stream at the current text cursor position and then displayed by calling "
     (:CL "replay") " on the table (or item list) output record." (:PAR) " "
     (:SECTION :TITLE ("17.3.1 " "Table Formatting Protocol") :KIND :SUBSECTION :NAME (4 3 7 10) (:PAR)
      "Any output record class that implements the following generic functions is said to support the table formatting protocol."
      (:PAR)
      "In the following subsections, the term \"non-table output records\" will be used to mean any output record that is not a table, row, column, cell, or item list output record. When CLIM \"skips over intervening non-table output records\", this means that it will bypass all the output records between two such table output records (such as a table and a row, or a row and a cell) that are not records of those classes (most notably, presentation output records). CLIM implementations are encouraged to detect invalid nesting of table output records, such as a row within a row, a cell within a cell, or a row within a cell. Note that this does not prohibit the nesting of calls to "
      (:CL "formatting-table")
      ", it simply requires that programmers include the inner table within one of the cells of the outer table."
      (:PAR) " "
      (:DEFUN (:SIGNATURE :NAME ((:CL "table-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that represents tabular output records; a subclass of " (:CL "output-record")
       ". If you want to create a new class that behaves like a table output record, it should be a subclass of "
       (:CL "table-output-record") ". All instantiable subclasses of " (:CL "table-output-record")
       " must obey the table output record protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "table-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a "
       (:TERM "table output record") ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":x-spacing")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":y-spacing")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":multiple-columns-x-spacing")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":equalize-column-widths")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "All subclasses of " (:CL "table-output-record")
       " must handle these initargs, which are used to specify, respectively, the " (:MATH "x") " and " (:MATH "y")
       " spacing, the multiple column " (:MATH "x") " spacing, and equal-width columns attributes of the table."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-table-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class of output record that represents tabular output. Its children will be a sequence of either rows or columns, with presentation output records possibly intervening. This is a subclass of "
       (:CL "table-output-record") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-table-elements")) :PARAMS ((:I "function table-record type")) :KIND
        ("Generic Function"))
       (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all the rows or columns of "
       (:GROUP (:FONT :FACE :I) "table-record") " that are of type " (:GROUP (:FONT :FACE :I) "type") ". "
       (:GROUP (:FONT :FACE :I) "type") " is either " (:CL ":row") ", " (:CL ":column") ", or " (:CL ":row-or-column")
       ". " (:GROUP (:FONT :FACE :I) "function")
       " is a function of one argument, an output record; it has dynamic extent. " (:CL "map-over-table-elements")
       " is responsible for ensuring that rows, columns, and cells are properly nested. It must skip over intervening non-table output record structure, such as presentations."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "adjust-table-cells")) :PARAMS ((:I "table-record stream")) :KIND ("Generic Function"))
       (:PAR)
       "This function is called after the tabular output has been collected, but before it has been replayed. The method on "
       (:CL "standard-table-output-record")
       " implements the usual table layout constraint solver (described above) by moving the rows or columns of the table output record "
       (:GROUP (:FONT :FACE :I) "table-record") " and the cells within the rows or columns. "
       (:GROUP (:FONT :FACE :I) "stream") " is the stream on which the table is displayed." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "adjust-multiple-columns")) :PARAMS ((:I "table-record stream")) :KIND
        ("Generic Function"))
       (:PAR) "This is called after " (:CL "adjust-table-cells")
       " to account for the case where the programmer wants the table to have multiple columns. "
       (:GROUP (:FONT :FACE :I) "table-record") " and " (:GROUP (:FONT :FACE :I) "stream") " are as for "
       (:CL "adjust-table-cells") "." (:PAR) " "))
     (:SECTION :TITLE ("17.3.2 " "Row and Column Formatting Protocol") :KIND :SUBSECTION :NAME (4 3 7 10) (:PAR)
      "Any output record class that implements the following generic functions is said to support the row (or column) formatting protocol."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "row-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that represents one row in a table; a subclass of " (:CL "output-record")
       ". If you want to create a new class that behaves like a row output record, it should be a subclass of "
       (:CL "row-output-record") ". All instantiable subclasses of " (:CL "row-output-record")
       " must obey the row output record protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "row-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "row output record")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-row-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class of output record that represents a row of output within a table. Its children will be a sequence of cells, and its parent (skipping intervening non-tabular records such as presentations) will be a table output record. This is a subclass of "
       (:CL "row-output-record") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-row-cells")) :PARAMS ((:I "function row-record")) :KIND ("Generic Function"))
       (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all the cells in the row "
       (:GROUP (:FONT :FACE :I) "row-record") ", skipping intervening non-table output record structure. "
       (:GROUP (:FONT :FACE :I) "function")
       " is a function of one argument, an output record corresponding to a table cell within the row; it has dynamic extent."
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "column-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that represents one column in a table; a subclass of " (:CL "output-record")
       ". If you want to create a new class that behaves like a column output record, it should be a subclass of "
       (:CL "column-output-record") ". All instantiable subclasses of " (:CL "column-output-record")
       " must obey the column output record protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "column-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a "
       (:TERM "column output record") ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-column-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class of output record that represent a column of output within a table. Its children will be a sequence of cells, and its parent (skipping intervening non-tabular records such as presentations) will be a table output record; presentation output records may intervene. This is a subclass of "
       (:CL "column-output-record") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-row-cells")) :PARAMS ((:I "function column-record")) :KIND
        ("Generic Function"))
       (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all the cells in the column "
       (:GROUP (:FONT :FACE :I) "column-record") ", skipping intervening non-table output record structure. "
       (:GROUP (:FONT :FACE :I) "function")
       " is a function of one argument, an output record corresponding to a table cell within the column; it has dynamic extent."
       (:PAR) " "))
     (:SECTION :TITLE ("17.3.3 " "Cell Formatting Protocol") :KIND :SUBSECTION :NAME (4 3 7 10) (:PAR)
      "Any output record class that implements the following generic functions is said to support the cell formatting protocol."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "cell-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that represents one cell in a table or an item list; a subclass of " (:CL "output-record")
       ". If you want to create a new class that behaves like a cell output record, it should be a subclass of "
       (:CL "cell-output-record") ". All instantiable subclasses of " (:CL "cell-output-record")
       " must obey the cell output record protocol. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cell-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "cell output record")
       ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":align-x")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":align-y")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":min-width")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":min-height")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
       (:CL "cell-output-record") " must handle these initargs, which are used to specify, respectively, the "
       (:MATH "x") " and " (:MATH "y") " alignment, and the minimum width and height attributes of the cell." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-cell-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class of output record that represent a single piece of output within a table row or column, or an item list. Its children will either be presentations, or output records that represent displayed output. This is a subclass of "
       (:CL "cell-output-record") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "cell-align-x")) :PARAMS ((:I "cell")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "cell-align-y")) :PARAMS ((:I "cell")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "cell-min-width")) :PARAMS ((:I "cell")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "cell-min-height")) :PARAMS ((:I "cell")) :KIND ("Generic Function")) (:PAR)
       "These functions return, respectively, the " (:MATH "x") " and " (:MATH "y")
       " alignment and minimum width and height of the " (:TERM "cell output record") " "
       (:GROUP (:FONT :FACE :I) "cell") "." (:PAR) " "))
     (:SECTION :TITLE ("17.3.4 " "Item List Formatting Protocol") :KIND :SUBSECTION :NAME (4 3 7 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "item-list-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
       "The protocol class that represents an item list; a subclass of " (:CL "output-record")
       ". If you want to create a new class that behaves like an item list output record, it should be a subclass of "
       (:CL "item-list-output-record") ". All instantiable subclasses of " (:CL "item-list-output-record")
       " must obey the item list output record protocol. " (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "item-list-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an "
       (:TERM "item list output record") ", otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":x-spacing")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":y-spacing")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":initial-spacing")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":row-wise")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":n-rows")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":n-columns")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":max-width")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":max-height")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
       (:CL "item-list-output-record") " must handle these initargs, which are used to specify, respectively, the "
       (:MATH "x") " and " (:MATH "y")
       " spacing, the initial spacing, row-wise, the desired number of rows and columns, and maximum width and height attributes of the item list."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "standard-item-list-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable output record that represents item list output. Its children will be a sequence of cells, with presentations possibly intervening. This is a subclass of "
       (:CL "item-list-output-record") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-item-list-cells")) :PARAMS ((:I "function item-list-record")) :KIND
        ("Generic Function"))
       (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all of the cells in "
       (:GROUP (:FONT :FACE :I) "item-list-record") ". " (:CL "map-over-item-list-cells")
       " must skip over intervening non-table output record structure, such as presentations. "
       (:GROUP (:FONT :FACE :I) "function")
       " is a function of one argument, an output record corresponding to a cell in the item list; it has dynamic extent."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "adjust-item-list-cells")) :PARAMS ((:I "item-list-record stream")) :KIND
        ("Generic Function"))
       (:PAR)
       "This function is called after the item list output has been collected, but before the record has been replayed. The method on "
       (:CL "standard-item-list-output-record") " implements the usual item list layout constraint solver. "
       (:GROUP (:FONT :FACE :I) "item-list-record") " is the item list output record, and "
       (:GROUP (:FONT :FACE :I) "stream") " is the stream on which the item list is displayed." (:PAR)))))
   " "
   (:SECTION :TITLE ("18 " "Graph Formatting") :KIND :CHAPTER :NAME (7 10) " " (:LABEL :NAME "graph-formatting") (:PAR)
    "CLIM provides a mechanism for arranging arbitrary output in a graph. The following code produces the graph shown in Figure "
    (:REF :NAME "graph-example") "." (:PAR)
    (:PRE "
(defun graph-test (stream &optional (orientation :horizontal)) 
  (fresh-line stream)
  (macrolet ((make-node (&key name children)
               `(list* ,name ,children)))
    (flet ((node-name (node)
             (car node))
           (node-children (node)
             (cdr node)))
      (let* ((2a (make-node :name \"2A\"))
             (2b (make-node :name \"2B\"))
             (2c (make-node :name \"2C\"))
             (1a (make-node :name \"1A\" :children (list 2a 2b)))
             (1b (make-node :name \"1B\" :children (list 2b 2c)))
             (root (make-node :name \"0\" :children (list 1a 1b))))
        (format-graph-from-roots
          (list root)
          #'(lambda (node s)
              (write-string (node-name node) s))
          #'node-children
          :orientation orientation
          :stream stream)))))
")
    (:PAR)
    (:FIGURE :NUMBER "18.1" :CAPTION ((:LABEL :NAME "graph-example") " Example of graph formatting.") " "
     (:CENTER (:IMG :SRC "graph-example.png")) "  ")
    (:PAR) " "
    (:SECTION :TITLE ("18.1 " "Graph Formatting Functions") :KIND :SECTION :NAME (2 7 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "format-graph-from-roots")) :PARAMS
       ((:I "root-objects object-printer inferior-producer  " (:GROUP (:FONT :FACE :TT) "&key ")
         "stream  orientation cutoff-depth  merge-duplicates duplicate-key duplicate-test  generation-separation within-generation-separation  center-nodes  arc-drawer arc-drawing-options  graph-type (move-cursor "
         (:CL "t") ")"))
       :KIND ("Function"))
      (:PAR) "Draws a graph whose roots are specified by the sequence " (:GROUP (:FONT :FACE :I) "root-objects")
      ". The nodes of the graph are displayed by calling the function " (:GROUP (:FONT :FACE :I) "object-printer")
      ", which takes two arguments, the node to display and a stream. " (:GROUP (:FONT :FACE :I) "inferior-producer")
      " is a function of one argument that is called on each node to produce a sequence of inferiors (or " (:CL "nil")
      " if there are none). Both " (:GROUP (:FONT :FACE :I) "object-printer") " and "
      (:GROUP (:FONT :FACE :I) "inferior-producer") " have dynamic extent." (:PAR)
      "The output from graph formatting takes place in a normalized +" (:MATH "y")
      "-downward coordinate system. The graph is placed so that the upper left corner of its bounding rectangle is at the current text cursor position of "
      (:GROUP (:FONT :FACE :I) "stream") ". If the boolean " (:GROUP (:FONT :FACE :I) "move-cursor") " is "
      (:TERM "true")
      " (the default), then the text cursor will be moved so that it immediately follows the lower right corner of the graph."
      (:PAR) "The returned value is the output record corresponding to the graph." (:PAR)
      (:GROUP (:FONT :FACE :I) "stream") " is an output recording stream to which output will be done. It defaults to "
      (:CL "*standard-output*") "." (:PAR) (:GROUP (:FONT :FACE :I) "orientation") " may be either "
      (:CL ":horizontal") " (the default) or " (:CL ":vertical")
      ". It specifies which way the graph is oriented. CLIM implementations are permitted to extend the values of "
      (:GROUP (:FONT :FACE :I) "orientation") ", for example, adding " (:CL ":right") " or " (:CL ":left")
      " to distinguish between left-to-right or right-to-left layouts." (:PAR) (:GROUP (:FONT :FACE :I) "cutoff-depth")
      " specifies the maximum depth of the graph. It defaults to " (:CL "nil")
      ", meaning that there is no cutoff depth. Otherwise it must be an integer, meaning that no nodes deeper than "
      (:GROUP (:FONT :FACE :I) "cutoff-depth") " will be formatted or displayed." (:PAR) "If the boolean "
      (:GROUP (:FONT :FACE :I) "merge-duplicates") " is " (:TERM "true")
      ", then duplicate objects in the graph will share the same node in the display of the graph. That is, when "
      (:GROUP (:FONT :FACE :I) "merge-duplicates") " is " (:TERM "true") ", the resulting graph will be a tree. If "
      (:GROUP (:FONT :FACE :I) "merge-duplicates") " is " (:TERM "false")
      " (the default), then duplicate objects will be displayed in separate nodes. "
      (:GROUP (:FONT :FACE :I) "duplicate-key")
      " is a function of one argument that is used to extract the node object component used for duplicate comparison; the default is "
      (:CL "identity") ". " (:GROUP (:FONT :FACE :I) "duplicate-test")
      " is a function of two arguments that is used to compare two objects to see if they are duplicates; the default is "
      (:CL "eql") ". " (:GROUP (:FONT :FACE :I) "duplicate-key") " and " (:GROUP (:FONT :FACE :I) "duplicate-test")
      " have dynamic extent." (:PAR) (:GROUP (:FONT :FACE :I) "generation-separation")
      " is the amount of space to leave between successive generations of the graph; the default should be chosen so that the resulting graph is visually pleasing. "
      (:GROUP (:FONT :FACE :I) "within-generation-separation")
      " is the amount of space to leave between nodes in the same generation of the graph; the default should be chosen so that the resulting graph is visually pleasing. "
      (:GROUP (:FONT :FACE :I) "generation-separation") " and "
      (:GROUP (:FONT :FACE :I) "within-generation-separation") " are specified in the same way as the "
      (:GROUP (:FONT :FACE :I) "inter-row-spacing") " argument to " (:CL "formatting-table") "." (:PAR) "When "
      (:GROUP (:FONT :FACE :I) "center-nodes") " is " (:TERM "true")
      ", each node of the graph is centered with respect to the widest node in the same generation. The default is "
      (:TERM "false") "." (:PAR) (:GROUP (:FONT :FACE :I) "arc-drawer")
      " is a function of seven positional and some unspecified keyword arguments that is responsible for drawing the arcs from one node to another; it has dynamic extent. The positional arguments are the stream, the \"from\" node's object, the \"to\" node's object, the \"from\" "
      (:MATH "x") " and " (:MATH "y") " position, and the \"to\" " (:MATH "x") " and " (:MATH "y")
      " position. The keyword arguments gotten from " (:GROUP (:FONT :FACE :I) "arc-drawing-options")
      " are typically line drawing options, such as for " (:CL "draw-line*") ". If "
      (:GROUP (:FONT :FACE :I) "arc-drawer")
      " is unsupplied, the default behavior is to draw a thin line from the \"from\" node to the \"to\" node using "
      (:CL "draw-line*") "." (:PAR) (:GROUP (:FONT :FACE :I) "graph-type")
      " is a keyword that specifies the type of graph to draw. All CLIM implementations must support graphs of type "
      (:CL ":tree") ", " (:CL ":directed-graph") " (and its synonym " (:CL ":digraph") "), and "
      (:CL ":directed-acyclic-graph") " (and its synonym " (:CL ":dag") "). " (:GROUP (:FONT :FACE :I) "graph-type")
      " defaults to " (:CL ":digraph") " when " (:GROUP (:FONT :FACE :I) "merge-duplicates") " is " (:TERM "true")
      ", otherwise it defaults to " (:CL ":tree")
      ". Typically, different graph types will use different output record classes and layout engines to lay out the graph. However, it is permissible for all of the required graph types to use exactly the same graph layout engine."
      (:PAR) " "))
    (:SECTION :TITLE ("18.2 " "The Graph Formatting Protocols") :KIND :SECTION :NAME (2 7 10) (:PAR)
     "Graph formatting is implemented on top of the basic output recording protocol, using "
     (:CL "with-new-output-record") " to specify the appropriate type of output record. For example, "
     (:CL "format-graph-from-roots")
     " first collects all the output that belongs in the graph into a collection of graph node output records by calling "
     (:CL "generate-graph-nodes")
     ". All of the graph node output records are descendents of a single graph output record. During this phase, "
     (:CL "stream-drawing-p") " is bound to " (:CL "nil") " and " (:CL "stream-recording-p") " is bound to " (:CL "t")
     ". When all the output has been generated, the graph layout code (" (:CL "layout-graph-nodes") " and "
     (:CL "layout-graph-edges")
     ") is called to compute the graph layout. Finally, the graph output record is positioned on the stream at the current text cursor position and then displayed by calling "
     (:CL "replay") " on the graph output record." (:PAR) " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "graph-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that represents a graph; a subclass of " (:CL "output-record")
      ". If you want to create a new class that behaves like a graph output record, it should be a subclass of "
      (:CL "graph-output-record") ". All instantiable subclasses of " (:CL "graph-output-record")
      " must obey the graph output record protocol. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "graph-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "graph output record")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-graph-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class of output record that represents a graph. Its children will be a sequence graph nodes. This is a subclass of "
      (:CL "graph-output-record") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":orientation")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":center-nodes")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":cutoff-depth")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":merge-duplicates")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":generation-separation")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":within-generation-separation")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":hash-table")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "All the graph output record must handle these seven initargs, which are used to specify, respectively, the orientation, node centering, cutoff depth, merge duplicates, generation and within-generation spacing, and the node hash table of a graph output record."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "define-graph-type")) :PARAMS ((:I "graph-type class")) :KIND ("Macro")) (:PAR)
      "Defines a new graph type named by the symbol " (:GROUP (:FONT :FACE :I) "graph-type")
      " that is implemented by the class " (:GROUP (:FONT :FACE :I) "class") ". " (:GROUP (:FONT :FACE :I) "class")
      " must be a subclass of " (:CL "graph-output-record") ". Neither of the arguments is evaluated." (:PAR)
      "All CLIM implementations must support graphs of type " (:CL ":tree") ", " (:CL ":directed-graph")
      " (and its synonym " (:CL ":digraph") "), and " (:CL ":directed-acyclic-graph") " (and its synonym " (:CL ":dag")
      ")." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "graph-root-nodes")) :PARAMS ((:I "graph-record")) :KIND ("Generic Function"))
      (:PAR)
      "Returns a sequence of the graph node output records corresponding to the root objects for the graph output record "
      (:GROUP (:FONT :FACE :I) "graph-record") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf graph-root-nodes)")) :PARAMS ((:I "roots graph-record")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the root nodes of " (:GROUP (:FONT :FACE :I) "graph-record") " to "
      (:GROUP (:FONT :FACE :I) "roots") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "generate-graph-nodes")) :PARAMS
       ((:I "graph-record stream  root-objects object-printer inferior-producer  " (:GROUP (:FONT :FACE :TT) "&key ")
         "duplicate-key duplicate-test"))
       :KIND ("Generic Function"))
      (:PAR) "This function is responsible for generating all of the graph node output records of the graph. "
      (:GROUP (:FONT :FACE :I) "graph-record") " is the graph output record, and " (:GROUP (:FONT :FACE :I) "stream")
      " is the output stream. The graph node output records are generating by calling the object printer on the root objects, then (recursively) calling the inferior producer on the root objects and calling the object printer on all inferiors. After all of the graph node output records have been generated, the value of "
      (:CL "graph-root-nodes") " of " (:GROUP (:FONT :FACE :I) "graph-record")
      " must be set to be a sequence of the those graph node output records that correspond to the root objects."
      (:PAR) (:GROUP (:FONT :FACE :I) "root-objects") ", " (:GROUP (:FONT :FACE :I) "object-printer") ", "
      (:GROUP (:FONT :FACE :I) "inferior-producer") ", " (:GROUP (:FONT :FACE :I) "duplicate-key") ", and "
      (:GROUP (:FONT :FACE :I) "duplicate-test") " are as for " (:CL "format-graph-from-roots") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "layout-graph-nodes")) :PARAMS
       ((:I "graph-record stream arc-drawer arc-drawing-options")) :KIND ("Generic Function"))
      (:PAR) "This function is responsible for laying out the nodes in the graph contained in the output record "
      (:GROUP (:FONT :FACE :I) "graph-record")
      ". It is called after the graph output has been collected, but before the graph record has been displayed. The method on "
      (:CL "standard-graph-output-record") " implements the usual graph layout constraint solver. "
      (:GROUP (:FONT :FACE :I) "stream") " is the stream on which the graph is displayed." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "layout-graph-edges")) :PARAMS
       ((:I "graph-record stream arc-drawer arc-drawing-options")) :KIND ("Generic Function"))
      (:PAR)
      "This function is responsible for laying out the edges in the graph. It is called after the graph nodes have been layed out, but before the graph record has been displayed. The method on "
      (:CL "standard-graph-output-record")
      " simply causes thin lines to be drawn from each node to all of its children. "
      (:GROUP (:FONT :FACE :I) "graph-record") " and " (:GROUP (:FONT :FACE :I) "stream") " are as for "
      (:CL "layout-graph-nodes") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "graph-node-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that represents a node in graph; a subclass of " (:CL "output-record")
      ". If you want to create a new class that behaves like a graph node output record, it should be a subclass of "
      (:CL "graph-node-output-record") ". All instantiable subclasses of " (:CL "graph-node-output-record")
      " must obey the graph node output record protocol. " (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "graph-node-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a "
      (:TERM "graph node output record") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-graph-node-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class of output record that represents a graph node. Its parent will be a graph output record. This is a subclass of "
      (:CL "graph-node-output-record") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "graph-node-parents")) :PARAMS ((:I "graph-node-record")) :KIND ("Generic Function"))
      (:PAR)
      "Returns a sequence of the graph node output records whose objects are \"parents\" of the object corresponding to the graph node output record "
      (:GROUP (:FONT :FACE :I) "graph-node-record") ". Note that this is not the same as " (:CL "output-record-parent")
      ", since " (:CL "graph-node-parents") " can return output records that are not the parent records of "
      (:GROUP (:FONT :FACE :I) "graph-node-record") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf graph-node-parents)")) :PARAMS ((:I "parents graph-node-record")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the parents of " (:GROUP (:FONT :FACE :I) "graph-node-record") " to be "
      (:GROUP (:FONT :FACE :I) "parents") ". " (:GROUP (:FONT :FACE :I) "parents")
      " must be a list of graph node records." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "graph-node-children")) :PARAMS ((:I "graph-node-record")) :KIND ("Generic Function"))
      (:PAR)
      "Returns a sequence of the graph node output records whose objects are \"children\" of the object corresponding to the graph node output record "
      (:GROUP (:FONT :FACE :I) "graph-node-record") ". Note that this is not the same as "
      (:CL "output-record-children") ", since " (:CL "graph-node-children")
      " can return output records that are not child records of " (:GROUP (:FONT :FACE :I) "graph-node-record") "."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf graph-node-children)")) :PARAMS ((:I "children graph-node-record")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the children of " (:GROUP (:FONT :FACE :I) "graph-node-record") " to be "
      (:GROUP (:FONT :FACE :I) "children") ". " (:GROUP (:FONT :FACE :I) "children")
      " must be a list of graph node records." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "graph-node-object")) :PARAMS ((:I "graph-node-record")) :KIND ("Generic Function"))
      (:PAR) "Returns the object that corresponds to the graph node output record "
      (:GROUP (:FONT :FACE :I) "graph-node-record")
      ". It is permissible for this function to work correctly only while inside of the call to "
      (:CL "format-graph-from-roots") ". It is unspecified what result will be returned outside of "
      (:CL "format-graph-from-roots")
      ". This restriction is permitted so that CLIM is not required to capture application objects that might have dynamic extent."
      (:PAR))))
   " "
   (:SECTION :TITLE ("19 " "Bordered Output") :KIND :CHAPTER :NAME (7 10) " " (:LABEL :NAME "bordered-output") (:PAR)
    "CLIM provides a mechanism for surrounding arbitrary output with some kind of a border. The programmer annotates some output-generating code with an advisory macro that describes the type of border to be drawn. The following code produces the output shown in Figure "
    (:REF :NAME "border-example") "." (:PAR)
    "For example, the following produces three pieces of output, surrounded by a rectangular, highlighted with a dropshadow, and underlined, respectively."
    (:PAR)
    (:PRE "
(defun border-test (stream)
  (fresh-line stream)
  (surrounding-output-with-border (stream :shape :rectangle)
    (format stream \"This is some output with a rectangular border\"))
  (terpri stream) (terpri stream)
  (surrounding-output-with-border (stream :shape :drop-shadow)
    (format stream \"This has a drop-shadow under it\"))
  (terpri stream) (terpri stream)
  (surrounding-output-with-border (stream :shape :underline)
    (format stream \"And this output is underlined\")))
")
    (:PAR)
    (:FIGURE :NUMBER "19.1" :CAPTION ((:LABEL :NAME "border-example") " Examples of bordered output.") " "
     (:CENTER (:IMG :SRC "border-example.png")) "  ")
    (:PAR) " "
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "surrounding-output-with-border")) :PARAMS
      ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&rest ")
        "drawing-options  " (:GROUP (:FONT :FACE :TT) "&key ") "shape (move-cursor " (:CL "t") "))  "
        (:GROUP (:FONT :FACE :TT) "&body ") "body"))
      :KIND ("Macro"))
     (:PAR) "Binds the local environment in such a way the output of " (:GROUP (:FONT :FACE :I) "body")
     " will be surrounded by a border of the specified shape. Every implementation must support the shapes "
     (:CL ":rectangle") " (the default), " (:CL ":oval") ", " (:CL ":drop-shadow") ", and " (:CL ":underline") ". "
     (:CL ":rectangle") " draws a rectangle around the bounding rectangle of the output. " (:CL ":oval")
     " draws an oval around the bounding rectangle of the output. " (:CL ":drop-shadow")
     " draws a \"drop shadow\" around the lower right edge of the bounding rectangle of the output. "
     (:CL ":underline")
     " draws a thin line along the baseline of all of the text in the output, but does not draw anything underneath non-textual output. "
     (:GROUP (:FONT :FACE :I) "drawing-options")
     " is a list of drawing options that are passed to the function that draws the border." (:PAR) "If the boolean "
     (:GROUP (:FONT :FACE :I) "move-cursor") " is " (:TERM "true")
     " (the default), then the text cursor will be moved so that it immediately follows the lower right corner of the bordered output."
     (:PAR) (:GROUP (:FONT :FACE :I) "stream") " is an output recording stream to which output will be done. The "
     (:GROUP (:FONT :FACE :I) "stream")
     " argument is not evaluated, and must be a symbol that is bound to a stream. If "
     (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*") " is used. "
     (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
     "There are several strategies for implementing borders. One strategy is to create a \"border output record\" that contains the output records produced by the output of "
     (:GROUP (:FONT :FACE :I) "body")
     ", plus one or more output records that represent the border. Another strategy might be to arrange to call the border drawer at the approriate times without explicitly recording it."
     (:PAR) " ")
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "define-border-type")) :PARAMS
      ((:I "shape arglist " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
     (:PAR) "Defines a new kind of border named " (:GROUP (:FONT :FACE :I) "shape") ". "
     (:GROUP (:FONT :FACE :I) "arglist") " must be a subset of the \"canonical\" arglist below (using "
     (:CL "string-equal") " to do the comparison): " (:BR) " "
     (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "stream record left top right bottom)") " " (:BR)
     (:PAR) (:GROUP (:FONT :FACE :I) "arglist")
     " may include other keyword arguments that serve as the drawing options." (:PAR) (:GROUP (:FONT :FACE :I) "body")
     " is the code that actually draws the border. It has lexical access to " (:CL "stream") ", " (:CL "record") ", "
     (:CL "left") ", " (:CL "top") ", " (:CL "right") ", and " (:CL "bottom")
     ", which are respectively, the stream being drawn on, the output record being surrounded, and the coordinates of the left, top, right, and bottom edges of the bounding rectangle of the record. "
     (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)))
   " "
   (:SECTION :TITLE ("20 " "Text Formatting") :KIND :CHAPTER :NAME (7 10) " " (:LABEL :NAME "text-formatting") (:PAR)
    (:SECTION :TITLE ("20.1 " "Textual List Formatting") :KIND :SECTION :NAME (3 7 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "format-textual-list")) :PARAMS
       ((:I "sequence printer  " (:GROUP (:FONT :FACE :TT) "&key ") "stream separator conjunction")) :KIND
       ("Function"))
      (:PAR) "Outputs the sequence of items in " (:GROUP (:FONT :FACE :I) "sequence")
      " as a \"textual list\". For example, the list " (:CL "(1 2 3 4)") " might be printed as "
      (:PRE "
1, 2, 3, and 4
")
      (:PAR) (:GROUP (:FONT :FACE :I) "printer")
      " is a function of two arguments: an element of the sequence and a stream; it has dynamic extent. It is called to output each element of the sequence."
      (:PAR) (:GROUP (:FONT :FACE :I) "stream") " specifies the output stream. The default is "
      (:CL "*standard-output*") "." (:PAR) "The " (:GROUP (:FONT :FACE :I) "separator") " and "
      (:GROUP (:FONT :FACE :I) "conjunction")
      " arguments provide control over the appearance of each element of the sequence and over the separators used between each pair of elements. "
      (:GROUP (:FONT :FACE :I) "separator")
      " is a string that is output after every element but the last one; the default for "
      (:GROUP (:FONT :FACE :I) "separator") " is " (:CL "\", \"") " (that is, a comma followed by a space). "
      (:GROUP (:FONT :FACE :I) "conjunction") " is a string that is output before the last element. The default is "
      (:CL "nil") ", meaning that there is no conjunction. Typical values for " (:GROUP (:FONT :FACE :I) "conjunction")
      " are the strings " (:CL "\"and\"") " and " (:CL "\"or\"") "." (:PAR) " "))
    (:SECTION :TITLE ("20.2 " "Indented Output") :KIND :SECTION :NAME (3 7 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "indenting-output")) :PARAMS
       ((:I "(stream indentation " (:GROUP (:FONT :FACE :TT) "&key ") "(move-cursor " (:CL "t") "))  "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Binds " (:GROUP (:FONT :FACE :I) "stream")
      " to a stream that inserts whitespace at the beginning of each line of output produced by "
      (:GROUP (:FONT :FACE :I) "body")
      ", and then writes the indented output to the stream that is the original value of "
      (:GROUP (:FONT :FACE :I) "stream") "." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to an output recording stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "indentation")
      " specifies how much whitespace should be inserted at the beginning of each line. It is specified in the same way as the "
      (:CL ":x-spacing") " option to " (:CL "formatting-table") "." (:PAR) "If the boolean "
      (:GROUP (:FONT :FACE :I) "move-cursor") " is " (:TERM "true")
      " (the default), CLIM moves the cursor to the end of the table." (:PAR) "Programmers using "
      (:CL "indenting-output") " should begin the body with a call to " (:GROUP (:FONT :FACE :I) "fresh-line")
      " (or some equivalent) to position the stream to the initial indentation." (:PAR)
      (:GROUP (:FONT :FACE :B) "Implementation note:") " Some CLIM implementations restrict the use of "
      (:CL "indenting-output") " and " (:CL "filling-output") " such that a call to " (:CL "indenting-output")
      " should appear outside of a call to " (:CL "filling-output")
      ". Implementations are encouraged to relax this restriction if the behavior is well-defined, but uses of "
      (:CL "indenting-output") " inside of " (:CL "filling-output") " may not be portable." (:PAR) " "))
    (:SECTION :TITLE ("20.3 " "Filled Output") :KIND :SECTION :NAME (3 7 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "filling-output")) :PARAMS
       ((:I "(stream " (:GROUP (:FONT :FACE :TT) "&key ")
         "fill-width break-characters  after-line-break after-line-break-initially)  "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Binds " (:GROUP (:FONT :FACE :I) "stream")
      " to a stream that inserts line breaks into the textual output written to it (by such functions as "
      (:CL "write-char") " and " (:CL "write-string") ") so that the output is usually no wider then "
      (:GROUP (:FONT :FACE :I) "fill-width") ". The filled output is then written on the original stream." (:PAR)
      "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "fill-width")
      " specifies the width of filled lines, and defaults to 80 characters. It is specified the same way as the "
      (:CL ":x-spacing") " option for " (:CL "formatting-table") "." (:PAR)
      "\"Words\" are separated by the characters specified in the list " (:GROUP (:FONT :FACE :I) "break-characters")
      ". When a line is broken to prevent wrapping past the end of a line, the line break is made at one of these separators. That is, "
      (:CL "filling-output") " does not split \"words\" across lines, so it might produce output wider than "
      (:GROUP (:FONT :FACE :I) "fill-width") "." (:PAR) (:GROUP (:FONT :FACE :I) "after-line-break")
      " specifies a string to be sent to " (:GROUP (:FONT :FACE :I) "stream")
      " after line breaks; the string appears at the beginning of each new line. The string must not be wider than "
      (:GROUP (:FONT :FACE :I) "fill-width") "." (:PAR) "If the boolean "
      (:GROUP (:FONT :FACE :I) "after-line-break-initially") " is " (:TERM "true") ", then the "
      (:GROUP (:FONT :FACE :I) "after-line-break") " text is to be written to " (:GROUP (:FONT :FACE :I) "stream")
      " before executing " (:GROUP (:FONT :FACE :I) "body")
      ", that is, at the beginning of the first line. The default is " (:TERM "false") "." (:PAR))))
   " "
   (:SECTION :TITLE ("21 " "Incremental Redisplay") :KIND :CHAPTER :NAME (7 10) " "
    (:LABEL :NAME "incremental-redisplay") (:PAR)
    (:SECTION :TITLE ("21.1 " "Overview of Incremental Redisplay") :KIND :SECTION :NAME (4 7 10) (:PAR)
     "CLIM's incremental redisplay facility to allows the programmer to change the output in an output history (and hence, on the screen or other output device) in an incremental fashion. It allows the programmer to redisplay individual pieces of the existing output differently, under program control. It is \"incremental\" in the sense that CLIM will try to minimize the changes to the existing output on a display device when displaying new output."
     (:PAR) "There are two different ways to do incremental redisplay." (:PAR) "The first is to call "
     (:CL "redisplay")
     " on an output record. In essence, this tells CLIM to recompute the output of that output record over from scratch. CLIM compares the new results with the existing output and tries to do minimal redisplay. The "
     (:CL "updating-output")
     " form allows the programmer to assist CLIM by informing it that entire branches of the output history are known not to have changed. "
     (:CL "updating-output")
     " also allows the programmer to communicate the fact that a piece of the output record hierarchy has moved, either by having an output record change its parent, or by having an output record change its position."
     (:PAR)
     "The second way to do incremental redisplay is for the programmer to manually do the updates to the output history, and then call "
     (:CL "note-output-record-child-changed")
     " on an output record. This causes CLIM to propagate the changes up the output record tree and allows parent output records to readjust themselves to account for the changes."
     (:PAR) "Each style is appropriate under different circumstances. " (:CL "redisplay")
     " is often easier to use, especially when there might are large numbers of changes between two passes, or when the programmer has only a poor idea as to what the changes might be. "
     (:CL "note-output-record-child-changed")
     " can be more efficient for small changes at the bottom of the output record hierarchy, or in cases where the programmer is well informed as to the specific changes necessary and can help CLIM out."
     (:PAR) " "
     (:SECTION :TITLE ("21.1.1 " "Examples of Incremental Redisplay") :KIND :SUBSECTION :NAME (1 4 7 10) (:PAR)
      "The usual technique of incremental redisplay is to use " (:CL "updating-output")
      " to inform CLIM what output has changed, and use " (:CL "redisplay") " to recompute and redisplay that output."
      (:PAR) "The outermost call to " (:CL "updating-output")
      " identifies a program fragment that produces incrementally redisplayable output. A nested call to "
      (:CL "updating-output") " (that is, a call to " (:CL "updating-output")
      " that occurs during the execution of the body of the outermost " (:CL "updating-output")
      " and specifies the same stream) identifies an individually redisplayable piece of output, the program fragment that produces that output, and the circumstances under which that output needs to be redrawn. This nested calls to "
      (:CL "updating-output")
      " are just hints to incremental redisplay that can reduce the amount of work done by CLIM." (:PAR)
      "The outermost call to " (:CL "updating-output")
      " executes its body, producing the initial version of the output, and returns an " (:CL "updating-output-record")
      " that captures the body in a closure. Each nested call to " (:CL "updating-output") " stores its "
      (:CL ":unique-id") " and " (:CL ":cache-value") " arguments and the portion of the output produced by its body."
      (:PAR) (:CL "redisplay") " takes an " (:CL "updating-output-record") " and executes the captured body of "
      (:CL "updating-output") " over again. When a nested call to " (:CL "updating-output")
      " is executed during redisplay, " (:CL "updating-output")
      " decides whether the cached output can be reused or the output needs to be redrawn. This is controlled by the "
      (:CL ":cache-value") " argument to " (:CL "updating-output")
      ". If its value matches its previous value, the body would produce output identical to the previous output and thus it is unnecessary for CLIM to execute the body again. In this case the cached output is reused and "
      (:CL "updating-output")
      " does not execute its body. If the cache value does not match, the output needs to be recomputed, so "
      (:CL "updating-output")
      " executes its body and the new output drawn on the stream replaces the previous output. The "
      (:CL ":cache-value") " argument is only meaningful for nested calls to " (:CL "updating-output") "." (:PAR)
      "In order to compare the cache to the output record, two pieces of information are necessary:" (:PAR)
      (:UL
       (:LI
        "An association between the output being done by the program and a particular cache. This is supplied in the "
        (:CL ":unique-id") " option to " (:CL "updating-output") "." (:PAR))
       (:LI "A means of determining whether this particular cache is valid. This is the " (:CL ":cache-value")
        " option to " (:CL "updating-output") ". "))
      (:PAR)
      "Normally, the programmer would supply both options. The unique-id would be some data structure associated with the corresponding part of output. The cache value would be something in that data structure that changes whenever the output changes."
      (:PAR) "It is valid to give the " (:CL ":unique-id") " and not the " (:CL ":cache-value")
      ". This is done to identify a parent in the hierarchy. By this means, the children essentially get a more complex unique id when they are matched for output. (In other words, it is like using a telephone area code.) The cache without a cache value is never valid. Its children always have to be checked."
      (:PAR) "It is also valid to give the " (:CL ":cache-value") " and not the " (:CL ":unique-id")
      ". In this case, unique ids are just assigned sequentially. So, if output associated with the same thing is done in the same order each time, it isn't necessary to invent new unique ids for each piece. This is especially true in the case of children of a cache with a unique id and no cache value of its own. In this case, the parent marks the particular data structure, whose components can change individually, and the children are always in the same order and properly identified by their parent and the order in which they are output."
      (:PAR)
      "A unique id need not be unique across the entire redisplay, only among the children of a given output cache; that is, among all possible (current and additional) uses made of "
      (:CL "updating-output") " that are dynamically (not lexically) within another." (:PAR)
      "To make incremental redisplay maximally efficient, the programmer should attempt to give as many caches with "
      (:CL ":cache-value")
      " as possible. For instance, if the thing being redisplayed is a deeply nested tree, it is better to be able to know when whole branches have not changed than to have to recurse to every single leaf and check it. So, if there is a modification tick in the leaves, it is better to also have one in their parent of the leaves and propagate the modification up when things change. While the simpler approach works, it requires CLIM to do more work than is necessary."
      (:PAR) "The following function illustrates the standard use of incremental redisplay:" (:PAR)
      (:PRE "
(defun test (stream)
  (let* ((list (list 1 2 3 4 5))
         (record
           (updating-output (stream)
             (do* ((elements list (cdr elements))
                   (count 0 (1+ count)))
                  ((null elements))
               (let ((element (first elements)))
                 (updating-output (stream :unique-id count
                                          :cache-value element)
                   (format stream \"Element ~D\" element)
                   (terpri stream)))))))
    (sleep 10)
    (setf (nth 2 list) 17)
    (redisplay record stream)))
")
      (:PAR) "When this function is run on a window, the initial display will look like:" (:PAR)
      (:PRE "
  Element 1
  Element 2
  Element 3
  Element 4
  Element 5
")
      (:PAR) "After the sleep has terminated, the display will look like:" (:PAR)
      (:PRE "
  Element 1
  Element 2
  Element 17
  Element 4
  Element 5
")
      (:PAR)
      "CLIM takes care of ensuring that only the third line gets erased and redisplayed. In the case where items moved around (try the example substituting"
      (:PAR)
      (:PRE "
(setq list (sort list #'(lambda (x y)
                          (declare (ignore x y))
                          (zerop (random 2))))) 
")
      (:PAR) "for the form after the call to " (:CL "sleep")
      "), CLIM would ensure that the minimum amount of work would be done in updating the display, thereby minimizing \"flashiness\" while providing a powerful user interface."
      (:PAR) "See Chapter " (:REF :NAME "application-frames")
      " for a discussion of how to use incremental redisplay automatically within the panes of an application frame."
      (:PAR) " "))
    (:SECTION :TITLE ("21.2 " "Standard Programmer Interface") :KIND :SECTION :NAME (4 7 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "updating-output")) :PARAMS
       ((:I "(stream  " (:GROUP (:FONT :FACE :TT) "&rest ") "args  " (:GROUP (:FONT :FACE :TT) "&key ")
         "unique-id (id-test " (:ENTITY :NAME "#35") "'" (:CL "eql") ")  cache-value (cache-test "
         (:ENTITY :NAME "#35") "'" (:CL "eql") ")  fixed-position all-new parent-cache  record-type)  "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Introduces a caching point for incremental redisplay." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to an output recording stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "record-type") " specifies the class of output record to create. The default is "
      (:CL "standard-updating-output-record")
      ". This argument should only be supplied by a programmer if there is a new class of output record that supports the updating output record protocol."
      (:PAR) (:CL "updating-output") " must be implemented by expanding into a call to " (:CL "invoke-updating-output")
      ", supplying a function that executes " (:GROUP (:FONT :FACE :I) "body") " as the "
      (:GROUP (:FONT :FACE :I) "continuation") " argument to " (:CL "invoke-updating-output")
      ". The exact behavior of this macro is described under " (:CL "invoke-updating-output") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "invoke-updating-output")) :PARAMS
       ((:I "stream continuation record-type  unique-id id-test  cache-value cache-test  "
         (:GROUP (:FONT :FACE :TT) "&key ") "all-new parent-cache"))
       :KIND ("Generic Function"))
      (:PAR) "Introduces a caching point for incremental redisplay. Calls the function "
      (:GROUP (:FONT :FACE :I) "continuation") ", which generates the output records to be redisplayed. "
      (:GROUP (:FONT :FACE :I) "continuation") " is a function of one argument, the stream; it has dynamic extent."
      (:PAR)
      "If this is used outside the dynamic scope of an incremental redisplay, it has no particular effect. However, when incremental redisplay is occurring, the supplied "
      (:GROUP (:FONT :FACE :I) "cache-value") " is compared with the value stored in the cache identified by "
      (:GROUP (:FONT :FACE :I) "unique-id") ". If the values differ or the code in " (:GROUP (:FONT :FACE :I) "body")
      " has not been run before, the code in " (:GROUP (:FONT :FACE :I) "body") " runs, and "
      (:GROUP (:FONT :FACE :I) "cache-value") " is saved for next time. If the cache values are the same, the code in "
      (:GROUP (:FONT :FACE :I) "body") " is not run, because the current output is still valid." (:PAR)
      (:GROUP (:FONT :FACE :I) "unique-id") " provides a means to uniquely identify the output done by "
      (:GROUP (:FONT :FACE :I) "body") ". If " (:GROUP (:FONT :FACE :I) "unique-id")
      " is not supplied, CLIM will generate one that is guaranteed to be unique. "
      (:GROUP (:FONT :FACE :I) "unique-id") " may be any object as long as it is unique with respect to the "
      (:GROUP (:FONT :FACE :I) "id-test") " predicate among all such unique ids in the current incremental redisplay. "
      (:GROUP (:FONT :FACE :I) "id-test")
      " is a function of two arguments that is used for comparing unique ids; it has indefinite extent." (:PAR)
      (:GROUP (:FONT :FACE :I) "cache-value")
      " is a value that remains constant if and only if the output produced by body does not need to be recomputed. If the cache value is not supplied, CLIM will not use a cache for this piece of output. "
      (:GROUP (:FONT :FACE :I) "cache-test")
      " is a function of two arguments that is used for comparing cache values; it has indefinite extent." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "fixed-position") " is " (:TERM "true")
      ", then the location of this output is fixed relative to its parent output record. When CLIM redisplays an output record that has a fixed position, then if the contents have not changed, the position of the output record will not change. If the contents have changed, CLIM assumes that the code will take care to preserve its position. The default for "
      (:GROUP (:FONT :FACE :I) "fixed-position") " is " (:TERM "false") "." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "all-new") " is " (:TERM "true") ", that indicates that all of the output done by "
      (:GROUP (:FONT :FACE :I) "body")
      " is new, and will never match output previously recorded. In this case, CLIM will discard the old output and do the redisplay from scratch. The default for "
      (:GROUP (:FONT :FACE :I) "all-new") " is " (:TERM "false") "." (:PAR) "The output record tree created by "
      (:CL "updating-output")
      " defines a caching structure where mappings from a unique-id to an output record are maintained. If the programmer specifies an output record some output record "
      (:MATH "P") " via the " (:GROUP (:FONT :FACE :I) "parent-cache")
      " argument, then CLIM will try to find a corresponding output record with the matching unique-id in the cache belonging to "
      (:MATH "P") ". If neither " (:GROUP (:FONT :FACE :I) "parent-cache")
      " is not provided, then CLIM looks for the unique-id in the output record created by immediate dynamically enclosing call to "
      (:CL "updating-output")
      ". If that fails, CLIM use the unique-id to find an output record that is a child of the output history of "
      (:GROUP (:FONT :FACE :I) "stream")
      ". Once CLIM has found an output record that matches the unique-id, it uses the cache value and cache test to determine whether the output record has changed. If the output record has not changed, it may have moved, in which case CLIM will simply move the display of the output record on the display device."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "redisplay")) :PARAMS
       ((:I "record stream " (:GROUP (:FONT :FACE :TT) "&key ") "(check-overlapping " (:CL "t") ")")) :KIND
       ("Function"))
      (:PAR) "This function simply calls " (:CL "redisplay-output-record") " on the arguments "
      (:GROUP (:FONT :FACE :I) "record") " and " (:GROUP (:FONT :FACE :I) "stream") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "redisplay-output-record")) :PARAMS
       ((:I "record stream  " (:GROUP (:FONT :FACE :TT) "&optional ") "(check-overlapping " (:CL "t")
         ")  x y parent-x parent-y"))
       :KIND ("Generic Function"))
      (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "The coordinate system stuff affected by the x/y and parent-x/y arguments is entirely bogus. The proposal to make \"stream relative\" coordinates for output records instead of \"parent relative\" coordinates will eliminate this completely. --- SWM")
      (:PAR)
      (:CL "(redisplay-output-record " (:GROUP (:FONT :FACE :I) "record") " " (:GROUP (:FONT :FACE :I) "stream") ")")
      " causes the output of " (:GROUP (:FONT :FACE :I) "record")
      " to be recomputed. CLIM redisplays the changes \"incrementally\", that is, it only displays those parts that have been changed. "
      (:GROUP (:FONT :FACE :I) "record") " must already be part of the output history of the "
      (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
      ", although it can be anywhere inside the hierarchy." (:PAR) "When "
      (:GROUP (:FONT :FACE :I) "check-overlapping") " is " (:TERM "false")
      ", this means that CLIM can assume that no sibling output records overlap each other at any level in the output record tree. Supplying a "
      (:TERM "false") " value for this argument can improve performance of redisplay." (:PAR)
      (:GROUP (:FONT :FACE :B) "Implementation note:") " " (:CL "redisplay-output-record")
      " is implemented by first binding " (:CL "stream-redisplaying-p") " of the stream to " (:TERM "true")
      ", then creating the new output records by invoking " (:CL "compute-new-output-records")
      ". Once the new output records have been computed, " (:CL "compute-difference-set")
      " is called to compute the difference set, which is then passed to " (:CL "note-child-output-record-changed") "."
      (:PAR) "The other optional arguments can be used to specify where on the " (:GROUP (:FONT :FACE :I) "stream")
      " the output record should be redisplayed. " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
      " represent where the cursor should be, relative to (" (:CL "output-record-parent")
      " record), before we start redisplaying " (:GROUP (:FONT :FACE :I) "record") ". "
      (:GROUP (:FONT :FACE :I) "parent-x") " and " (:GROUP (:FONT :FACE :I) "parent-y")
      " can be supplied to say: do the output as if the parent started at positions "
      (:GROUP (:FONT :FACE :I) "parent-x") " and " (:GROUP (:FONT :FACE :I) "parent-y")
      " (which are in absolute coordinates). The default values for " (:GROUP (:FONT :FACE :I) "x") " and "
      (:GROUP (:FONT :FACE :I) "y") " are "
      (:CL "(output-record-start-position " (:GROUP (:FONT :FACE :I) "record") ")") ". The default values for "
      (:GROUP (:FONT :FACE :I) "parent-x") " and " (:GROUP (:FONT :FACE :I) "parent-y") " are" (:PAR)
      (:PRE "
(convert-from-relative-to-absolute-coordinates 
  stream (output-record-parent record))
")
      (:PAR) (:GROUP (:FONT :FACE :I) "record") " will usually be an output record created by " (:CL "updating-output")
      ". If it is not, then " (:CL "redisplay-output-record") " will be equivalent to " (:CL "replay-output-record")
      "." (:PAR) " "))
    (:SECTION :TITLE ("21.3 " "Incremental Redisplay Protocol") :KIND :SECTION :NAME (4 7 10) (:PAR)
     (:GROUP (:FONT :FACE :B) "Major issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "While the description of the API here is accurate, the description of the protocol is a disaster. This is no surprise, since the protocol for increment redisplay is itself a disaster. --- SWM")
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "updating-output-record")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class corresponding to records that support incremental redisplay; a subclass of "
      (:CL "output-record")
      ". If you want to create a new class that behaves like an updating output record, it should be a subclass of "
      (:CL "updating-output-record") ". All instantiable subclasses of " (:CL "updating-output-record")
      " must obey the updating output record protocol. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "updating-output-record-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an "
      (:TERM "updating output record") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":unique-id")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":id-test")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":cache-value")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":cache-test")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":fixed-position")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "updating-output-record")
      " must handle these four initargs, which are used to specify, respectively, the unique id and id test, cache value and cache test, and the \"fixed position\" component of the output record."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-updating-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class of output record that supports incremental redisplay. This is a subclass of "
      (:CL "updating-output-record") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-unique-id")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
      (:PAR) "Returns the unique id associated with the updating output record " (:GROUP (:FONT :FACE :I) "record") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-cache-value")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
      (:PAR) "Returns the cache value associated with the updating output record " (:GROUP (:FONT :FACE :I) "record")
      "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "output-record-fixed-position")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
      (:PAR) "Returns " (:TERM "true") " if the updating output record " (:GROUP (:FONT :FACE :I) "record")
      " is at a fixed location on the output stream, otherwise returns " (:TERM "false")
      ". Output records that are not at fixed location on the output stream will be moved by incremental redisplay when any of their siblings adjust their size or position."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-displayer")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
      (:PAR)
      "Returns the function that produces the output for this output record. This is the function that is called during redisplay to produce new output if the cache value mismatches."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "compute-new-output-records")) :PARAMS ((:I "record stream")) :KIND ("Generic Function"))
      (:PAR) (:CL "compute-new-output-records")
      " modifies an output record tree to reflect new output done by the application. In addition to inserting the new output records into the output record tree, it must save enough information to be able to compute the difference set, such as the old bounding rectangle, old cursor positions, old children, and so forth."
      (:PAR) (:CL "compute-new-output-records") " recursively invokes itself on each child of "
      (:GROUP (:FONT :FACE :I) "record") "." (:PAR) (:CL "compute-new-output-records") " of an output record of type "
      (:CL "updating-output-record") " runs the displayer (" (:CL "output-record-displayer")
      "), which gives the behavior of incremental redisplay. That is, it reruns the code (getting hints from "
      (:CL "updating-output") ") and figures out the changes from there by comparing it to the old output history."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "compute-difference-set")) :PARAMS
       ((:I "record " (:GROUP (:FONT :FACE :TT) "&optional ") "(check-overlapping " (:CL "t") ")  (offset-x " (:CL "0")
         ") (offset-y " (:CL "0") ")  (old-offset-x " (:CL "0") ") (old-offset-y " (:CL "0") ")"))
       :KIND ("Generic Function"))
      (:PAR) (:CL "compute-difference-set") " compares the current state of the " (:TERM "output record") " "
      (:GROUP (:FONT :FACE :I) "record")
      " with its previous state, and returns a \"difference set\" as five values. The difference set controls what needs to be done to the display device in order to accomplish the incremental redisplay."
      (:PAR) "The values returned are " (:GROUP (:FONT :FACE :I) "erases")
      " (what areas of the display device need to be erased), " (:GROUP (:FONT :FACE :I) "moves")
      " (what output records need to be moved), " (:GROUP (:FONT :FACE :I) "draws")
      " (what output records need to be freshly replayed), " (:GROUP (:FONT :FACE :I) "erase-overlapping") ", and "
      (:GROUP (:FONT :FACE :I) "move-overlapping") ". Each is a list whose elements are lists of the form:" (:PAR)
      "When " (:GROUP (:FONT :FACE :I) "check-overlapping") " is " (:TERM "false")
      ", this means that CLIM can assume that no sibling output records overlap each other at any level. Supplying a "
      (:TERM "false") " value for this argument can improve performance of redisplay." (:PAR) " "
      (:UL
       (:LI (:GROUP (:FONT :FACE :I) "erases") " are lists of "
        (:CL "(" (:GROUP (:FONT :FACE :I) "record") " " (:GROUP (:FONT :FACE :I) "old-box") ")") (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "moves") " are lists of "
        (:CL "("
             (:GROUP (:FONT :FACE :I) "record")
             " "
             (:GROUP (:FONT :FACE :I) "old-box")
             " "
             (:GROUP (:FONT :FACE :I) "new-position")
             ")")
        (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "draws") " are lists of "
        (:CL "(" (:GROUP (:FONT :FACE :I) "record") " " (:GROUP (:FONT :FACE :I) "old-box") ")") (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "erase-overlapping") " is a list of "
        (:CL "(" (:GROUP (:FONT :FACE :I) "record") " " (:GROUP (:FONT :FACE :I) "old-box") ")") (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "move-overlapping") " is a list of "
        (:CL "("
             (:GROUP (:FONT :FACE :I) "record")
             " "
             (:GROUP (:FONT :FACE :I) "old-box")
             " "
             (:GROUP (:FONT :FACE :I) "new-position")
             ")")
        " "))
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "augment-draw-set")) :PARAMS
       ((:I "record erases moves draws erase-overlapping move-overlapping  " (:GROUP (:FONT :FACE :TT) "&optional ")
         "x-offset y-offset old-x-offset old-y-offset"))
       :KIND ("Generic Function"))
      (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " " (:GROUP (:FONT :FACE :SL) "To be supplied. --- SWM") (:PAR)
      " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "note-output-record-child-changed")) :PARAMS ((:I)) :KIND ("Generic Function"))
      (:GROUP "record child mode old-position old-bounding-rectangle stream  " (:GROUP (:FONT :FACE :TT) "&optional ")
       "erases moves draws erase-overlapping move-overlapping  " (:GROUP (:FONT :FACE :TT) "&key ")
       "check-overlapping")
      (:PAR) (:CL "note-output-record-child-changed")
      " is called after an output history has had changes made to it, but before any of the new output has been displayed. It will call "
      (:CL "propagate-output-record-changes-p")
      " to determine if the parent output record should be notified, and if so, will call "
      (:CL "propagate-output-record-changes")
      " to create an updated difference set. If no changes need to be propagated to the parent output record, then "
      (:CL "note-output-record-child-changed") " will call " (:CL "incremental-redisplay")
      " in order display the difference set." (:PAR) (:GROUP (:FONT :FACE :I) "mode") " is one of " (:CL ":delete")
      ", " (:CL ":add") ", " (:CL ":change") ", " (:CL ":move") ", or " (:CL ":none") (:PAR)
      (:GROUP (:FONT :FACE :I) "old-position") " and " (:GROUP (:FONT :FACE :I) "old-bounding-rectangle")
      " describe where " (:GROUP (:FONT :FACE :I) "child") " was before it was moved." (:PAR)
      (:GROUP (:FONT :FACE :I) "check-overlapping") " is as for " (:CL "compute-difference-set") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "propagate-output-record-changes-p")) :PARAMS
       ((:I "record child mode  old-position old-bounding-rectangle")) :KIND ("Generic Function"))
      (:PAR) (:CL "propagate-output-record-changes-p") " is a predicate that returns " (:TERM "true")
      " if the change made to the child will cause " (:GROUP (:FONT :FACE :I) "record")
      " to be redisplayed in any way. Otherwise, it returns " (:TERM "false") ". " (:GROUP (:FONT :FACE :I) "mode")
      " is one of " (:CL ":delete") ", " (:CL ":add") ", " (:CL ":change") ", " (:CL ":move") ", or " (:CL ":none") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "propagate-output-record-changes")) :PARAMS ((:I)) :KIND ("Generic Function"))
      (:GROUP "record child mode  " (:GROUP (:FONT :FACE :TT) "&optional ")
       "old-position old-bounding-rectangle  erases moves draws erase-overlapping move-overlapping check-overlapping")
      (:PAR) "Called when the changed " (:GROUP (:FONT :FACE :I) "child") " output record requires that its parent, "
      (:GROUP (:FONT :FACE :I) "record") ", be redisplayed as well. " (:CL "propagate-output-record-changes")
      " will update the difference set to reflect the additional changes." (:PAR)
      (:GROUP (:FONT :FACE :I) "check-overlapping") " is as for " (:CL "compute-difference-set") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "match-output-records")) :PARAMS
       ((:I "record " (:GROUP (:FONT :FACE :TT) "&rest ") "initargs")) :KIND ("Generic Function"))
      (:PAR) "Returns " (:TERM "true") " if record matches the supplied class initargs "
      (:GROUP (:FONT :FACE :I) "initargs") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-child-output-record")) :PARAMS
       ((:I "record use-old-elements record-type  " (:GROUP (:FONT :FACE :TT) "&rest ") "initargs  "
         (:GROUP (:FONT :FACE :TT) "&key ") "unique-id unique-id-test"))
       :KIND ("Generic Function"))
      (:PAR) "Finds a child of " (:GROUP (:FONT :FACE :I) "record") " matching the "
      (:GROUP (:FONT :FACE :I) "record-type") " and the supplied initargs " (:GROUP (:FONT :FACE :I) "initargs") ". "
      (:GROUP (:FONT :FACE :I) "unique-id") " and " (:GROUP (:FONT :FACE :I) "unique-id-test")
      " are used to match against the children as well. " (:GROUP (:FONT :FACE :I) "use-old-elements")
      " controls whether the desired record is to be found in the previous (before redisplay) contents of the record."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-record-contents-ok")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
      (:PAR) "Returns " (:TERM "true") " if the current state of " (:GROUP (:FONT :FACE :I) "record")
      " are up to date, otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "recompute-contents-ok")) :PARAMS ((:I "record")) :KIND ("Generic Function"))
      (:PAR) "Compares the old (before redisplay) and new contents of " (:GROUP (:FONT :FACE :I) "record")
      " to determine whether or not this record changed in such a way so that the display needs updating." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "cache-output-record")) :PARAMS ((:I "record child unique-id")) :KIND
       ("Generic Function"))
      (:PAR) (:GROUP (:FONT :FACE :I) "record") " stores " (:GROUP (:FONT :FACE :I) "child")
      " such that it can be located later using " (:GROUP (:FONT :FACE :I) "unique-id") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "decache-child-output-record")) :PARAMS ((:I "record child use-old-elements")) :KIND
       ("Generic Function"))
      (:PAR) "Invalidates the redisplay state of " (:GROUP (:FONT :FACE :I) "record") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-cached-output-record")) :PARAMS
       ((:I "record use-old-elements record-type  " (:GROUP (:FONT :FACE :TT) "&rest ") "initargs  "
         (:GROUP (:FONT :FACE :TT) "&key ") "unique-id unique-id-test "
         (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
       :KIND ("Generic Function"))
      (:PAR) "Finds a previously cached child matching " (:GROUP (:FONT :FACE :I) "record-type") ", "
      (:GROUP (:FONT :FACE :I) "initargs") ", " (:GROUP (:FONT :FACE :I) "unique-id") ", and "
      (:GROUP (:FONT :FACE :I) "unique-id-test") ". " (:GROUP (:FONT :FACE :I) "use-old-elements")
      " controls whether the desired record is to be found in the previous (before redisplay) contents of the record."
      (:PAR) " "))
    (:SECTION :TITLE ("21.4 " "Incremental Redisplay Stream Protocol") :KIND :SECTION :NAME (4 7 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "redisplayable-stream-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:PAR) "Returns " (:TERM "true")
      " for any stream that maintains an output history and supports the incremental redisplay protocol, otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-redisplaying-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:PAR) "Returns " (:TERM "true") " if the " (:GROUP (:FONT :FACE :I) "stream")
      " is currently doing redisplay (that is, is inside of a call to " (:CL "redisplay") "), otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "incremental-redisplay")) :PARAMS
       ((:I "stream position  erases moves draws erase-overlapping move-overlapping")) :KIND ("Generic Function"))
      (:PAR) "Performs the incremental update on " (:GROUP (:FONT :FACE :I) "stream")
      " according to the difference set comprised by " (:GROUP (:FONT :FACE :I) "erases") ", "
      (:GROUP (:FONT :FACE :I) "moves") ", " (:GROUP (:FONT :FACE :I) "draws") ", "
      (:GROUP (:FONT :FACE :I) "erase-overlapping") ", and " (:GROUP (:FONT :FACE :I) "move-overlapping")
      ", which are values returned by " (:CL "compute-difference-set") ". " (:GROUP (:FONT :FACE :I) "position")
      " is a point object that represents the start position of the topmost output record that will be redisplayed."
      (:PAR) (:CL "incremental-redisplay") " can be called on any extended output stream." (:PAR))))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part VI: " "Extended Stream Input Facilities") :NAME (10) " " " "
   (:SECTION :TITLE ("22 " "Extended Stream Input") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "extended-input")
    (:PAR)
    "CLIM provides a stream-oriented input layer that is implemented on top of the sheet input architecture. The basic CLIM input stream protocol is based on the character input stream protocol proposal submitted to the ANSI Common Lisp committee by David Gray. This proposal was not approved by the committee, but has been implemented by most Lisp vendors."
    (:PAR)
    (:SECTION :TITLE ("22.1 " "Basic Input Streams") :KIND :SECTION :NAME (5 5 10) (:PAR)
     "CLIM provides an implementation of the basic input stream facilities (described in more detail in Appendix "
     (:REF :NAME "gray-streams")
     "), either by directly using the underlying Lisp implementation, or by implementing the facilities itself." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-input-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "This class provides an implementation of the CLIM's basic input stream protocol based on CLIM's input kernel. It defines a "
      (:CL "handle-event")
      " method for keystroke events and queues the resulting characters in a per-stream input buffer. Members of this class are mutable. "
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-read-char")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns the next character available in the " (:TERM "input stream") " " (:GROUP (:FONT :FACE :I) "stream")
      ", or " (:CL ":eof")
      " if the stream is at end-of-file. If no character is available this function will wait until one becomes available."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-read-char-no-hang")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:PAR) "Like " (:CL "stream-read-char") ", except that if no character is available the function returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-unread-char")) :PARAMS ((:I "stream character")) :KIND ("Generic Function"))
      (:PAR) "Places the character " (:GROUP (:FONT :FACE :I) "character") " back into the " (:TERM "input stream") " "
      (:GROUP (:FONT :FACE :I) "stream") "'s input buffer. The next call to " (:CL "read-char") " on "
      (:GROUP (:FONT :FACE :I) "stream")
      " will return the unread character. The character supplied must be the most recent character read from the stream."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-peek-char")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns the next character available in the " (:TERM "input stream") " " (:GROUP (:FONT :FACE :I) "stream")
      ". The character is not removed from the input buffer. Thus, the same character will be returned by a subsequent call to "
      (:CL "stream-read-char") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-listen")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:TERM "true") " if there is input available on the " (:TERM "input stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ", " (:TERM "false") " if not." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-read-line")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Reads and returns a string containing a line of text from the " (:TERM "input stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ", delimited by the " (:CODE "#\\Newline") " character." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-clear-input")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Clears any buffered input associated with the " (:TERM "input stream") " " (:GROUP (:FONT :FACE :I) "stream")
      ", and returns " (:TERM "false") "." (:PAR) " "))
    (:SECTION :TITLE ("22.2 " "Extended Input Streams") :KIND :SECTION :NAME (5 5 10) (:PAR)
     "In addition to the basic input stream protocol, CLIM defines an extended input stream protocol. This protocol extends the stream model to allow manipulation of non-character user gestures, such as pointer button presses. The extended input protocol provides the programmer with more control over input processing, including the options of specifying input wait timeouts and auxiliary input test functions."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "extended-input-stream")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class for CLIM extended input streams. This is a subclass of " (:CL "input-stream")
      ". If you want to create a new class that behaves like an extended input stream, it should be a subclass of "
      (:CL "extended-input-stream") ". All instantiable subclasses of " (:CL "extended-input-stream")
      " must obey the extended input stream protocol. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "extended-input-stream-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a CLIM "
      (:TERM "extended input stream") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":input-buffer")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":pointer")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":text-cursor")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "extended-input-stream")
      " must handle these initargs, which are used to specify, respectively, the input buffer, pointer, and text cursor for the extended input stream."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-extended-input-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "This class provides an implementation of the CLIM extended input stream protocol based on CLIM's input kernel. The extended input stream maintains the state of the display's pointing devices (such as a mouse) in pointer objects associated with the stream. It defines a "
      (:CL "handle-event")
      " methods for keystroke and pointer motion and button press events and updates the pointer object state and queues the resulting events in a per-stream input buffer."
      (:PAR) "Members of this class are mutable. " (:PAR) " ")
     (:SECTION :TITLE ("22.2.1 " "The Extended Input Stream Protocol") :KIND :SUBSECTION :NAME (2 5 5 10) (:PAR)
      "The following generic functions comprise the extended input stream protocol. All extended input streams must implement methods for these generic functions."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-input-buffer")) :PARAMS ((:I "stream")) :KIND ("Generic Function")))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf stream-input-buffer)")) :PARAMS ((:I "buffer stream")) :KIND
        ("Generic Function"))
       (:PAR)
       "The functions provide access to the stream's input buffer. Normally programs do not need to manipulate the input buffer directly. It is sometimes useful to cause several streams to share the same input buffer so that input that comes in on one of them is available to an input call on any of the streams. The input buffer must be vector with a fill pointer capable of holding general input gesture objects (such as characters and event objects)."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-pointer-position")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&key ") "pointer")) :KIND ("Generic Function"))
       (:PAR) "Returns the current position of the pointing device " (:GROUP (:FONT :FACE :I) "pointer") " for the "
       (:TERM "extended input stream") " " (:GROUP (:FONT :FACE :I) "stream") " as two values, the " (:MATH "x")
       " and " (:MATH "y") " positions in the stream's drawing surface coordinate system. If "
       (:GROUP (:FONT :FACE :I) "pointer") " is not supplied, it defaults to " (:CL "port-pointer")
       " of the stream's port." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf* stream-pointer-position)")) :PARAMS
        ((:I "x y stream " (:GROUP (:FONT :FACE :TT) "&key ") "pointer")) :KIND ("Generic Function"))
       (:PAR) "Sets the position of the pointing device for the " (:TERM "extended input stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " to " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       ", which are integers. " (:GROUP (:FONT :FACE :I) "pointer") " is as for " (:CL "stream-pointer-position") "."
       (:PAR) "For CLIM implementations that do not support " (:CL "setf*") ", the \"setter\" function for this is "
       (:CL "stream-set-pointer-position") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-set-input-focus")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "Sets the \"input focus\" to the " (:TERM "extended input stream") " " (:GROUP (:FONT :FACE :I) "stream")
       " by changing the value of " (:CL "port-keyboard-input-focus") " and returns the old input focus as its value."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-input-focus")) :PARAMS
        ((:I "(stream) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Temporarily gives the keyboard input focus to the " (:TERM "extended input stream") " "
       (:GROUP (:FONT :FACE :I) "stream")
       ". By default, an application frame gives the input focus to the window associated with " (:CL "frame-query-io")
       "." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
       " argument is not evaluated, and must be a symbol that is bound to a stream. If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-input*") " is used. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "*input-wait-test*")) :PARAMS ((:I)) :KIND ("Variable"))
       (:SIGNATURE :NAME ((:CL "*input-wait-handler*")) :PARAMS ((:I)) :KIND ("Variable"))
       (:SIGNATURE :NAME ((:CL "*pointer-button-press-handler*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
       "These three variables are used to hold the default values for the current input wait test, wait handler, and pointer button press handler. These variables are globally bound to "
       (:CL "nil") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "read-gesture")) :PARAMS
        ((:I (:GROUP (:FONT :FACE :TT) "&key ") "(stream " (:CL "*standard-input*")
          ")  timeout peek-p  (input-wait-test " (:CL "*input-wait-test*") ")  (input-wait-handler "
          (:CL "*input-wait-handler*") ")  (pointer-button-press-handler " (:CL "*pointer-button-press-handler*") ")"))
        :KIND ("Function"))
       (:PAR) "Calls " (:CL "stream-read-gesture") " on the " (:TERM "extended input stream") " "
       (:GROUP (:FONT :FACE :I) "stream")
       " and all of the other keyword arguments. These arguments are the same as for " (:CL "stream-read-gesture") "."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-read-gesture")) :PARAMS
        ((:I "stream  " (:GROUP (:FONT :FACE :TT) "&key ") "timeout peek-p  (input-wait-test "
          (:CL "*input-wait-test*") ")  (input-wait-handler " (:CL "*input-wait-handler*")
          ")  (pointer-button-press-handler " (:CL "*pointer-button-press-handler*") ")"))
        :KIND ("Generic Function"))
       (:PAR) "Returns the next gesture available in the " (:TERM "extended input stream") " "
       (:GROUP (:FONT :FACE :I) "stream")
       "; the gesture will be either a character or an event (such as a pointer button event). The input is not echoed."
       (:PAR) "If the user types an abort gesture (that is, a gesture that matches any of the gesture names in "
       (:CL "*abort-gestures*") "), then the " (:CL "abort-gesture") " condition will be signalled." (:PAR)
       "If the user types an accelerator gesture (that is, a gesture that matches any of the gesture names in "
       (:CL "*accelerator-gestures*") "), then the " (:CL "accelerator-gesture") " condition will be signalled." (:PAR)
       (:CL "stream-read-gesture") " works by invoking " (:CL "stream-input-wait") " on "
       (:GROUP (:FONT :FACE :I) "stream") ", " (:GROUP (:FONT :FACE :I) "input-wait-test") ", and "
       (:GROUP (:FONT :FACE :I) "timeout") ", and then processing the input, if there is any. " (:CL ":around")
       " methods on this generic function can be used to implement some sort of a gesture preprocessing mechanism on every gesture; CLIM's input editor will typically be implemented this way."
       (:PAR) (:GROUP (:FONT :FACE :I) "timeout") " is either " (:CL "nil")
       " or an integer that specifies the number of seconds that " (:CL "stream-read-gesture")
       " will wait for input to become available. If no input is available, " (:CL "stream-read-gesture")
       " will return two values, " (:CL "nil") " and " (:CL ":timeout") "." (:PAR) "If the boolean "
       (:GROUP (:FONT :FACE :I) "peek-p") " is " (:TERM "true")
       ", then the returned gesture will be left in the stream's input buffer." (:PAR)
       (:GROUP (:FONT :FACE :I) "input-wait-test")
       " is a function of one argument, the stream. The function should return " (:TERM "true")
       " when there is input to process, otherwise it should return " (:TERM "false")
       ". This argument will be passed on to " (:CL "stream-input-wait") ". " (:CL "stream-read-gesture") " will bind "
       (:CL "*input-wait-test*") " to " (:GROUP (:FONT :FACE :I) "input-wait-test") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "input-wait-handler") " is a function of one argument, the stream. It is called when "
       (:CL "stream-input-wait") " returns " (:TERM "false")
       " (that is, no input is available). This option can be used in conjunction with "
       (:GROUP (:FONT :FACE :I) "input-wait-test")
       " to handle conditions other than keyboard gestures, or to provide some sort of interactive behavior (such as highlighting applicable presentations). "
       (:CL "stream-read-gesture") " will bind " (:CL "*input-wait-handler*") " to "
       (:GROUP (:FONT :FACE :I) "input-wait-handler") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "pointer-button-press-handler")
       " is a function of two arguments, the stream and a pointer button press event. It is called when the user clicks a pointer button. "
       (:CL "stream-read-gesture") " will bind " (:CL "*pointer-button-press-handler*") " to "
       (:GROUP (:FONT :FACE :I) "pointer-button-press-handler") "." (:PAR) " "
       (:GROUP (:FONT :FACE :I) "input-wait-test") ", " (:GROUP (:FONT :FACE :I) "input-wait-handler") ", and "
       (:GROUP (:FONT :FACE :I) "pointer-button-press-handler") " have dynamic extent." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-input-wait")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&key ") "timeout input-wait-test")) :KIND ("Generic Function"))
       (:PAR) "Waits for input to become available on the " (:TERM "extended input stream") " "
       (:GROUP (:FONT :FACE :I) "stream") ". " (:GROUP (:FONT :FACE :I) "timeout") " and "
       (:GROUP (:FONT :FACE :I) "input-wait-test") " are as for " (:CL "stream-read-gesture") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "unread-gesture")) :PARAMS
        ((:I "gesture " (:GROUP (:FONT :FACE :TT) "&key ") "(stream " (:CL "*standard-input*") ")")) :KIND
        ("Function"))
       (:PAR) "Calls " (:CL "stream-unread-gesture") " on " (:GROUP (:FONT :FACE :I) "gesture") " and "
       (:GROUP (:FONT :FACE :I) "stream") ". These arguments are the same as for " (:CL "stream-unread-gesture") "."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-unread-gesture")) :PARAMS ((:I "stream gesture")) :KIND ("Generic Function"))
       (:PAR) "Places " (:GROUP (:FONT :FACE :I) "gesture") " back into the " (:TERM "extended input stream") " "
       (:GROUP (:FONT :FACE :I) "stream") "'s input buffer. The next call to " (:CL "stream-read-gesture")
       " request will return the unread gesture. The gesture supplied must be the most recent gesture read from the stream via "
       (:CL "read-gesture") "." (:PAR) " "))
     (:SECTION :TITLE ("22.2.2 " "Extended Input Stream Conditions") :KIND :SUBSECTION :NAME (2 5 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "*abort-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
       "A list of all of the gesture names that correspond to abort gestures. The exact global set of standard abort gestures is unspecified, but must include the "
       (:CL ":abort") " gesture name." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "abort-gesture")) :PARAMS ((:I)) :KIND ("Condition")) (:PAR)
       "This condition is signalled by " (:CL "read-gesture") " whenever an abort gesture (one of the gestures in "
       (:CL "*abort-gestures*") " is read from the user. This condition will handle the " (:CL ":event")
       " initarg, which is used to supply the event corresponding to the abort gesture." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "abort-gesture-event")) :PARAMS ((:I "condition")) :KIND ("Generic Function"))
       (:PAR) "Returns the event that cause the abort gesture condition to be signalled. " (:CL "condition")
       " is an object of type " (:CL "abort-gesture") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "*accelerator-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
       "A list of all of the gesture names that correspond to keystroke accelerators. The global value for this is "
       (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "accelerator-gesture")) :PARAMS ((:I)) :KIND ("Condition")) (:PAR)
       "This condition is signalled by " (:CL "read-gesture")
       " whenever an keystroke accelerator gesture (one of the gestures in " (:CL "*accelerator-gestures*")
       " is read from the user. This condition will handle the " (:CL ":event") " and the " (:CL ":numeric-argument")
       " initargs, which are used to supply the event corresponding to the abort gesture and the accumulated numeric argument (which defaults to 1)."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "accelerator-gesture-event")) :PARAMS ((:I "condition")) :KIND ("Generic Function"))
       (:PAR) "Returns the event that caused the accelerator gesture condition to be signalled. " (:CL "condition")
       " is an object of type " (:CL "accelerator-gesture") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "accelerator-gesture-numeric-argument")) :PARAMS ((:I "condition")) :KIND
        ("Generic Function"))
       (:PAR)
       "Returns the accumlated numeric argument (maintained by the input editor) at the time the accelerator gesture condition was signalled. "
       (:CL "condition") " is an object of type " (:CL "accelerator-gesture") "." (:PAR) " ")))
    (:SECTION :TITLE ("22.3 " "Gestures and Gesture Names" (:LABEL :NAME "gesture-names")) :KIND :SECTION :NAME
     (5 5 10) (:PAR) "A " (:CONCEPT "gesture")
     " is some sort of input action by the user, such as typing a character or clicking a pointer button. A "
     (:CONCEPT "keyboard gesture") " refers to those gestures that are input by typing something on the keyboard. A "
     (:CONCEPT "pointer gesture")
     " refers to those gestures that are input by doing something with the pointer, such as clicking a button." (:PAR)
     "A " (:CONCEPT "gesture name")
     " is a symbol that gives a name to a set of similar gestures. Gesture names are used in order to provide a level of abstraction above raw device events; greater portability can thus be achieved by avoiding referring directly to platform-dependent constructs, such as character objects that refer to a particular key on the keyboard. For example, the "
     (:CL ":complete") " gesture is used to name the gesture that causes the " (:CL "complete-input")
     " complete the current input string; on Genera, this may correspond to the Complete key on the keyboard (which generates a "
     (:CODE "#\\Complete")
     " character), but on a Unix workstation, it may correspond to some other key. Another example is " (:CL ":select")
     ", which is commonly used to indicate a left button click on the pointer." (:PAR)
     "Note that gesture names participate in a one-to-many mapping, that is, a single gesture name can name a group of physical gestures. For example, an "
     (:CL ":edit") " might include both a pointer button click and a key press." (:PAR) "CLIM uses " (:TERM "event")
     " objects to represent user gestures. Some of the more common events are those of the class "
     (:CL "pointer-button-event")
     ". Event objects store the sheet associated with the event, a timestamp, and the modifier key state (a quantity that indicates which modifier keys were held down on the keyboard at the time the event occurred). Pointer button event objects also store the pointer object, the button that was clicked on the pointer, the window the pointer was over and the "
     (:MATH "x") " and " (:MATH "y") " position within that window. Keyboard gestures store the key name." (:PAR)
     "In some contexts, the object used to represent a user gesture is referred to as an " (:CONCEPT "gesture object")
     ". An gesture object might be exactly the same as an event object, or might contain less information. For example, for a keyboard gesture that corresponds to a standard printing character, it may be enough to represent the gesture object as a character."
     (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "define-gesture-name")) :PARAMS
       ((:I "name type gesture-spec " (:GROUP (:FONT :FACE :TT) "&key ") "(unique " (:CL "t") ")")) :KIND ("Macro"))
      (:PAR) "Defines a new gesture named by the symbol " (:GROUP (:FONT :FACE :I) "name") ". "
      (:GROUP (:FONT :FACE :I) "type")
      " is the type of gesture being created, and must be one of the symbols described below. "
      (:GROUP (:FONT :FACE :I) "gesture-spec")
      " specifies the physical gesture that corresponds to the named gesture; its syntax depends on the value of "
      (:GROUP (:FONT :FACE :I) "type") ". " (:CL "define-gesture-name") " must expand into a call to "
      (:CL "add-gesture-name") "." (:PAR) "If " (:GROUP (:FONT :FACE :I) "unique") " is " (:TERM "true")
      ", all old gestures named by " (:GROUP (:FONT :FACE :I) "name") " are first removed. "
      (:GROUP (:FONT :FACE :I) "unique") " defaults to " (:CL "t") "." (:PAR) "None of the arguments to "
      (:CL "define-gesture-name") " is evaluated." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "add-gesture-name")) :PARAMS
       ((:I "name type gesture-spec " (:GROUP (:FONT :FACE :TT) "&key ") "unique")) :KIND ("Function"))
      (:PAR) "Adds a gesture named by the symbol " (:GROUP (:FONT :FACE :I) "name") " to the set of gesture names. "
      (:GROUP (:FONT :FACE :I) "type")
      " is the type of gesture being created, and must be one of the symbols described below. "
      (:GROUP (:FONT :FACE :I) "gesture-spec")
      " specifies the physical gesture that corresponds to the named gesture; its syntax depends on the value of "
      (:GROUP (:FONT :FACE :I) "type") "." (:PAR) "If " (:GROUP (:FONT :FACE :I) "unique") " is " (:TERM "true")
      ", all old gestures named by " (:GROUP (:FONT :FACE :I) "name") " are first removed. "
      (:GROUP (:FONT :FACE :I) "unique") " defaults to " (:CL "nil") "." (:PAR) "When "
      (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":keyboard") ", " (:GROUP (:FONT :FACE :I) "gesture-spec")
      " is a list of the form " (:GROUP (:FONT :FACE :I) "(key-name . modifier-key-names)") ". "
      (:GROUP (:FONT :FACE :I) "key-name") " is the name of a non-modifier key on the keyboard (see below). "
      (:GROUP (:FONT :FACE :I) "modifier-key-names") " is a (possibly empty) list of modifier key names ("
      (:CL ":shift") ", " (:CL ":control") ", " (:CL ":meta") ", " (:CL ":super") ", and " (:CL ":hyper") ")." (:PAR)
      "For the standard Common Lisp characters (the 95 ASCII printing characters including " (:CODE "#\\Space") "), "
      (:GROUP (:FONT :FACE :I) "key-name")
      " is the character object itself. For the other \"semi-standard\" characters, "
      (:GROUP (:FONT :FACE :I) "key-name") " is a keyword symbol naming the character (" (:CL ":newline") ", "
      (:CL ":linefeed") ", " (:CL ":return") ", " (:CL ":tab") ", " (:CL ":backspace") ", " (:CL ":page") ", and "
      (:CL ":rubout")
      "). CLIM implementations may extend the set of key names on a per-port basic, but should choose a port-specific package. For example, the Genera port might such gestures as include "
      (:CL "genera-clim:help") " and " (:CL "genera-clim:complete") "." (:PAR)
      "The names of the modifier keys have been chosen to be uniform across all platforms, even though not all platforms will have keys on the keyboard with these names. The per-port part of a CLIM implementation must simply choose a sensible mapping from the modifier key names to the names of the keys on the keyboard. For example, a CLIM implementation on the Macintosh might map "
      (:CL ":meta") " to the Command shift key, and " (:CL ":super") " to the Option shift key." (:PAR) "When "
      (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":pointer-button") ", " (:CL ":pointer-button-press") ", or "
      (:CL ":pointer-button-release") ", " (:GROUP (:FONT :FACE :I) "gesture-spec") " is a list of the form "
      (:GROUP (:FONT :FACE :I) "(button-name . modifier-key-names)") ". " (:GROUP (:FONT :FACE :I) "button")
      " is the name of a pointer button (" (:CL ":left") ", " (:CL ":middle") ", or " (:CL ":right") "), and "
      (:GROUP (:FONT :FACE :I) "modifier-key-names") " is as above." (:PAR)
      "CLIM implementations are permitted to have other values of " (:GROUP (:FONT :FACE :I) "type")
      " as an extension, such as " (:CL ":pointer-motion") " or " (:CL ":timer") "." (:PAR) "As an example, the "
      (:CL ":edit") " gesture name above could be defined as follows using " (:CL "define-gesture-name") ":" (:PAR)
      (:PRE "
(define-gesture-name :edit :pointer-button (:left :meta))
(define-gesture-name :edit :keyboard (#\\E :control))
")
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "delete-gesture-name")) :PARAMS ((:I "name")) :KIND ("Function")) (:PAR)
      "Removes the gesture named by the symbol " (:GROUP (:FONT :FACE :I) "name") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "event-matches-gesture-name-p")) :PARAMS ((:I "event gesture-name")) :KIND ("Function"))
      (:PAR) "Returns " (:TERM "true") " if the device event " (:GROUP (:FONT :FACE :I) "event")
      " \"matches\" the gesture named by " (:GROUP (:FONT :FACE :I) "gesture-name") "." (:PAR)
      "For pointer button events, the event matches the gesture name when the pointer button from the event matches the name of the pointer button one of the gesture specifications named by "
      (:GROUP (:FONT :FACE :I) "gesture-name")
      ", and the modifier key state from the event matches the names of the modifier keys in that same gesture specification."
      (:PAR)
      "For keyboard events, the event matches the gesture name when the key name from the event matches the key name of one of the gesture specifications named by "
      (:GROUP (:FONT :FACE :I) "gesture-name")
      ", and the modifier key state from the event matches the names of the modifier keys in that same gesture specification."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "modifier-state-matches-gesture-name-p")) :PARAMS ((:I "modifier-state gesture-name"))
       :KIND ("Function"))
      (:PAR) "Returns " (:TERM "true") " if the modifier key state from the device event "
      (:GROUP (:FONT :FACE :I) "event")
      " matches the names of the modifier keys in one of the gesture specifications named by "
      (:GROUP (:FONT :FACE :I) "gesture-name") "." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "Note that none of the functions above take a port argument. This is because CLIM implicitly assumes that the canonical set of gesture names is the same on every port, and only the mappings differ from port to port. Some ports may define additional gesture names, but they will simply not be mapped on other ports. Is this a reasonable assumption? --- SWM")
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-modifier-state")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "modifiers"))
       :KIND ("Function"))
      (:PAR)
      "Given a list of modifier state names, this creates an integer that serves as a modifier key state. The legal modifier state names are "
      (:CL ":shift") ", " (:CL ":control") ", " (:CL ":meta") ", " (:CL ":super") ", and " (:CL ":hyper") "." (:PAR)
      " ")
     (:SECTION :TITLE ("22.3.1 " "Standard Gesture Names") :KIND :SUBSECTION :NAME (1 5 5 10) (:PAR)
      "Every CLIM implementation must provide a standard set of gesture names that correspond to a common set of gestures. These gesture names must have a meaningful mapping for every port type."
      (:PAR) "Here are the required, standard keyboard gesture names:" (:PAR)
      (:UL
       (:LI (:CL ":abort")
        "---corresponds to gestures that cause the currently running application to be aborted back to top-level. On Genera, this will match the "
        (:CODE "#\\Abort") " character. On other systems, this may match the event corresponding to typing "
        (:GROUP (:FONT :FACE :TT) "Control-C") "." (:PAR))
       (:LI (:CL ":clear-input")
        "---corresponds to gestures that cause the current input buffer to be cleared. On Genera, this will match the "
        (:CODE "#\\Clear-Input") " character. On other systems, this may match the event corresponding to typing "
        (:GROUP (:FONT :FACE :TT) "Control-U") "." (:PAR))
       (:LI (:CL ":complete")
        "---corresponds to the gestures that tell the completion facility to complete the current input. On most systems, this will typically match the "
        (:CODE "#\\Tab") " or " (:CODE "#\\Escape") " character. On Genera, this will match the " (:CODE "#\\Complete")
        " character as well." (:PAR))
       (:LI (:CL ":help") "---corresponds to the gestures that tell " (:CL "accept")
        " and the completion facility to display a help message. On most systems, this will typically match the event corresponding to typing "
        (:GROUP (:FONT :FACE :TT) "Control-/") ". On Genera, this will match the " (:CODE "#\\Help")
        " character as well." (:PAR))
       (:LI (:CL ":possibilities")
        "---corresponds to the gestures that tell the completion facility to display the current set of possible completions. On most systems, this will typically match the event corresponding to typing "
        (:GROUP (:FONT :FACE :TT) "Control-?") ". "))
      (:PAR) "Here are the required, standard pointer gesture names:" (:PAR)
      (:UL
       (:LI (:GROUP (:CL ":select"))
        "---corresponds to the gesture that is used to \"select\" the object being pointed to with the pointer. Typically, this will correspond to the left button on the pointer."
        (:PAR))
       (:LI (:GROUP (:CL ":describe"))
        "---corresponds to the gesture that is used to \"describe\" or display some sort of documentation on the object being pointed to with the pointer. Typically, this will correspond to the middle button on the pointer."
        (:PAR))
       (:LI (:GROUP (:CL ":menu"))
        "---corresponds to the gesture that is used to display a menu of all possible operation on the object being pointed to with the pointer. Typically, this will correspond to the right button on the pointer."
        (:PAR))
       (:LI (:GROUP (:CL ":edit"))
        "---corresponds to the gesture that is used to \"edit\" the object being pointed to with the pointer. Typically, this will correspond to the left button on the pointer with some modifier key held down (such as the "
        (:CL ":meta") " key)." (:PAR))
       (:LI (:GROUP (:CL ":delete"))
        "---corresponds to the gesture that is used to \"delete\" the object being pointed to with the pointer. Typically, this will correspond to the middle button on the pointer with some modifier key held down (such as the "
        (:CL ":shift") " key). "))
      (:PAR) " "))
    (:SECTION :TITLE ("22.4 " "The Pointer Protocol") :KIND :SECTION :NAME (5 5 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a pointing device. If you want to create a new class that behaves like a pointer, it should be a subclass of "
      (:CL "pointer") ". All instantiable subclasses of " (:CL "pointer")
      " must obey the pointer protocol. Members of this class are mutable. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointerp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "pointer")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":port")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "The " (:CL ":port")
      " initarg is used to specify the port with which the pointer is associated." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-pointer")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that implements a pointer." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-sheet")) :PARAMS ((:I "pointer")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf pointer-sheet)")) :PARAMS ((:I "sheet pointer")) :KIND ("Generic Function"))
      (:PAR) "Returns (or sets) the sheet over which the " (:TERM "pointer") " " (:GROUP (:FONT :FACE :I) "pointer")
      " is located." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-button-state")) :PARAMS ((:I "pointer")) :KIND ("Generic Function"))
      (:PAR) "Returns the current state of the buttons of the " (:TERM "pointer") " "
      (:GROUP (:FONT :FACE :I) "pointer") " as an integer. This will be a mask consisting of the " (:CL "logior")
      " of " (:CL "+pointer-left-button+") ", " (:CL "+pointer-middle-button+") ", and " (:CL "+pointer-right-button+")
      "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-position")) :PARAMS ((:I "pointer")) :KIND ("Generic Function")) (:PAR)
      "Returns the " (:MATH "x") " and " (:MATH "y") " position of the " (:TERM "pointer") " "
      (:GROUP (:FONT :FACE :I) "pointer") " as two values." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf* pointer-position)")) :PARAMS ((:I "x y pointer")) :KIND ("Generic Function"))
      (:PAR) "Sets the " (:MATH "x") " and " (:MATH "y") " position of the " (:TERM "pointer") " "
      (:GROUP (:FONT :FACE :I) "pointer") " to the specified position." (:PAR)
      "For CLIM implementations that do not support " (:CL "setf*") ", the \"setter\" function for this is "
      (:CL "pointer-set-position") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-cursor")) :PARAMS ((:I "pointer")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf pointer-cursor)")) :PARAMS ((:I "cursor pointer")) :KIND ("Generic Function"))
      (:PAR)
      "A pointer object usually has a visible cursor associated with it. These functions return (or set) the cursor associated with the "
      (:TERM "pointer") " " (:GROUP (:FONT :FACE :I) "pointer") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "port")) :PARAMS ((:I "(pointer " (:CL "standard-pointer") ")")) :KIND ("Method"))
      (:PAR) "Returns the port with which " (:GROUP (:FONT :FACE :I) "pointer") " is associated." (:PAR) " "))
    (:SECTION :TITLE ("22.5 " "Pointer Tracking") :KIND :SECTION :NAME (5 5 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "tracking-pointer")) :PARAMS
       ((:I "(sheet " (:GROUP (:FONT :FACE :TT) "&key ")
         "pointer multiple-window  transformp context-type highlight)  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "The " (:CL "tracking-pointer")
      " macro provides a general means for running code while following the position of a pointing device, and monitoring for other input events. The programmer supplies code (the clauses in "
      (:GROUP (:FONT :FACE :I) "body") ") to be run upon the occurrence of any of the following types of events:"
      (:PAR)
      (:UL (:LI "Motion of the pointer" (:PAR)) (:LI "Motion of the pointer over a presentation" (:PAR))
       (:LI "Clicking or releasing a pointer button" (:PAR))
       (:LI "Clicking or releasing a pointer button while the pointer is over a presentation" (:PAR))
       (:LI "Keyboard event (typing a character) "))
      (:PAR) "The " (:GROUP (:FONT :FACE :I) "sheet")
      " argument is not evaluated, and must be a symbol that is bound to an input sheet or stream. If "
      (:GROUP (:FONT :FACE :I) "sheet") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) "The "
      (:GROUP (:FONT :FACE :I) "pointer")
      " argument specifies a pointer to track. It defaults to the primary pointer for the sheet, "
      (:CL "(port-pointer (port " (:GROUP (:FONT :FACE :I) "sheet") "))") "." (:PAR) "When the boolean "
      (:GROUP (:FONT :FACE :I) "multiple-windows") " is " (:TERM "true")
      ", then the pointer will be tracked across multiple windows, otherwise is will be tracked only in the window corresponding to "
      (:GROUP (:FONT :FACE :I) "sheet") "." (:PAR) "When the boolean " (:GROUP (:FONT :FACE :I) "transformp") " is "
      (:TERM "true") ", then the coordinates supplied to the " (:CL ":pointer-motion")
      " clause will be in the \"user\" coordinate system rather than in stream coordinates, that is, the medium's transformation will be applied to the coordinates."
      (:PAR) (:GROUP (:FONT :FACE :I) "context-type")
      " is used to specify the presentation type of presentations that will be \"visible\" to the tracking code for purposes of highlighting and for the "
      (:CL ":presentation") ", " (:CL ":presentation-button-press") ", and " (:CL ":presentation-button-release")
      " clauses. Supplying " (:GROUP (:FONT :FACE :I) "context-type") " is only useful when "
      (:GROUP (:FONT :FACE :I) "sheet") " is an output recording stream. " (:GROUP (:FONT :FACE :I) "context-type")
      " defaults to " (:CL "t") ", meaning that all presentations are visible." (:PAR) "When "
      (:GROUP (:FONT :FACE :I) "highlight") " is " (:TERM "true") ", " (:CL "tracking-pointer")
      " will highlight applicable presentations as the pointer is positioned over them. " (:GROUP "highlight")
      " defaults to " (:TERM "true") " when any of the " (:CL ":presentation") ", " (:CL ":presentation-button-press")
      ", or " (:CL ":presentation-button-release") " clauses is supplied, otherwise it defaults to " (:TERM "false")
      ". See Chapter " (:REF :NAME "output-recording") " for a complete discussion of presentations." (:PAR)
      "The body of " (:CL "tracking-pointer") " consists of a list of clauses. Each clause is of the form " (:BR) " "
      (:GROUP (:FONT :FACE :I) "(clause-keyword arglist . clause-body)") " " (:BR)
      " and defines a local function to be run upon occurrence of each type of event. The possible values for "
      (:GROUP (:FONT :FACE :I) "clause-keyword") " and the associated " (:GROUP (:FONT :FACE :I) "arglist") " are:"
      (:PAR)
      (:UL
       (:LI
        (:GROUP (:CL ":pointer-motion") " "
         (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "window x y)"))
        " " (:BR) " Defines a clause to run whenever the pointer moves. In the clause, "
        (:GROUP (:FONT :FACE :I) "window") " is bound to the window in which the motion occurred, and "
        (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
        " to the coordinates of the pointer. (See the keyword argument " (:CL ":transformp")
        " below for a description of the coordinate system in which " (:GROUP (:FONT :FACE :I) "x") " and "
        (:GROUP (:FONT :FACE :I) "y") " are expressed.)" (:PAR))
       (:LI
        (:GROUP (:CL ":presentation") " "
         (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "presentation window x y)"))
        " " (:BR)
        " Defines a clause to run whenever the pointer moves over a presentation of the desired type. (See the keyword argument "
        (:CL ":context-type") " above for a description of how to specify the desired type.) In the clause, "
        (:GROUP (:FONT :FACE :I) "presentation") " is bound to the presentation, " (:GROUP (:FONT :FACE :I) "window")
        " to the window in which the motion occurred, and " (:GROUP (:FONT :FACE :I) "x") " and "
        (:GROUP (:FONT :FACE :I) "y") " to the coordinates of the pointer. (See the keyword argument "
        (:CL ":transformp") " above for a description of the coordinate system in which " (:GROUP (:FONT :FACE :I) "x")
        " and " (:GROUP (:FONT :FACE :I) "y") " are expressed.)" (:PAR) "When both " (:CL ":presentation") " and "
        (:CL ":pointer-motion") " clauses are provided, the two clauses are mutually exclusive. The "
        (:CL ":presentation") " clause will run only if the pointer is over an applicable presentation, otherwise the "
        (:CL ":pointer-motion") " clause will run." (:PAR))
       (:LI
        (:GROUP (:CL ":pointer-button-press") " "
         (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "event x y)"))
        " " (:BR) " Defines a clause to run whenever a pointer button is pressed. In the clause, "
        (:GROUP (:FONT :FACE :I) "event")
        " is bound to the pointer button press event. (The window and the coordinates of the pointer are part of "
        (:GROUP (:FONT :FACE :I) "event") ".)" (:PAR) (:GROUP (:FONT :FACE :I) "x") " and "
        (:GROUP (:FONT :FACE :I) "y") " are the transformed " (:MATH "x") " and " (:MATH "y")
        " positions of the pointer. These will be different from " (:CL "pointer-event-x") " and "
        (:CL "pointer-event-y") " if the user transformation is not the identity transformation." (:PAR))
       (:LI
        (:GROUP (:CL ":presentation-button-press") " "
         (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "presentation event x y)"))
        " " (:BR)
        " Defines a clause to run whenever the pointer button is pressed while the pointer is over a presentation of the desired type. (See the keyword argument "
        (:CL ":context-type") " below for a description of how to specify the desired type.) In the clause, "
        (:GROUP (:FONT :FACE :I) "presentation") " is bound to the presentation, and "
        (:GROUP (:FONT :FACE :I) "event")
        " to the pointer button press event. (The window and the stream coordinates of the pointer are part of "
        (:GROUP (:FONT :FACE :I) "event") ".) " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
        " are as for the " (:CL ":pointer-button-press") " clause." (:PAR) "When both "
        (:CL ":presentation-button-press") " and " (:CL ":pointer-button-press")
        " clauses are provided, the two clauses are mutually exclusive. The " (:CL ":presentation-button-press")
        " clause will run only if the pointer is over an applicable presentation, otherwise the "
        (:CL ":pointer-button-press") " clause will run." (:PAR))
       (:LI
        (:GROUP (:CL ":pointer-button-release") " "
         (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "event x y)"))
        " " (:BR) " Defines a clause to run whenever a pointer button is released. In the clause, "
        (:GROUP (:FONT :FACE :I) "event")
        " is bound to the pointer button release event. (The window and the coordinates of the pointer are part of "
        (:GROUP (:FONT :FACE :I) "event") ".)" (:PAR) (:GROUP (:FONT :FACE :I) "x") " and "
        (:GROUP (:FONT :FACE :I) "y") " are the transformed " (:MATH "x") " and " (:MATH "y")
        " positions of the pointer. These will be different from " (:CL "pointer-event-x") " and "
        (:CL "pointer-event-y") " if the user transformation is not the identity transformation." (:PAR))
       (:LI
        (:GROUP (:CL ":presentation-button-release") " "
         (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "presentation event x y)"))
        " " (:BR)
        " Defines a clause to run whenever a pointer button is released while the pointer is over a presentation of the desired type. (See the keyword argument "
        (:CL ":context-type") " below for a description of how to specify the desired type.) In the clause, "
        (:GROUP (:FONT :FACE :I) "presentation") " is bound to the presentation, and "
        (:GROUP (:FONT :FACE :I) "event")
        " to the pointer button release event. (The window and the stream coordinates of the pointer are part of "
        (:GROUP (:FONT :FACE :I) "event") ".) " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
        " are as for the " (:CL ":pointer-button-release") " clause." (:PAR) "When both "
        (:CL ":presentation-button-release") " and " (:CL ":pointer-button-release")
        " clauses are provided, the two clauses are mutually exclusive. The " (:CL ":presentation-button-release")
        " clause will run only if the pointer is over an applicable presentation, otherwise the "
        (:CL ":pointer-button-release") " clause will run." (:PAR))
       (:LI (:GROUP (:CL ":keyboard") " " (:GROUP (:FONT :FACE :I) "(" (:GROUP (:FONT :FACE :TT) "&key ") "gesture)"))
        " " (:BR) " Defines a clause to run whenever a character is typed on the keyboard. In the clause, "
        (:GROUP (:FONT :FACE :I) "gesture")
        " is bound to the keyboard gesture corresponding to the character typed. "))
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "drag-output-record")) :PARAMS
       ((:I "stream output-record  " (:GROUP (:FONT :FACE :TT) "&key ")
         "repaint erase feedback finish-on-release  multiple-window"))
       :KIND ("Generic Function"))
      (:PAR) "Enters an interaction mode in which the user moves the pointer and "
      (:GROUP (:FONT :FACE :I) "output-record") " \"follows\" the pointer by being dragged on the "
      (:TERM "output recording stream") " " (:GROUP (:FONT :FACE :I) "stream")
      ". By default, the dragging is accomplished by erasing the output record from its previous position and redrawing at the new position. "
      (:GROUP (:FONT :FACE :I) "output-record") " remains in the output history of " (:GROUP (:FONT :FACE :I) "stream")
      " at its final position." (:PAR) "The returned values are the final " (:MATH "x") " and " (:MATH "y")
      " position of the pointer." (:PAR) "The boolean " (:GROUP (:FONT :FACE :I) "repaint")
      " allows the programmer to control the appearance of windows as the pointer is dragged. If "
      (:GROUP (:FONT :FACE :I) "repaint") " is " (:TERM "true")
      " (the default), displayed contents of windows are not disturbed as the output record is dragged over them (that is, those regions of the screen are repainted). If it is "
      (:TERM "false") ", then no repainting is done as the output record is dragged." (:PAR)
      (:GROUP (:FONT :FACE :I) "erase")
      " allows the programmer to identify a function that will be called to erase the output record as it is dragged. It must be a function of two arguments, the output record to erase and the stream; it has dynamic extent. The default is "
      (:CL "erase-output-record") "." (:PAR) (:GROUP (:FONT :FACE :I) "feedback")
      " allows the programmer to identify a \"feedback\" function. " (:GROUP (:FONT :FACE :I) "feedback")
      " must be a is a function of seven arguments: the output record, the stream, the initial " (:MATH "x") " and "
      (:MATH "y") " position of the pointer, the current " (:MATH "x") " and " (:MATH "y")
      " position of the pointer, and a drawing argument (either " (:CL ":erase") " or " (:CL ":draw")
      "). It has dynamic extent. The default is " (:CL "nil")
      ", meaning that the feedback behavior will be for the output record to track the pointer. (The "
      (:GROUP (:FONT :FACE :I) "feedback")
      " argument is used when the programmer desires more complex feedback behavior, such as drawing a \"rubber band\" line as the user moves the mouse.) Note that if "
      (:GROUP (:FONT :FACE :I) "feedback") " is supplied, " (:GROUP (:FONT :FACE :I) "erase") " is ignored." (:PAR)
      "If the boolean " (:GROUP (:FONT :FACE :I) "finish-on-release") " is " (:TERM "false") " (the default), "
      (:CL "drag-output-record") " is exited when the user presses a pointer button. When it is " (:TERM "true") ", "
      (:CL "drag-output-record") " is exited when the user releases the pointer button currently being held down."
      (:PAR) (:GROUP (:FONT :FACE :I) "multiple-window") " is as for " (:CL "tracking-pointer") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "dragging-output")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "repaint finish-on-release multiple-window)  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Evaluates " (:GROUP (:FONT :FACE :I) "body") " inside of " (:CL "with-output-to-output-record")
      " to produce an output record for the stream " (:GROUP (:FONT :FACE :I) "stream") ", and then invokes "
      (:CL "drag-output-record") " on the record in order to drag the output. The output record is not inserted into "
      (:GROUP (:FONT :FACE :I) "stream") "'s output history." (:PAR) "The returned values are the final " (:MATH "x")
      " and " (:MATH "y") " position of the pointer." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to an " (:TERM "output recording stream")
      " stream. If " (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-output*")
      " is used. " (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "repaint") ", " (:GROUP (:FONT :FACE :I) "finish-on-release") ", and "
      (:GROUP (:FONT :FACE :I) "multiple-window") " are as for " (:CL "drag-output-record") "." (:PAR))))
   " "
   (:SECTION :TITLE ("23 " "Presentation Types") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "presentation-types")
    (:PAR)
    (:SECTION :TITLE ("23.1 " "Overview of Presentation Types") :KIND :SECTION :NAME (8 5 10) (:PAR)
     "The core around which the CLIM application user interface model is built is the concept of the application-defined user interface data type. Each application has its own set of semantically significant user interface entities; a CAD program for designing circuits has its various kinds of components (gates, resistors, and so on), while a database manager has its relations and field types. These entities have to be displayed to the user (possibly in more than one displayed representation) and the user has to be able to interact with and specify the entities via pointer gestures and keyboard input. Frequently each user interface entity has a corresponding Lisp data type (such as an application-specific structure or CLOS class definition), but this is not always the case. The data representation for an interaction entity may be a primitive Lisp data type. In fact, it is possible for several different user interface entities to use the same Lisp data type for their internal representation, for example, building floor numbers and employee vacation day totals could both be represented internally as integers."
     (:PAR)
     "CLIM provides a framework for defining the appearance and behavior of these user interface entities via the "
     (:CONCEPT "presentation type")
     " mechanism. A presentation type can be thought of as a CLOS class that has some additional functionality pertaining to its roles in the user interface of an application. By defining a presentation type the application programmer defines all of the user interface components of the entity:"
     (:PAR)
     (:UL (:LI "Its displayed representation, textual or graphical" (:PAR))
      (:LI "Textual representation, for user input via the keyboard" (:PAR))
      (:LI "Pointer sensitivity, for user input via the pointer "))
     (:PAR)
     "In other words, by defining a presentation type, the application programmer describes in one place all the information about an object necessary to display it to the user and interact with the user for object input."
     (:PAR)
     "The set of presentation types forms a type lattice, an extension of the Common Lisp CLOS type lattice. When a new presentation type is defined as a subtype of another presentation type it inherits all the attributes of the supertype except those explicitly overridden in the definition."
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "Describe what a presentation type is more exactly. What is a parameterized presentation type? Why do we want them? Why are they in a lattice? How do they relate to CL types and CLOS classes? What exactly gets inherited? --- SWM")
     (:PAR) " ")
    (:SECTION :TITLE ("23.2 " "Presentations") :KIND :SECTION :NAME (8 5 10) (:PAR) "A " (:CONCEPT "presentation")
     " is a special kind of output record that remembers not only output, but the object associated with the output and the semantic type associated with that object."
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "Describe exactly what a presentation is. What does it mean for presentations to be nested? --- SWM")
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "presentation")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a presentation. If you want to create a new class that behaves like a presentation, it should be a subclass of "
      (:CL "presentation") ". All instantiable subclasses of " (:CL "presentation")
      " must obey the presentation protocol. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "presentationp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "presentation")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-presentation")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable output record class that represents presentations. " (:CL "present")
      " normally creates output records of this class. Members of this class are mutable. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":object")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":type")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":view")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":single-box")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":modifier")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "All presentation classes must handle these five initargs, which are used to specify, respectively, the object, type, view, single-box, and modifier components of a presentation."
      (:PAR) " ")
     (:SECTION :TITLE ("23.2.1 " "The Presentation Protocol") :KIND :SUBSECTION :NAME (1 8 5 10) (:PAR)
      "The following functions comprise the presentation protocol. All classes that inherit from " (:CL "presentation")
      " must implement methods for these generic functions." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "presentation-object")) :PARAMS ((:I "presentation")) :KIND ("Generic Function"))
       (:PAR) "Returns the object associated with the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf presentation-object)")) :PARAMS ((:I "object presentation")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the object associated with the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation") " to " (:GROUP (:FONT :FACE :I) "object") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "presentation-type")) :PARAMS ((:I "presentation")) :KIND ("Generic Function"))
       (:PAR) "Returns the presentation type associated with the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf presentation-type)")) :PARAMS ((:I "type presentation")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the object associated with the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation") " to " (:GROUP (:FONT :FACE :I) "object") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-single-box")) :PARAMS ((:I "presentation")) :KIND ("Generic Function"))
       (:PAR) "Returns the \"single box\" attribute of the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation")
       ", which controls how the presentation is highlighted and when it is sensitive. This will be one of four values:"
       (:PAR)
       (:UL
        (:LI (:CL "nil")
         " (the default)---if the pointer is pointing at a visible piece of the output that was drawn as part of the presentation, then it is considered to be pointing at the presentation. The presentation is highlighted by highlighting each visible part of the output that was drawn as part of the presentation."
         (:PAR))
        (:LI (:CL "t")
         "---if the pointer is inside the bounding rectangle of the presentation, it is considered to be pointing at the presentation. The presentation is highlighted by drawing a thin border around the bounding rectangle."
         (:PAR))
        (:LI (:CL ":position") "---like " (:CL "t")
         " for determining whether the pointer is pointing at the presentation, but like " (:CL "nil")
         " for highlighting." (:PAR))
        (:LI (:CL ":highlighting") "---like " (:CL "nil")
         " for determining whether the pointer is pointing at the presentation, but like " (:CL "t")
         " for highlighting. "))
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf presentation-single-box)")) :PARAMS ((:I "single-box presentation")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the \"single box\" attribute of the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation") " to " (:GROUP (:FONT :FACE :I) "single-box") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-modifier")) :PARAMS ((:I "presentation")) :KIND ("Generic Function"))
       (:PAR) "Returns the \"modifier\" associated with the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation")
       ". The modifier is some sort of object that describes how the presentation object might be modified. For example, it might be a function of one argument (the new value) that can be called in order to store a new value for "
       (:GROUP (:FONT :FACE :I) "object") " after a user somehow \"edits\" the presentation." (:PAR) " ")))
    (:SECTION :TITLE ("23.3 " "Presentation Types") :KIND :SECTION :NAME (8 5 10) (:PAR)
     "The type associated with a presentation is specified with a " (:CONCEPT "presentation type specifier")
     ", an object matching one of the following three patterns: " (:BR) " "
     (:TABULAR
      (:TR
       (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
        (:GROUP "  " (:GROUP (:FONT :FACE :I) "name") " ")))
      (:TR
       (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
        (:GROUP "  " (:CL "(" (:GROUP (:FONT :FACE :I) "name") " " (:GROUP (:FONT :FACE :I) "parameters...") ")")
         " ")))
      (:TR
       (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
        (:GROUP "  "
         (:CL "(("
              (:GROUP (:FONT :FACE :I) "name")
              " "
              (:GROUP (:FONT :FACE :I) "parameters...")
              ") "
              (:GROUP (:FONT :FACE :I) "options...")
              ")")
         " "))))
     (:PAR) "Note that " (:GROUP (:FONT :FACE :I) "name")
     " can be either a symbol that names a presentation type or a CLOS class object (but not a " (:CL "built-in-class")
     " object), in order to support anonymous CLOS classes." (:PAR) "The " (:GROUP (:FONT :FACE :I) "parameters")
     " \"parameterize\" the type, just as in a Common Lisp type specifier. The function " (:CL "presentation-typep")
     " uses the parameters to check object membership in a type. Adding parameters to a presentation type specifier produces a subtype, which contains some, but not necessarily all, of the objects that are members of the unparameterized type. Thus the parameters can turn off the sensitivity of some presentations that would otherwise be sensitive."
     (:PAR) " The " (:GROUP (:FONT :FACE :I) "options")
     " are alternating keywords and values that affect the use or appearance of the presentation, but not its semantic meaning. The "
     (:GROUP (:FONT :FACE :I) "options")
     " have no effect on presentation sensitivity. (A programmer could choose to make a tester in a translator examine options, but this is not standard practice.) The standard option "
     (:CL ":description") " is accepted by all types; if it is a non-" (:CL "nil")
     " value, then the value must be a string that describes the type and overrides the description supplied by the type's definition."
     (:PAR) "Every presentation type is associated with a CLOS class. If " (:GROUP (:FONT :FACE :I) "name")
     " is a class object or the name of a class, and that class is not a " (:CL "built-in-class")
     ", that class is the associated class. Otherwise, " (:CL "define-presentation-type")
     " defines a class with metaclass " (:CL "presentation-type-class")
     " and superclasses determined by the presentation type definition. This class is not named "
     (:GROUP (:FONT :FACE :I) "name") ", since that could interfere with built-in Common Lisp types such as "
     (:CL "and") ", " (:CL "member") ", and " (:CL "integer") ". " (:CL "class-name") " of this class returns a list "
     (:CL "(presentation-type " (:GROUP (:FONT :FACE :I) "name") ")") ". " (:CL "presentation-type-class")
     " is a subclass of " (:CL "standard-class") "." (:PAR)
     "Implementations are permitted to require programmers to evaluate the " (:CL "defclass")
     " form first in the case when the same name is used in both a " (:CL "defclass") " and a "
     (:CL "define-presentation-type") "." (:PAR)
     "Every CLOS class (except for built-in classes) is a presentation type, as is its name. If it has not been defined with "
     (:CL "define-presentation-type") ", it allows no parameters and no options." (:PAR)
     (:CONCEPT "Presentation type inheritance")
     " is used both to inherit methods (\"what parser should be used for this type?\"), and to establish the semantics for the type (\"what objects are sensitive in this input context?\"). Inheritance of methods is the same as in CLOS and thus depends only on the type name, not on the parameters and options."
     (:PAR)
     "During presentation method combination, presentation type inheritance arranges to translate the parameters of a subtype into a new set of parameters for its supertype, and translates the options of the subtype into a new set of options for the supertype."
     (:PAR) " "
     (:SECTION :TITLE ("23.3.1 " "Defining Presentation Types") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-presentation-type")) :PARAMS
        ((:I "name parameters  " (:GROUP (:FONT :FACE :TT) "&key ")
          "options inherit-from description history  parameters-are-types"))
        :KIND ("Macro"))
       (:PAR) "Defines a presentation type whose name is the symbol or class " (:GROUP (:FONT :FACE :I) "name")
       " and whose parameters are specified by the lambda-list " (:GROUP (:FONT :FACE :I) "parameters")
       ". These parameters are visible within " (:GROUP (:FONT :FACE :I) "inherit-from")
       " and within the methods created with " (:CL "define-presentation-method")
       ". For example, the parameters are used by " (:CL "presentation-typep") " and " (:CL "presentation-subtypep")
       " methods to refine their tests for type inclusion." (:PAR) (:GROUP (:FONT :FACE :I) "options")
       " is a list of option specifiers. It defaults to " (:CL "nil")
       ". An option specifier is either a symbol or a list (" (:GROUP (:FONT :FACE :I) "symbol") " "
       (:GROUP (:FONT :FACE :TT) "&optional ") " " (:GROUP (:FONT :FACE :I) "default") " "
       (:GROUP (:FONT :FACE :I) "supplied-p") " " (:GROUP (:FONT :FACE :I) "presentation-type") " "
       (:GROUP (:FONT :FACE :I) "accept-options") "), where " (:GROUP (:FONT :FACE :I) "symbol") ", "
       (:GROUP (:FONT :FACE :I) "default") ", and " (:GROUP (:FONT :FACE :I) "supplied-p")
       " are as in a normal lambda-list. If " (:GROUP (:FONT :FACE :I) "presentation-type") " and "
       (:GROUP (:FONT :FACE :I) "accept-options")
       " are present, they specify how to accept a new value for this option from the user. "
       (:GROUP (:FONT :FACE :I) "symbol") " can also be specified in the (" (:GROUP (:FONT :FACE :I) "keyword") " "
       (:GROUP (:FONT :FACE :I) "variable") ") form allowed for Common Lisp lambda lists. "
       (:GROUP (:FONT :FACE :I) "symbol") " is a variable that is visible within "
       (:GROUP (:FONT :FACE :I) "inherit-from") " and within most of the methods created with "
       (:CL "define-presentation-method") ". The keyword corresponding to " (:GROUP (:FONT :FACE :I) "symbol")
       " can be used as an option in the third form of a presentation type specifier. An option specifier for the standard option "
       (:CL ":description") " is automatically added to " (:GROUP (:FONT :FACE :I) "options")
       " if an option with that keyword is not present, however it does not produce a visible variable binding." (:PAR)
       "Unsupplied optional or keyword parameters default to " (:CL "*") " (as in " (:CL "deftype")
       ") if no default is specified in " (:GROUP (:FONT :FACE :I) "parameters") ". Unsupplied options default to "
       (:CL "nil") " if no default is specified in " (:GROUP (:FONT :FACE :I) "options") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "inherit-from")
       " is a form that evaluates to a presentation type specifier for another type from which the new type inherits. "
       (:GROUP (:FONT :FACE :I) "inherit-from") " can access the parameter variables bound by the "
       (:GROUP (:FONT :FACE :I) "parameters") " lambda list and the option variables specified by "
       (:GROUP (:FONT :FACE :I) "options") ". If " (:GROUP (:FONT :FACE :I) "name")
       " is or names a CLOS class (other than a " (:CL "built-in-class") "), then "
       (:GROUP (:FONT :FACE :I) "inherit-from") " must specify the class's direct superclasses (using " (:CL "and")
       " to specify multiple inheritance). It is useful to do this when you want to parameterize previously defined CLOS classes."
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "inherit-from") " is unsupplied, it defaults as follows: If "
       (:GROUP (:FONT :FACE :I) "name")
       " is or names a CLOS class, then the type inherits from the presentation type corresponding to the direct superclasses of that CLOS class (using "
       (:CL "and") " to specify multiple inheritance). Otherwise, the type named by " (:GROUP (:FONT :FACE :I) "name")
       " inherits from " (:CL "standard-object") "." (:PAR) (:GROUP (:FONT :FACE :I) "description") " is a string or "
       (:CL "nil") ". This should be the term for an instance for the type being defined. If it is " (:CL "nil")
       " or unsupplied, a description is automatically generated; it will be a \"prettied up\" version of the type name, for example, "
       (:CL "small-integer") " would become " (:CL "\"small integer\"") ". You can also write a "
       (:CL "describe-presentation-type") " presentation method. " (:GROUP (:FONT :FACE :I) "description")
       " is implemented by the default " (:CL "describe-presentation-type") " method, so "
       (:GROUP (:FONT :FACE :I) "description")
       " only works in presentation types where that default method is not shadowed." (:PAR)
       (:GROUP (:FONT :FACE :I) "history") " can be " (:CL "t")
       " (the default), which means this type has its own history of previous inputs, " (:CL "nil")
       ", which means this type keeps no history, or the name of another presentation type, whose history is shared by this type. More complex histories can be specified by writing a "
       (:CL "presentation-type-history") " presentation method." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL) "What is a presentation type history? Should they be exposed? --- SWM") (:PAR)
       "If the boolean " (:GROUP (:FONT :FACE :I) "parameters-are-types") " is " (:TERM "true")
       ", this means that the parameters to the presentation type are themselves presentation types. If they are not presentation types, "
       (:GROUP (:FONT :FACE :I) "parameters-are-types") " should be supplied as " (:TERM "false") ". Types such as "
       (:CL "and") ", " (:CL "or") ", and " (:CL "sequence") " will specify this as " (:TERM "true") "." (:PAR)
       "Every presentation type must define or inherit presentation methods for " (:CL "accept") " and "
       (:CL "present")
       " if the type is going to be used for input and output. For presentation types that are only going to be used for input via the pointer, the "
       (:CL "accept") " need not be defined." (:PAR) "If a presentation type has "
       (:GROUP (:FONT :FACE :I) "parameters") ", it must define presentation methods for " (:CL "presentation-typep")
       " and " (:CL "presentation-subtypep")
       " that handle the parameters, or inherit appropriate presentation methods. In many cases it should also define presentation methods for "
       (:CL "describe-presentation-type") " and " (:CL "presentation-type-specifier-p") "." (:PAR)
       "There are certain restrictions on the " (:GROUP (:FONT :FACE :I) "inherit-from")
       " form, to allow it to be analyzed at compile time. The form must be a simple substitution of parameters and options into positions in a fixed framework. It cannot involve conditionals or computations that depend on valid values for the parameters or options; for example, it cannot require parameter values to be numbers. It cannot depend on the dynamic or lexical environment. The form will be evaluated at compile time with uninterned symbols used as dummy values for the parameters and options. In the type specifier produced by evaluating the form, the type name must be a constant that names a type, the type parameters cannot derive from options of the type being defined, and the type options cannot derive from parameters of the type being defined. All presentation types mentioned must be already defined. "
       (:CL "and") " can be used for multiple inheritance, but " (:CL "or") ", " (:CL "not") ", and " (:CL "satisfies")
       " cannot be used." (:PAR) "None of the arguments, except " (:GROUP (:FONT :FACE :I) "inherit-from")
       ", is evaluated." (:PAR) " "))
     (:SECTION :TITLE ("23.3.2 " "Presentation Type Abbreviations") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-presentation-type-abbreviation")) :PARAMS
        ((:I "name parameters equivalent-type  " (:GROUP (:FONT :FACE :TT) "&key ") "options")) :KIND ("Macro"))
       (:PAR) (:GROUP (:FONT :FACE :I) "name") ", " (:GROUP (:FONT :FACE :I) "parameters") ", and "
       (:GROUP (:FONT :FACE :I) "options") " are as in " (:CL "define-presentation-type")
       ". This defines a presentation type that is an " (:CONCEPT "abbreviation") " for the presentation type "
       (:GROUP (:FONT :FACE :I) "equivalent-type")
       ". Presentation type abbreviations can only be used in places where this specification explicitly permits them. In such places, "
       (:GROUP (:FONT :FACE :I) "equivalent-type") " and " (:TERM "abbreviation")
       " are exactly equivalent and can be used interchangeably." (:PAR) (:GROUP (:FONT :FACE :I) "name")
       " must be a symbol and must not be the name of a CLOS class." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "equivalent-type")
       " form might be evaluated at compile time if presentation type abbreviations are expanded by compiler optimizers. Unlike "
       (:GROUP (:FONT :FACE :I) "inherit-from") ", " (:GROUP (:FONT :FACE :I) "equivalent-type")
       " can perform arbitrary computations and is not called with dummy parameter and option values. The type specifier produced by evaluating "
       (:GROUP (:FONT :FACE :I) "equivalent-type")
       " can be a real presentation type or another abbreviation. If the type specifier doesn't include the standard option "
       (:CL ":description") ", the option is automatically copied from the abbreviation to its expansion." (:PAR)
       "Note that you cannot define any presentation methods on a presentation type abbreviation. If you need methods, use "
       (:CL "define-presentation-type") " instead." (:PAR) (:CL "define-presentation-type-abbreviation")
       " is used to name a commonly used cliche. For example, a presentation type to read an octal integer might be defined as "
       (:PRE "
(define-presentation-type-abbreviation octal-integer (&optional low high) 
    `((integer ,low ,high) :base 8 :description \"octal integer\"))
")
       (:PAR) "None of the arguments, except " (:GROUP (:FONT :FACE :I) "equivalent-type") ", is evaluated." (:PAR)
       " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "expand-presentation-type-abbreviation-1")) :PARAMS
        ((:I "type " (:GROUP (:FONT :FACE :TT) "&optional ") "env")) :KIND ("Function"))
       (:PAR) "If the " (:TERM "presentation type specifier") " " (:GROUP (:FONT :FACE :I) "type")
       " is a presentation type abbreviation, or is an " (:CL "and") ", " (:CL "or") ", " (:CL "sequence") ", or "
       (:CL "sequence-enumerated")
       " that contains a presentation type abbreviation, then this expands the type abbreviation once, and returns two values, the expansion and "
       (:CL "t") ". If " (:GROUP (:FONT :FACE :I) "type") " is not a presentation type abbreviation, then the values "
       (:GROUP (:FONT :FACE :I) "type") " and " (:CL "nil") " are returned." (:PAR) (:GROUP (:FONT :FACE :I) "env")
       " is a macro-expansion environment, as for " (:CL "macroexpand") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "expand-presentation-type-abbreviation")) :PARAMS
        ((:I "type " (:GROUP (:FONT :FACE :TT) "&optional ") "env")) :KIND ("Function"))
       (:PAR) (:CL "expand-presentation-type-abbreviation") " is like " (:CL "expand-presentation-type-abbreviation-1")
       ", except that " (:GROUP (:FONT :FACE :I) "type")
       " is repeatedly expanded until all presentation type abbreviations have been removed." (:PAR) " "))
     (:SECTION :TITLE ("23.3.3 " "Presentation Methods") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      "Presentation methods inherit and combine in the same way as ordinary CLOS methods. The reason presentation methods are not exactly the same as ordinary CLOS methods revolves around the "
      (:GROUP (:FONT :FACE :I) "type") " argument. The parameter specializer for " (:GROUP (:FONT :FACE :I) "type")
      " is handled in a special way, and presentation method inheritance \"massages\" the type parameters and options seen by each method. For example, consider three types "
      (:CL "int") ", " (:CL "rrat") ", and " (:CL "num") " defined as follows:" (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "How are massaged arguments passed along? Right now, we pass along those parameters of the same name, and no others. --- SWM")
      (:PAR)
      (:PRE "
(define-presentation-type int (low high)
  :inherit-from `(rrat ,high ,low))

(define-presentation-method presentation-typep :around (object (type int))
  (and (call-next-method)
       (integerp object)
       (<= low object high)))

(define-presentation-type rrat (high low)
  :inherit-from `num)

(define-presentation-method presentation-typep :around (object (type rrat))
  (and (call-next-method)
       (rationalp object)
       (<= low object high)))

(define-presentation-type num ())

(define-presentation-method presentation-typep (object (type num))
  (numberp object))
")
      (:PAR) "If the user were to evaluate the form " (:CL "(presentation-typep X '(int 1 5))")
      ", then the type parameters will be " (:CL "(1 5)") " in the " (:CL "presentation-typep") " method for "
      (:CL "int") ", " (:CL "(5 1)") " in the method for " (:CL "rrat") ", and " (:CL "nil") " in the method for "
      (:CL "num") ". The value for " (:GROUP (:FONT :FACE :I) "type") " will be or " (:CL "((int 1 5))")
      " in each of the methods." (:PAR) " "
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-presentation-generic-function")) :PARAMS
        ((:I "generic-function-name  presentation-function-name  lambda-list " (:GROUP (:FONT :FACE :TT) "&rest ")
          "options"))
        :KIND ("Macro"))
       (:PAR) "Defines a generic function that will be used for presentation methods. "
       (:GROUP (:FONT :FACE :I) "generic-function-name")
       " is a symbol that names the generic function that will be used internally by CLIM for the individual methods, "
       (:GROUP (:FONT :FACE :I) "presentation-function-name")
       " is a symbol that names the function that programmers will call to invoke the method, and "
       (:GROUP (:FONT :FACE :I) "lambda-list") " and " (:GROUP (:FONT :FACE :I) "options") " are as for "
       (:CL "defgeneric") "." (:PAR) "There are some \"special\" arguments in " (:GROUP (:FONT :FACE :I) "lambda-list")
       " that are known about by the presentation type system. The first argument in "
       (:GROUP (:FONT :FACE :I) "lambda-list") " must be either " (:CL "type-key") " or " (:CL "type-class")
       "; this argument is used by CLIM to implement method dispatching. The second argument may be "
       (:CL "parameters")
       ", meaning that, when the method is invoked, the type parameters will be passed to it. The third argument may be "
       (:CL "options")
       ", meaning that, when the method is invoked, the type options will be passed to it. Finally, an argument named "
       (:CL "type") " must be included in " (:GROUP (:FONT :FACE :I) "lambda-list") "; when the method is called, "
       (:GROUP (:FONT :FACE :I) "type") " argument will be bound to the presentation type specifier." (:PAR)
       "For example, the " (:CL "accept") " presentation generic function might be defined as follows: "
       (:PRE "
(define-presentation-generic-function present-method present
  (type-key parameters options object type stream view
   &key acceptably for-context-type))
")
       (:PAR) "None of the arguments is evaluated." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-presentation-method")) :PARAMS
        ((:I "name qualifiers* specialized-lambda-list " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Defines a presentation method for the function named " (:GROUP (:FONT :FACE :I) "name")
       " on the presentation type named in " (:GROUP (:FONT :FACE :I) "specialized-lambda-list") ". "
       (:GROUP (:FONT :FACE :I) "specialized-lambda-list")
       " is a CLOS specialized lambda list for the method, and its contents varies depending on what "
       (:GROUP (:FONT :FACE :I) "name") " is. " (:GROUP (:FONT :FACE :I) "qualifiers*")
       " is zero or more of the usual CLOS method qualifier symbols. " (:CL "define-presentation-method")
       " must support at least " (:CL "standard") " method combination (and therefore the " (:CL ":before") ", "
       (:CL ":after") ", and " (:CL ":around")
       " method qualifiers). Some CLIM implementations may support other method combination types, but this is not required."
       (:PAR) (:GROUP (:FONT :FACE :I) "body") " defines the body of the method. " (:GROUP (:FONT :FACE :I) "body")
       " may have zero or more declarations as its first forms." (:PAR)
       "All presentation methods have an argument named " (:GROUP (:FONT :FACE :I) "type")
       " that must be specialized with the name of a presentation type. The value of " (:GROUP (:FONT :FACE :I) "type")
       " is a presentation type specifier, which can be for a subtype that inherited the method." (:PAR)
       "All presentation methods except " (:CL "presentation-subtypep")
       " have lexical access to the parameters from the presentation type specifier. Presentation methods for the functions "
       (:CL "accept") ", " (:CL "present") ", " (:CL "describe-presentation-type") ", "
       (:CL "presentation-type-specifier-p") ", and " (:CL "accept-present-default")
       " also have lexical access to the options from the presentation type specifier." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-default-presentation-method")) :PARAMS
        ((:I "name qualifiers* specialized-lambda-list  " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Like " (:CL "define-presentation-method")
       ", except that it is used to define a default method that will be used only if there are no more specific methods."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "funcall-presentation-generic-function")) :PARAMS
        ((:I "presentation-function-name " (:GROUP (:FONT :FACE :TT) "&rest ") "arguments")) :KIND ("Macro"))
       (:PAR) "Calls the presentation generic function named by "
       (:GROUP (:FONT :FACE :I) "presentation-function-name") " on the arguments "
       (:GROUP (:FONT :FACE :I) "arguments") ". " (:GROUP (:FONT :FACE :I) "arguments")
       " must match the arguments specified by the " (:CL "define-presentation-generic-function")
       " that was used to define the presentation generic function, excluding the " (:CL "type-key") ", "
       (:CL "type-class") ", " (:CL "parameters") ", and " (:CL "options") " arguments, which are filled in by CLIM."
       (:PAR) (:CL "funcall-presentation-generic-function") " is analogous to " (:CL "funcall") "." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "presentation-function-name") " argument is not evaluated." (:PAR)
       "For example, to call the " (:CL "present") " presentation generic function, one might use the following: "
       (:PRE "
(funcall-presentation-generic-function present
  object presentation-type stream view)
")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "apply-presentation-generic-function")) :PARAMS
        ((:I "presentation-function-name " (:GROUP (:FONT :FACE :TT) "&rest ") "arguments")) :KIND ("Macro"))
       (:PAR) "Like " (:CL "funcall-presentation-generic-function") ", except that "
       (:CL "apply-presentation-generic-function") " is analogous to " (:CL "apply") "." (:PAR) "The "
       (:GROUP (:FONT :FACE :I) "presentation-function-name") " argument is not evaluated." (:PAR)
       " Here is a list of all of the standard presentation methods and their specialized lambda lists. For the meaning of the arguments to each presentation method, refer to the description of the function that calls that method."
       (:PAR) "For all of the presentation methods, the " (:GROUP (:FONT :FACE :I) "type")
       " will always be specialized. For those methods that take a " (:GROUP (:FONT :FACE :I) "view")
       " argument, implementors and programmers may specialize it as well. The other arguments are not typically specialized."
       (:PAR) (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "present")) :PARAMS
        ((:I "object type stream view " (:GROUP (:FONT :FACE :TT) "&key ") "acceptably for-context-type")) :KIND
        ("Presentation Method"))
       (:PAR) "The " (:CL "present") " presentation method is responsible for displaying the representation of "
       (:GROUP (:FONT :FACE :I) "object") " having " (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type")
       " for a particular " (:TERM "view") " " (:GROUP (:FONT :FACE :I) "view")
       ". The method's caller takes care of creating the presentation, the method simply displays the content of the presentation."
       (:PAR) "The " (:CL "present") " method can specialize on the " (:GROUP (:FONT :FACE :I) "view")
       " argument in order to define more than one view of the data. For example, a spreadsheet program might define a presentation type for revenue, which can be displayed either as a number or a bar of a certain length in a bar graph. Typically, at least one canonical view should be defined for a presentation type, for example, the "
       (:CL "present") " method for the " (:CL "textual-view")
       " view must be defined if the programmer wants to allow objects of that type to be displayed textually." (:PAR)
       (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the " (:CL "present")
       " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters options object type stream view "
        (:GROUP (:FONT :FACE :TT) "&key ") "acceptably for-context-type)")
       " " (:BR) " " (:GROUP (:FONT :FACE :I) "type-key")
       " is the object that is used to cause the appropriate methods to be selected (an instance of the class that corresponds to the presentation type "
       (:GROUP (:FONT :FACE :I) "type") ".). " (:GROUP (:FONT :FACE :I) "parameters") " and "
       (:GROUP (:FONT :FACE :I) "options")
       " are the parameters and options for the type on which the current method is specialized. The other arguments are gotten from the arguments of the same name in "
       (:CL "present") "." (:PAR) " " (:GROUP (:FONT :FACE :B) "Implementation note:")
       " the actual generic function of the " (:CL "present")
       " method is an internal generic function, not the function whose name is " (:CL "present")
       ". Similar internal generic functions are used for all presentation methods." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "accept")) :PARAMS
        ((:I "type stream view " (:GROUP (:FONT :FACE :TT) "&key ") "default default-type")) :KIND
        ("Presentation Method"))
       (:PAR) "The " (:CL "accept") " method is responsible for \"parsing\" the representation of the "
       (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type") " for a particular " (:TERM "view") " "
       (:GROUP (:FONT :FACE :I) "view") ". The " (:CL "accept")
       " method must return a single value, the object that was \"parsed\", or two values, the object and its type (a presentation type specifier). The method's caller takes care of establishing the input context, defaulting, prompting, and input editing."
       (:PAR) "The " (:CL "accept") " method can specialize on the " (:GROUP (:FONT :FACE :I) "view")
       " argument in order to define more than one input view for the data. The " (:CL "accept") " method for the "
       (:CL "textual-view")
       " view must be defined if the programmer wants to allow objects of that type to entered via the keyboard."
       (:PAR) "Note that " (:CL "accept") " presentation methods can call " (:CL "accept")
       " recursively. In this case, the programmer should be careful to specify " (:CL "nil") " for " (:CL ":prompt")
       " and " (:CL ":display-default") " unless recursive prompting is really desired." (:PAR)
       (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the " (:CL "accept")
       " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters options type stream view " (:GROUP (:FONT :FACE :TT) "&key ")
        "default default-type)")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "describe-presentation-type")) :PARAMS ((:I "type stream plural-count")) :KIND
        ("Presentation Method"))
       (:PAR) "The " (:CL "describe-presentation-type") " method is responsible for textually describing the "
       (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type") ". " (:GROUP (:FONT :FACE :I) "stream")
       " is a stream, and will not be " (:CL "nil") " as it can be for the " (:CL "describe-presentation-type")
       " function." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the "
       (:CL "describe-presentation-type") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters options type stream plural-count)") (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-type-specifier-p")) :PARAMS ((:I "type")) :KIND ("Presentation Method"))
       (:PAR) "The " (:CL "presentation-type-specifier-p")
       " method is responsible for checking the validity of the parameters and options for the "
       (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type") ". The default method returns " (:CL "t") "."
       (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the "
       (:CL "presentation-type-specifier-p") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters options type)") (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-typep")) :PARAMS ((:I "object type")) :KIND ("Presentation Method"))
       (:PAR) "The " (:CL "presentation-typep") " method is called when the " (:CL "presentation-typep")
       " function requires type-specific knowledge. If the type name in the " (:TERM "presentation type") " "
       (:GROUP (:FONT :FACE :I) "type") " is a CLOS class or names a CLOS class, the method is called only if "
       (:GROUP (:FONT :FACE :I) "object") " is a member of the class and " (:GROUP (:FONT :FACE :I) "type")
       " contains parameters, and the method simply tests whether " (:GROUP (:FONT :FACE :I) "object")
       " is a member of the subtype specified by the parameters. For non-class types, the method is always called."
       (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the "
       (:CL "presentation-typep") " method is " (:BR) " " (:GROUP (:FONT :FACE :I) "(type-key parameters object type)")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-subtypep")) :PARAMS ((:I "type putative-supertype")) :KIND
        ("Presentation Method"))
       (:PAR) (:CL "presentation-subtypep") " walks the type lattice (using " (:CL "map-over-presentation-supertypes")
       ") to determine whethe or not the " (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type")
       " is a subtype of the" (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "putative-supertype")
       ", without looking at the type parameters. When a supertype of " (:GROUP (:FONT :FACE :I) "type")
       " has been found whose name is the same as the name of " (:GROUP (:FONT :FACE :I) "putative-supertype")
       ", then the " (:CL "subtypep")
       " method for that type is called in order to resolve the question by looking at the type parameters (that is, if the "
       (:CL "subtypep") " method is called, " (:GROUP (:FONT :FACE :I) "type") " and "
       (:GROUP (:FONT :FACE :I) "putative-supertype")
       " are guaranteed to be the same type, differing only in their parameters). If "
       (:GROUP (:FONT :FACE :I) "putative-supertype") " is never found during the type walk, then "
       (:CL "presentation-subtypep") " will never call the " (:CL "presentation-subtypep") " presentation method for "
       (:GROUP (:FONT :FACE :I) "putative-supertype") "." (:PAR) "Unlike all other presentation methods, "
       (:CL "presentation-subtypep") " receives a " (:GROUP (:FONT :FACE :I) "type")
       " argument that has been translated to the presentation type for which the method is specialized; "
       (:GROUP (:FONT :FACE :I) "type") " is never a subtype. The method is only called if "
       (:GROUP (:FONT :FACE :I) "putative-supertype")
       " has parameters and the two presentation type specifiers do not have equal parameters. The method must return the two values that "
       (:CL "presentation-subtypep") " returns." (:PAR) "Since " (:CL "presentation-subtypep")
       " takes two type arguments, the parameters are not lexically available as variables in the body of a presentation method."
       (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the "
       (:CL "presentation-subtypep") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key type putative-supertype)") (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-presentation-type-supertypes")) :PARAMS ((:I "function type")) :KIND
        ("Presentation Method"))
       (:PAR) "This method is called in order to apply " (:GROUP (:FONT :FACE :I) "function")
       " to the superclasses of the " (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type") "." (:PAR)
       (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the "
       (:CL "map-over-presentation-type-supertypes") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-class function type)") (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "accept-present-default")) :PARAMS
        ((:I "type stream view default default-supplied-p  present-p query-identifier")) :KIND ("Presentation Method"))
       (:PAR) "The " (:CL "accept-present-default") " method is called when " (:CL "accept") " turns into "
       (:CL "present") " inside of " (:CL "accepting-values") ". The default method calls " (:CL "present") " or "
       (:CL "describe-presentation-type") " depending on whether " (:GROUP (:FONT :FACE :I) "default-supplied-p")
       " is " (:TERM "true") " or " (:TERM "false") ", respectively." (:PAR) "The boolean "
       (:GROUP (:FONT :FACE :I) "default-supplied-p") " will be " (:TERM "true") " only in the case when the "
       (:CL ":default") " option was explicitly supplied in the call to " (:CL "accept") " that invoked "
       (:CL "accept-present-default") "." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
       " the actual argument list to the " (:CL "accept-present-default") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I)
        "(type-key parameters options type stream view default default-supplied-p present-p query-identifier)")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-type-history")) :PARAMS ((:I "type")) :KIND ("Presentation Method"))
       (:PAR) "This method is responsible for returning a history object for the " (:TERM "presentation type") " "
       (:GROUP (:FONT :FACE :I) "type") "." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
       " the actual argument list to the " (:CL "presentation-type-history") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters type)") (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-default-preprocessor")) :PARAMS
        ((:I "default type " (:GROUP (:FONT :FACE :TT) "&key ") "default-type")) :KIND ("Presentation Method"))
       (:PAR) "This method is responsible for taking the object " (:GROUP (:FONT :FACE :I) "default")
       ", and coercing it to match the " (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type")
       " (which is the type being accepted) and " (:GROUP (:FONT :FACE :I) "default-type")
       " (which is the presentation type of " (:GROUP (:FONT :FACE :I) "default")
       "). This is useful when you want to change the default gotten from the presentation type's history so that it conforms to parameters or options in "
       (:GROUP (:FONT :FACE :I) "type") " and " (:GROUP (:FONT :FACE :I) "default-type")
       ".) The method must return two values, the new object to be used as the default, and a new presentation type, which should be at least as specific as "
       (:GROUP (:FONT :FACE :I) "type") "." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
       " the actual argument list to the " (:CL "presentation-default-preprocessor") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters default type " (:GROUP (:FONT :FACE :TT) "&key ")
        "default-type)")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-refined-position-test")) :PARAMS ((:I "type record x y")) :KIND
        ("Presentation Method"))
       (:PAR)
       "This method used to definitively answer hit detection queries for a presentation, that is, determining that the point "
       (:MATH "(x,y)") " is contained within the output record " (:GROUP (:FONT :FACE :I) "record")
       ". Its contract is exactly the same as for " (:CL "output-record-refined-position-test")
       ", except that it is intended to specialize on the presentation type " (:GROUP (:FONT :FACE :I) "type") "."
       (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " the actual argument list to the "
       (:CL "presentation-refined-position-test") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters options type record x y)") (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "highlight-presentation")) :PARAMS ((:I "type record stream state")) :KIND
        ("Presentation Method"))
       (:PAR) "This method is responsible for drawing a highlighting box around the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "record") " on the " (:TERM "output recording stream") " "
       (:GROUP (:FONT :FACE :I) "stream") ". " (:GROUP (:FONT :FACE :I) "state") " will be either " (:CL ":highlight")
       " or " (:CL ":unhighlight") "." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
       " the actual argument list to the " (:CL "highlight-presentation") " method is " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(type-key parameters options type record stream state)") (:PAR) (:PAR)))
     (:SECTION :TITLE ("23.3.4 " "Presentation Type Functions") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "describe-presentation-type")) :PARAMS
        ((:I "type " (:GROUP (:FONT :FACE :TT) "&optional ") "stream plural-count")) :KIND ("Function"))
       (:PAR) "Describes the " (:TERM "presentation type specifier") " " (:GROUP (:FONT :FACE :I) "type") " on the "
       (:TERM "stream") " " (:GROUP (:FONT :FACE :I) "stream") ", which defaults to " (:CL "*standard-output*") ". If "
       (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "nil") ", a string containing the description is returned. "
       (:GROUP (:FONT :FACE :I) "plural-count") " is either " (:CL "nil")
       " (meaning that the description should be the singular form of the name), " (:CL "t")
       " (meaning that the description should the plural form of the name), or an integer greater than zero (the number of items to be described). The default is "
       (:CL "1") "." (:PAR) (:GROUP (:FONT :FACE :I) "type") " can be a presentation type abbreviation." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-type-parameters")) :PARAMS
        ((:I "type-name " (:GROUP (:FONT :FACE :TT) "&optional ") "env")) :KIND ("Function"))
       (:PAR)
       "Returns a lambda-list, the parameters specified when the presentation type or presentation type abbreviation whose name is "
       (:GROUP (:FONT :FACE :I) "type-name") " was defined. " (:GROUP (:FONT :FACE :I) "type-name")
       " is a symbol or a class. " (:GROUP (:FONT :FACE :I) "env") " is a macro-expansion environment, as in "
       (:CL "find-class") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-type-options")) :PARAMS
        ((:I "type-name " (:GROUP (:FONT :FACE :TT) "&optional ") "env")) :KIND ("Function"))
       (:PAR)
       "Returns the list of options specified when the presentation type or presentation type abbreviation whose name is "
       (:GROUP (:FONT :FACE :I) "type-name")
       " was defined. This does not include the standard options unless the presentation-type definition mentioned them explicitly. "
       (:GROUP (:FONT :FACE :I) "type-name") " is a symbol or a class. " (:GROUP (:FONT :FACE :I) "env")
       " is a macro-expansion environment, as in " (:CL "find-class") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-presentation-type-decoded")) :PARAMS
        ((:I "(name-var " (:GROUP (:FONT :FACE :TT) "&optional ") "parameters-var options-var)  type  "
          (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR)
       "The specified variables are bound to the components of the presentation type specifier produced by evaluating "
       (:GROUP (:FONT :FACE :I) "type") ", the forms in " (:GROUP (:FONT :FACE :I) "body")
       " are executed, and the values of the last form are returned. " (:GROUP (:FONT :FACE :I) "name-var") ", if non-"
       (:CL "nil") ", is bound to the presentation type name. " (:GROUP (:FONT :FACE :I) "parameters-var") ", if non-"
       (:CL "nil") ", is bound to a list of the parameters. " (:GROUP (:FONT :FACE :I) "options-var") ", if non-"
       (:CL "nil") ", is bound to a list of the options. When supplied, " (:GROUP (:FONT :FACE :I) "name-var") ", "
       (:GROUP (:FONT :FACE :I) "parameters-var") ", and " (:GROUP (:FONT :FACE :I) "options-var") " must be symbols."
       (:PAR) "The " (:GROUP (:FONT :FACE :I) "name-var") ", " (:GROUP (:FONT :FACE :I) "parameters-var") ", and "
       (:GROUP (:FONT :FACE :I) "options-var") " arguments are not evaluated. " (:GROUP (:FONT :FACE :I) "body")
       " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "presentation-type-name")) :PARAMS ((:I "type")) :KIND ("Function")) (:PAR)
       "Returns the presentation type name of the presentation type specifier " (:GROUP (:FONT :FACE :I) "type")
       ". This function is provided as a convenience. It could be implemented with the following code:" (:PAR)
       (:PRE "
(defun presentation-type-name (type)
  (with-presentation-type-decoded (name) type
    name))
")
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-presentation-type-parameters")) :PARAMS
        ((:I "(type-name type) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR)
       "Variables with the same name as each parameter in the definition of the presentation type are bound to the parameter values in "
       (:GROUP (:FONT :FACE :I) "type")
       ", if present, or else to the defaults specified in the definition of the presentation type. The forms in "
       (:GROUP (:FONT :FACE :I) "body")
       " are executed in the scope of these variables and the values of the last form are returned." (:PAR)
       "The value of the form " (:GROUP (:FONT :FACE :I) "type")
       " must be a presentation type specifier whose name is " (:GROUP (:FONT :FACE :I) "type-name") ". The "
       (:GROUP (:FONT :FACE :I) "type-name") " and " (:GROUP (:FONT :FACE :I) "type") " arguments are not evaluated. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-presentation-type-options")) :PARAMS
        ((:I "(type-name type) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR)
       "Variables with the same name as each option in the definition of the presentation type are bound to the option values in "
       (:GROUP (:FONT :FACE :I) "type")
       ", if present, or else to the defaults specified in the definition of the presentation type. The forms in "
       (:GROUP (:FONT :FACE :I) "body")
       " are executed in the scope of these variables and the values of the last form are returned." (:PAR)
       "The value of the form " (:GROUP (:FONT :FACE :I) "type")
       " must be a presentation type specifier whose name is " (:GROUP (:FONT :FACE :I) "type-name") ". The "
       (:GROUP (:FONT :FACE :I) "type-name") " and " (:GROUP (:FONT :FACE :I) "type") " arguments are not evaluated. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "presentation-type-specifier-p")) :PARAMS ((:I "object")) :KIND ("Function"))
       (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a valid "
       (:TERM "presentation type specifier") ", otherwise returns " (:TERM "false") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "presentation-typep")) :PARAMS ((:I "object type")) :KIND ("Function")) (:PAR)
       "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object")
       " is of the presentation type specified by the " (:TERM "presentation type specifier") " "
       (:GROUP (:FONT :FACE :I) "type") ", otherwise returns " (:TERM "false") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "type") " may not be a presentation type abbreviation." (:PAR)
       "This is analogous to the Common Lisp " (:CL "typep") " function." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "presentation-type-of")) :PARAMS ((:I "object")) :KIND ("Function")) (:PAR)
       "Returns a presentation type of which " (:GROUP (:FONT :FACE :I) "object") " is a member. "
       (:CL "presentation-type-of")
       " returns the most specific presentation type that can be conveniently computed and is likely to be useful to the programmer. This is often the class name of the class of the object."
       (:PAR) "If " (:CL "presentation-type-of")
       " cannot determine the presentation type of the object, it may return either " (:CL "expression") " or "
       (:CL "t") "." (:PAR) "This is analogous to the Common Lisp " (:CL "typep") " function." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-subtypep")) :PARAMS ((:I "type putative-supertype")) :KIND ("Function"))
       (:PAR) "Answers the question \"is the type specified by the " (:TERM "presentation type specifier") " "
       (:GROUP (:FONT :FACE :I) "type") " a subtype of the type specified by the "
       (:TERM "presentation type specifier") " " (:GROUP (:FONT :FACE :I) "putative-supertype") "?\". "
       (:CL "presentation-subtypep") " returns two values, " (:GROUP (:FONT :FACE :I) "subtypep") " and "
       (:GROUP (:FONT :FACE :I) "known-p") ". When " (:GROUP (:FONT :FACE :I) "known-p") " is " (:TERM "true") ", "
       (:GROUP (:FONT :FACE :I) "subtypep") " can be either " (:TERM "true") " (meaning that "
       (:GROUP (:FONT :FACE :I) "type") " is definitely a subtype of " (:GROUP (:FONT :FACE :I) "putative-supertype")
       ") or " (:TERM "false") " (meaning that " (:GROUP (:FONT :FACE :I) "type") " is definitely not a subtype of "
       (:GROUP (:FONT :FACE :I) "putative-supertype") "). When " (:GROUP (:FONT :FACE :I) "known-p") " is "
       (:TERM "false") ", then " (:GROUP (:FONT :FACE :I) "subtypep") " must also be " (:TERM "false")
       "; this means that the answer cannot reliably be determined." (:PAR) (:GROUP (:FONT :FACE :I) "type")
       " may not be a presentation type abbreviation." (:PAR) "This is analogous to the Common Lisp " (:CL "subtypep")
       " function." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "map-over-presentation-type-supertypes")) :PARAMS ((:I "function type")) :KIND
        ("Function"))
       (:PAR) "Calls the function " (:GROUP (:FONT :FACE :I) "function") " on the "
       (:TERM "presentation type specifier") " " (:GROUP (:FONT :FACE :I) "type") " and each of its supertypes. "
       (:GROUP (:FONT :FACE :I) "function")
       " is called with two arguments, the name of a type and a presentation type specifier for that type with the parameters and options filled in. "
       (:GROUP (:FONT :FACE :I) "function")
       " has dynamic extent; its two arguments are permitted to have dynamic extent. The traversal of the type lattice is done in the order specified by the CLOS class precedence rules, and visits each type in the lattice exactly once."
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "presentation-type-direct-supertypes")) :PARAMS ((:I "type")) :KIND ("Function"))
       (:PAR)
       "Returns a sequence consisting of the names of all of the presentation types that are direct supertypes of the "
       (:TERM "presentation type specifier") " " (:GROUP (:FONT :FACE :I) "type") ", or " (:CL "nil") " if "
       (:GROUP (:FONT :FACE :I) "type")
       " has no supertypes. The consequences of modifying the returned sequence are unspecified." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "find-presentation-type-class")) :PARAMS
        ((:I "name " (:GROUP (:FONT :FACE :TT) "&optional ") "(errorp " (:CL "t") ") environment")) :KIND ("Function"))
       (:PAR) "Returns the class corresponding to the presentation type named " (:GROUP (:FONT :FACE :I) "name")
       ", which must be a symbol or a class object. " (:GROUP (:FONT :FACE :I) "errorp") " and "
       (:GROUP (:FONT :FACE :I) "environment") " are as for " (:CL "find-class") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "class-presentation-type-name")) :PARAMS
        ((:I "class " (:GROUP (:FONT :FACE :TT) "&optional ") "environment")) :KIND ("Function"))
       (:PAR) "Returns the presentation type name corresponding to the class " (:GROUP (:FONT :FACE :I) "class")
       ". This is essentially the inverse of " (:CL "find-presentation-type-class") ". "
       (:GROUP (:FONT :FACE :I) "environment") " is as for " (:CL "find-class") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "default-describe-presentation-type")) :PARAMS ((:I "description stream plural-count"))
        :KIND ("Function"))
       (:PAR) "Performs the default actions for " (:CL "describe-presentation-type")
       ", notably pluralization and prepending an indefinite article if appropriate. "
       (:GROUP (:FONT :FACE :I) "description") " is a string or a symbol, typically the " (:CL ":description")
       " presentation type option or the " (:CL ":description") " option to " (:CL "define-presentation-type") ". "
       (:GROUP (:FONT :FACE :I) "plural-count") " is as for " (:CL "describe-presentation-type") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-presentation-type-specifier")) :PARAMS
        ((:I "type-name-and-parameters " (:GROUP (:FONT :FACE :TT) "&rest ") "options")) :KIND ("Function"))
       (:PAR)
       "A convenient way to assemble a presentation type specifier with only non-default options included. This is only useful for abbreviation expanders, not for "
       (:CL ":inherit-from") ". " (:GROUP (:FONT :FACE :I) "type-name-and-parameters")
       " is a presentation type specifier, which must be in the "
       (:CL "(" (:GROUP (:FONT :FACE :I) "type-name") " " (:GROUP (:FONT :FACE :I) "parameters...") ")") " form. "
       (:GROUP (:FONT :FACE :I) "options")
       " are alternating keywords and values that are added as options to the presentation type specifier, except that if a value is equal to "
       (:GROUP (:FONT :FACE :I) "type-name")
       "'s default, that option is omitted, producing a more concise presentation type specifier." (:PAR) " ")))
    (:SECTION :TITLE ("23.4 " "Typed Output") :KIND :SECTION :NAME (8 5 10) (:PAR)
     "An application can specify that all output done within a certain dynamic extent should be associated with a given Lisp object and be declared to be of a specified presentation type. The resulting output is saved in the window's output history as a presentation. Specifically, the presentation remembers the output that was performed (by saving the associated output record), the Lisp object associated with the output, and the presentation type specified at output time. The object can be any Lisp object."
     (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-output-as-presentation")) :PARAMS
       ((:I "(stream object type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "modifier single-box allow-sensitive-inferiors  parent record-type "
         (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ")  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "The output of " (:GROUP (:FONT :FACE :I) "body") " to the " (:TERM "extended output recording") " "
      (:GROUP (:FONT :FACE :I) "stream") " is used to generate a presentation whose underlying object is "
      (:GROUP (:FONT :FACE :I) "object") " and whose presentation type is " (:GROUP (:FONT :FACE :I) "type")
      ". Each invocation of this macro results in the creation of a presentation object in the stream's output history unless output recording has been disabled or "
      (:CL ":allow-sensitive-inferiors nil")
      " was specified at a higher level, in which case the presentation object is not inserted into the history. "
      (:CL "with-output-as-presentation") " returns the presentation corresponding to the output." (:PAR) "The "
      (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to an extended output stream or output recording stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "type") " may be a presentation type abbreviation." (:PAR)
      (:GROUP (:FONT :FACE :I) "modifier") ", which defaults to " (:CL "nil")
      ", is some sort of object that describes how the presentation object might be modified. For example, it might be a function of one argument (the new value) that can be called in order to store a new value for "
      (:GROUP (:FONT :FACE :I) "object") " after a user somehow \"edits\" the presentation. "
      (:GROUP (:FONT :FACE :I) "modifier") " must have indefinite extent." (:PAR)
      (:GROUP (:FONT :FACE :I) "single-box") " is used to specify the " (:CL "presentation-single-box")
      " component of the resulting presentation. It can take on the values described under "
      (:CL "presentation-single-box") "." (:PAR) "When the boolean "
      (:GROUP (:FONT :FACE :I) "allow-sensitive-inferiors") " is " (:TERM "false") ", nested calls to " (:CL "present")
      " or " (:CL "with-output-as-presentation") " inside this one will not generate presentations. The default is "
      (:TERM "true") "." (:PAR) (:GROUP (:FONT :FACE :I) "parent")
      " specifies what output record should serve as the parent for the newly created presentation. If unspecified, "
      (:CL "stream-current-output-record") " of " (:GROUP (:FONT :FACE :I) "stream") " will be used as the parent."
      (:PAR) (:GROUP (:FONT :FACE :I) "record-type")
      " specifies the class of the presentation output record to be created. It defaults to "
      (:CL "standard-presentation")
      ". This argument should only be supplied by a programmer if there is a new class of output record that supports the updating output record protocol."
      (:PAR) "All arguments of this macro are evaluated." (:PAR) "For example, "
      (:PRE "
(with-output-as-presentation (stream #p\"foo\" 'pathname)
  (princ \"FOO\" stream))
")
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "present")) :PARAMS
       ((:I "object " (:GROUP (:FONT :FACE :TT) "&optional ") "type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "stream view modifier acceptably for-context-type  single-box allow-sensitive-inferiors sensitive record-type"))
       :KIND ("Function"))
      (:PAR) "The " (:GROUP (:FONT :FACE :I) "object") " of " (:TERM "presentation type") " "
      (:GROUP (:FONT :FACE :I) "type") " is presented to the " (:TERM "extended output stream") " "
      (:GROUP (:FONT :FACE :I) "stream") " (which defaults to " (:CL "*standard-output*") "), using the type's "
      (:CL "present") " method for the supplied " (:TERM "view") " " (:GROUP (:FONT :FACE :I) "view") ". "
      (:GROUP (:FONT :FACE :I) "type") " is a presentation type specifier, and can be an abbreviation. It defaults to "
      (:CL "(presentation-type-of " (:GROUP (:FONT :FACE :I) "object") ")")
      ". The other arguments and overall behavior of " (:CL "present") " are as for " (:CL "stream-present") "." (:PAR)
      "The returned value of " (:CL "present")
      " is the presentation object that contains the output corresponding to the object." (:PAR) (:CL "present")
      " must be implemented by first expanding any presentation type abbreviations (" (:GROUP (:FONT :FACE :I) "type")
      " and " (:GROUP (:FONT :FACE :I) "for-context-type") "), and then calling " (:CL "stream-present") " on "
      (:GROUP (:FONT :FACE :I) "stream") ", " (:GROUP (:FONT :FACE :I) "object") ", " (:GROUP (:FONT :FACE :I) "type")
      ", and the remaining keyword arguments, which are described below." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-present")) :PARAMS
       ((:I "stream object type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "view modifier acceptably for-context-type  single-box allow-sensitive-inferiors sensitive  record-type"))
       :KIND ("Generic Function"))
      (:PAR) (:CL "stream-present") " is the per-stream implementation of " (:CL "present")
      ", analogous to the relationship between " (:CL "write-char") " and " (:CL "stream-write-char")
      ". All extended output streams and output recording streams must implement a method for " (:CL "stream-present")
      ". The default method (on " (:CL "standard-extended-output-stream") ") implements the following behavior." (:PAR)
      "The object " (:GROUP (:FONT :FACE :I) "object") " of type " (:GROUP (:FONT :FACE :I) "type")
      " is presented to the " (:TERM "stream") " " (:GROUP (:FONT :FACE :I) "stream") " by calling the type's "
      (:CL "present") " method for the supplied " (:TERM "view") " " (:GROUP (:FONT :FACE :I) "view")
      ". The returned value is the presentation containing the output corresponding to the object." (:PAR)
      (:GROUP (:FONT :FACE :I) "type") " is a presentation type specifier. " (:GROUP (:FONT :FACE :I) "view")
      " is a view object that defaults to " (:CL "stream-default-view") " of " (:GROUP (:FONT :FACE :I) "stream") "."
      (:PAR) (:GROUP (:FONT :FACE :I) "for-context-type") " is a presentation type specifier that is passed to the "
      (:CL "present") " method for " (:GROUP (:FONT :FACE :I) "type")
      ", which can use it to tailor how the object will be presented. " (:GROUP (:FONT :FACE :I) "for-context-type")
      " defaults to " (:GROUP (:FONT :FACE :I) "type") "." (:PAR) (:GROUP (:FONT :FACE :I) "modifier") ", "
      (:GROUP (:FONT :FACE :I) "single-box") ", " (:GROUP (:FONT :FACE :I) "allow-sensitive-inferiors") ", and "
      (:GROUP (:FONT :FACE :I) "record-type") " are the same as for " (:CL "with-output-as-presentation") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "acceptably") " defaults to " (:CL "nil") ", which requests the " (:CL "present")
      " method to produce text designed to be read by human beings. If " (:GROUP (:FONT :FACE :I) "acceptably") " is "
      (:CL "t") ", it requests the " (:CL "present") " method to produce text that is recognized by the "
      (:CL "accept") " method for " (:GROUP (:FONT :FACE :I) "for-context-type")
      ". This makes no difference to most presentation types." (:PAR) "The boolean "
      (:GROUP (:FONT :FACE :I) "sensitive") " defaults to " (:TERM "true") ". If it is " (:TERM "false")
      ", no presentation is produced." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "present-to-string")) :PARAMS
       ((:I "object " (:GROUP (:FONT :FACE :TT) "&optional ") "type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "view acceptably for-context-type string index"))
       :KIND ("Function"))
      (:PAR) "Same as " (:CL "present") " inside " (:CL "with-output-to-string") ". If "
      (:GROUP (:FONT :FACE :I) "string") " is supplied, it must be a string with a fill pointer. When "
      (:GROUP (:FONT :FACE :I) "index") " is supplied, it is used as an index into " (:GROUP (:FONT :FACE :I) "string")
      ". " (:GROUP (:FONT :FACE :I) "view") ", " (:GROUP (:FONT :FACE :I) "acceptably") ", and "
      (:GROUP (:FONT :FACE :I) "for-context-type") " are as for " (:CL "present") "." (:PAR)
      "The first returned value is the string. When " (:GROUP (:FONT :FACE :I) "string")
      " is supplied, a second value is returned, the updated " (:GROUP (:FONT :FACE :I) "index") "." (:PAR) " "))
    (:SECTION :TITLE ("23.5 " "Context-dependent (Typed) Input") :KIND :SECTION :NAME (8 5 10) (:PAR)
     "Associating semantics with output is only half of the user interface equation. The presentation type system also supports the input side of the user interaction. When an application wishes to solicit from the user input of a particular presentation type, it establishes an "
     (:CONCEPT "input context")
     " for that type. CLIM will then automatically allow the user to satisfy the input request by pointing at a visible presentation of the requested type (or a valid subtype) and pressing a pointer button. Only the presentations that \"match\" the input context will be \"sensitive\" (that is, highlighted when the pointer is moved over them) and accepted as input, thus the presentation-based input mechanism supports "
     (:CONCEPT "context-dependent input") "." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL) "What exactly is an input context? What does it mean for them to be nested? --- SWM")
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "*input-context*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "The current input context. This will be a list, each element of which corresponds to a single call to "
      (:CL "with-input-context")
      ". The first element of the list represents the context established by the most recent call to "
      (:CL "with-input-context")
      ", and the last element represents the context established by the least recent call to "
      (:CL "with-input-context") "." (:PAR)
      "The exact format of the elements in the list is unspecified, but will typically be a list of a presentation type and a tag that corresponds to the point in the control structure of CLIM at which the input context was establish. "
      (:CL "*input-context*") " and the elements in it may have dynamic extent." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "input-context-type")) :PARAMS ((:I "context-entry")) :KIND ("Function")) (:PAR)
      "Given one element from " (:CL "*input-context*") ", " (:GROUP (:FONT :FACE :I) "context-entry")
      ", returns the presentation type of the context entry." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-input-context")) :PARAMS
       ((:I "(type " (:GROUP (:FONT :FACE :TT) "&key ") "override)  (" (:GROUP (:FONT :FACE :TT) "&optional ")
         "object-var type-var event-var options-var)  form  " (:GROUP (:FONT :FACE :TT) "&body ") "pointer-cases"))
       :KIND ("Macro"))
      (:PAR) "Establishes an input context of " (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type")
      "; this must be done by binding " (:CL "*input-context*") " to reflect the new input context. When the boolean "
      (:GROUP (:FONT :FACE :I) "override") " is " (:TERM "false") " (the default), this invocation of "
      (:CL "with-input-context")
      " adds its context presentation type to the current context. In this way an application can solicit more than one type of input at the same time. When "
      (:GROUP (:FONT :FACE :I) "override") " is " (:TERM "true")
      ", it overrides the current input context rather than nesting inside the current input context." (:PAR)
      (:GROUP (:FONT :FACE :I) "type") " can be a presentation type abbreviation." (:PAR)
      "After establishing the new input context, " (:GROUP (:FONT :FACE :I) "form")
      " is evaluated. If no pointer gestures are made by the user during the evaluation of "
      (:GROUP (:FONT :FACE :I) "form") ", the values of " (:GROUP (:FONT :FACE :I) "form")
      " are returned. Otherwise, one of the " (:GROUP (:FONT :FACE :I) "pointer-cases")
      " is executed (based on the presentation type of the object that was clicked on) and the value of that is returned. (See the descriptions of "
      (:CL "call-presentation-menu") " and " (:CL "throw-highlighted-presentation") ".) "
      (:GROUP (:FONT :FACE :I) "pointer-cases") " is constructed like a " (:CL "typecase")
      " statement clause list whose keys are presentation types; the first clause whose key satisfies the condition "
      (:CL "(presentation-subtypep " (:GROUP (:FONT :FACE :I) "type") " " (:GROUP (:FONT :FACE :I) "key") ")")
      " is the one that is chosen." (:PAR) "During the execution of one of the "
      (:GROUP (:FONT :FACE :I) "pointer-cases") ", " (:GROUP (:FONT :FACE :I) "object-var")
      " is bound to the object that was clicked on (the first returned value from the presentation translator that was invoked), "
      (:GROUP (:FONT :FACE :I) "type-var")
      " is bound to its presentation type (the second returned value from the translator), and "
      (:GROUP (:FONT :FACE :I) "event-var") " is bound to the pointer button event that was used. "
      (:GROUP (:FONT :FACE :I) "options-var")
      " is bound to any options that a presentation translator might have returned (the third value from the translator), and will be either "
      (:CL "nil") " or a list of keyword-value pairs. " (:GROUP (:FONT :FACE :I) "object-var") ", "
      (:GROUP (:FONT :FACE :I) "type-var") ", " (:GROUP (:FONT :FACE :I) "event-var") ", and "
      (:GROUP (:FONT :FACE :I) "options-var") " must all be symbols." (:PAR) (:GROUP (:FONT :FACE :I) "type") ", "
      (:GROUP (:FONT :FACE :I) "stream") ", and " (:GROUP (:FONT :FACE :I) "override")
      " are evaluated, the others are not." (:PAR) "For example, "
      (:PRE "
(with-input-context ('pathname)
                    (path)
     (read)
   (pathname
     (format t \"~&The pathname ~A was clicked on.\" path)))
")
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "accept")) :PARAMS
       ((:I "type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "stream view  default default-type provide-default  insert-default replace-input history active-p  prompt prompt-mode display-default query-identifier  activation-gestures additional-activation-gestures  delimiter-gestures additional-delimiter-gestures"))
       :KIND ("Function"))
      (:PAR) "Requests input of type " (:GROUP (:FONT :FACE :I) "type") " from the " (:TERM "stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ", which defaults to " (:CL "*standard-input*") ". " (:CL "accept")
      " returns two values, the object representing the input and its presentation type. "
      (:GROUP (:FONT :FACE :I) "type")
      " is a presentation type specifier, and can be an abbreviation. The other arguments and overall behavior of "
      (:CL "accept") " are as for " (:CL "accept-1") "." (:PAR) (:CL "accept")
      " must be implemented by first expanding any presentation type abbreviations (" (:GROUP (:FONT :FACE :I) "type")
      ", " (:GROUP (:FONT :FACE :I) "default-type") ", and " (:GROUP (:FONT :FACE :I) "history")
      "), handling the interactions between the default, default type, and presentation history, prompting the user by calling "
      (:CL "prompt-for-accept") ", and then calling " (:CL "stream-accept") " on " (:GROUP (:FONT :FACE :I) "stream")
      ", " (:GROUP (:FONT :FACE :I) "type") ", and the remaining keyword arguments." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-accept")) :PARAMS
       ((:I "stream type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "view  default default-type provide-default  insert-default replace-input history active-p  prompt prompt-mode display-default query-identifier  activation-gestures additional-activation-gestures  delimiter-gestures additional-delimiter-gestures"))
       :KIND ("Generic Function"))
      (:PAR) (:CL "stream-accept") " is the per-stream implementation of " (:CL "accept")
      ", analogous to the relationship between " (:CL "read-char") " and " (:CL "stream-read-char")
      ". All extended input streams must implement a method for " (:CL "stream-accept") ". The default method (on "
      (:CL "standard-extended-input-stream") ") simply calls " (:CL "accept-1") "." (:PAR)
      "The arguments and overall behavior of " (:CL "stream-accept") " are as for " (:CL "accept-1") "." (:PAR)
      (:GROUP (:FONT :FACE :B) "Rationale:") " the reason " (:CL "accept")
      " is specified as a three-function \"trampoline\" is to allow close tailoring of the behavior of " (:CL "accept")
      ". " (:CL "accept")
      " itself is the function that should be called by application programmers. CLIM implementors will specialize "
      (:CL "stream-accept") " on a per-stream basis. (For example, the behavior of " (:CL "accepting-values")
      " can be implemented by creating a special class of stream that turns calls to " (:CL "accept")
      " into fields of a dialog.) " (:CL "accept-1") " is provided as a convenient function for the "
      (:CL "stream-accept") " methods to call when they require the default behavior." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "accept-1")) :PARAMS
       ((:I "stream type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "view  default default-type provide-default  insert-default replace-input history active-p  prompt prompt-mode display-default query-identifier  activation-gestures additional-activation-gestures  delimiter-gestures additional-delimiter-gestures"))
       :KIND ("Function"))
      (:PAR) "Requests input of type " (:GROUP (:FONT :FACE :I) "type") " from the " (:TERM "stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ". " (:GROUP (:FONT :FACE :I) "type")
      " must be a presentation type specifier. " (:GROUP (:FONT :FACE :I) "view") " is a view object that defaults to "
      (:CL "stream-default-view") " of " (:GROUP (:FONT :FACE :I) "stream") ". " (:CL "accept-1")
      " returns two values, the object representing the input and its presentation type. (If "
      (:CL "frame-maintain-presentation-histories") " is " (:TERM "true")
      " for the current frame, then the returned object is also pushed on to the presentation history for that object.)"
      (:PAR) (:CL "accept-1") " establishes an input context via " (:CL "with-input-context") ", and then calls the "
      (:CL "accept") " presentation method for " (:GROUP (:FONT :FACE :I) "type") " and "
      (:GROUP (:FONT :FACE :I) "view") ". When called on an interactive stream, " (:CL "accept")
      " must allow input editing; see Chapter " (:REF :NAME "input-editing")
      " for a discussion of input editing. The call to " (:CL "accept") " will be terminated when the " (:CL "accept")
      " method returns, or the user clicks on a sensitive presentation. The typing of an activation and delimiter character is typically one way in which a call to an "
      (:CL "accept") " method is terminated." (:PAR) "A top-level " (:CL "accept")
      " satisfied by keyboard input discards the terminating keyboard gesture (which will be either a delimiter or an activation gesture). A nested call to "
      (:CL "accept") " leaves the terminating gesture unread." (:PAR)
      "If the user clicked on a matching presentation, " (:CL "accept-1")
      " will insert the object into the input buffer by calling " (:CL "presentation-replace-input")
      " on the object and type returned by the presentation translator, unless either the boolean "
      (:GROUP (:FONT :FACE :I) "replace-input") " is " (:TERM "false") " or the presentation translator returned an "
      (:CL ":echo") " option of " (:TERM "false") ". " (:GROUP (:FONT :FACE :I) "replace-input") " defaults to "
      (:TERM "true") ", but this default is overridden by the translator explicitly returning an " (:CL ":echo")
      " option of " (:TERM "false") "." (:PAR) "If " (:GROUP (:FONT :FACE :I) "default") " is supplied, then it and "
      (:GROUP (:FONT :FACE :I) "default-type") " are returned as values from " (:CL "accept-1")
      " when the input is empty. " (:GROUP (:FONT :FACE :I) "default-type")
      " must be a presentation type specifier. If " (:GROUP (:FONT :FACE :I) "default") " is not supplied and "
      (:GROUP (:FONT :FACE :I) "provide-default") " is " (:TERM "true") " (the default is " (:TERM "false")
      "), then the default is determined by taking the most recent item from the presentation type history specified by "
      (:GROUP (:FONT :FACE :I) "history") ". If " (:GROUP (:FONT :FACE :I) "insert-default") " is " (:TERM "true")
      " and there is a default, the default will be inserted into the input stream by calling "
      (:CL "presentation-replace-input") "." (:PAR) (:GROUP (:FONT :FACE :I) "history") " must be either " (:CL "nil")
      ", meaning that no presentation type history will be used, or a presentation type (or abbreviation) that names a history to be used for the call to "
      (:CL "accept") ". " (:GROUP (:FONT :FACE :I) "history") " defaults to " (:GROUP (:FONT :FACE :I) "type") "."
      (:PAR) (:GROUP (:FONT :FACE :I) "prompt") " can be " (:CL "t") ", which prompts by describing the type, "
      (:CL "nil") ", which suppresses prompting, or a string, which is displayed as a prompt (via "
      (:CL "write-string") "). The default is " (:CL "t") ", which produces \"Enter a "
      (:GROUP (:FONT :FACE :I) "type") ":\" in a top-level call to " (:CL "accept") " or \"("
      (:GROUP (:FONT :FACE :I) "type") ")\" in a nested call to " (:CL "accept") "." (:PAR) "If the boolean "
      (:GROUP (:FONT :FACE :I) "display-default") " is " (:TERM "true")
      ", the default is displayed (if one was supplied). If " (:GROUP (:FONT :FACE :I) "display-default") " is "
      (:TERM "false") ", the default is not displayed. " (:GROUP (:FONT :FACE :I) "display-default") " defaults to "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "prompt") " was provided, otherwise it defaults to "
      (:TERM "false") "." (:PAR) (:GROUP (:FONT :FACE :I) "prompt-mode") " can be " (:CL ":normal")
      " (the default) or " (:CL ":raw")
      ", which suppresses putting a colon after the prompt and/or default in a top-level " (:CL "accept")
      " and suppresses putting parentheses around the prompt and/or default in a nested " (:CL "accept") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "query-identifier") " is used within " (:CL "accepting-values")
      " to identify the field within the dialog. The " (:CL "active-p") " argument (which defaults to " (:CL "t")
      ") can be used to control whether a field within an " (:CL "accepting-values") " is active; when "
      (:TERM "false")
      ", the field will not be active, that is, it will not be available for input. Some CLIM implementations will provide a visual cue that the field is inactive, for instance, by \"graying out\" the field."
      (:PAR) (:GROUP (:FONT :FACE :I) "activation-gestures")
      " is a list of gesture names that will override the current activation gestures (which are stored in "
      (:CL "*activation-gestures*") "). Alternatively, " (:GROUP (:FONT :FACE :I) "additional-activation-gestures")
      " can be supplied to add activation gestures without overriding the current ones. See Chapter "
      (:REF :NAME "input-editing") " for a discussion of activation gestures." (:PAR)
      (:GROUP (:FONT :FACE :I) "delimiter-gestures")
      " is a list of gesture names that will override the current delimiter gestures (which are stored in "
      (:CL "*delimiter-gestures*") "). Alternatively, " (:GROUP (:FONT :FACE :I) "additional-delimiter-gestures")
      " can be supplied to add delimiter gestures without overriding the current ones. See Chapter "
      (:REF :NAME "input-editing") " for a discussion of delimiter gestures." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "accept-from-string")) :PARAMS
       ((:I "type string " (:GROUP (:FONT :FACE :TT) "&key ") "view default default-type start end")) :KIND
       ("Function"))
      (:PAR) "Like " (:CL "accept") ", except that the input is taken from " (:GROUP (:FONT :FACE :I) "string")
      ", starting at the position specified by " (:GROUP (:FONT :FACE :I) "start") " and ending at "
      (:GROUP (:FONT :FACE :I) "end") ". " (:GROUP (:FONT :FACE :I) "view") ", " (:GROUP (:FONT :FACE :I) "default")
      ", and " (:GROUP (:FONT :FACE :I) "default-type") " are as for " (:CL "accept") "." (:PAR)
      (:CL "accept-from-string") " returns an object and a presentation type (as in " (:CL "accept")
      "), but also returns a third value, the index at which input terminated." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "prompt-for-accept")) :PARAMS
       ((:I "stream type view " (:GROUP (:FONT :FACE :TT) "&rest ") "accept-args " (:GROUP (:FONT :FACE :TT) "&key ")))
       :KIND ("Generic Function"))
      (:PAR) "Called by " (:CL "accept") " to prompt the user for input of " (:TERM "presentation type") " "
      (:GROUP (:FONT :FACE :I) "type") " on the " (:TERM "stream") " " (:GROUP (:FONT :FACE :I) "stream") " for the "
      (:TERM "view") " " (:GROUP (:FONT :FACE :I) "view") ". " (:GROUP (:FONT :FACE :I) "accept-args")
      " are all of the keyword arguments supplied to " (:CL "accept") ". The default method (on "
      (:CL "standard-extended-input-stream") ") simply calls " (:CL "prompt-for-accept-1") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "prompt-for-accept-1")) :PARAMS
       ((:I "stream type  " (:GROUP (:FONT :FACE :TT) "&key ")
         "default default-type display-default  prompt prompt-mode  " (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
       :KIND ("Function"))
      (:PAR) "Prompts the user for input of " (:TERM "presentation type") " " (:GROUP (:FONT :FACE :I) "type")
      " on the " (:TERM "stream") " " (:GROUP (:FONT :FACE :I) "stream") "." (:PAR) "If the boolean "
      (:GROUP (:FONT :FACE :I) "display-default") " is " (:TERM "true")
      ", then the default is displayed; otherwise, the default is not displayed. When the default is being displayed, "
      (:GROUP (:FONT :FACE :I) "default") " and " (:GROUP (:FONT :FACE :I) "default-type")
      " are the taken as the object and presentation type of the default to display. "
      (:GROUP (:FONT :FACE :I) "display-default") " defaults to " (:TERM "true") " if "
      (:GROUP (:FONT :FACE :I) "prompt") " is non-" (:CL "nil") ", otherwise it defaults to " (:TERM "false") "."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "prompt") " is " (:CL "nil")
      ", no prompt is displayed. If it is a string, that string is displayed as the prompt. If "
      (:GROUP (:FONT :FACE :I) "prompt") " is " (:CL "t") " (the default), the prompt is generated by calling "
      (:CL "describe-presentation-type") " to produce a prompt of the form \"Enter a " (:GROUP (:FONT :FACE :I) "type")
      ":\" in a top-level call to " (:CL "accept") ", or \"(" (:GROUP (:FONT :FACE :I) "type")
      ")\" in a nested call to " (:CL "accept") "." (:PAR) (:GROUP (:FONT :FACE :I) "prompt-mode") " can be "
      (:CL ":normal") " (the default) or " (:CL ":raw")
      ", which suppresses putting a colon after the prompt and/or default in a top-level " (:CL "accept")
      " and suppresses putting parentheses around the prompt and/or default in a nested " (:CL "accept") "." (:PAR)
      " "))
    (:SECTION :TITLE ("23.6 " "Views") :KIND :SECTION :NAME (8 5 10) (:PAR) (:CL "accept") " and " (:CL "present")
     " methods can specialize on the " (:GROUP (:FONT :FACE :I) "view")
     " argument in order to define more than one view of the data. For example, a spreadsheet program might define a presentation type for quarterly earnings, which can be displayed as a floating point number or as a bar of some length in a bar graph. These two views might be implemented by specializing the view arguments for the "
     (:CL "textual-view") " class and the user-defined " (:CL "bar-graph-view") " class." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "view")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class for view objects. If you want to create a new class that behaves like a view, it should be a subclass of "
      (:CL "view") ". All instantiable subclasses of " (:CL "view") " must obey the view protocol. " (:PAR)
      "All of the view classes are immutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "viewp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "view") ", otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "textual-view")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class representing all textual views, a subclass of " (:CL "view")
      ". Presentation methods that apply to a textual view must only do textual input and output (such as "
      (:CL "read-char") " and " (:CL "write-string") ")." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "textual-menu-view")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that represents the default view that is used inside " (:CL "menu-choose")
      " for frame managers that are not using a gadget-oriented look and feel. It is a subclass of "
      (:CL "textual-view") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "textual-dialog-view")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that represents the default view that is used inside " (:CL "accepting-values")
      " dialogs for frame managers that are not using a gadget-oriented look and feel. It is a subclass of "
      (:CL "textual-view") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-view")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class representing all gadget views, a subclass of " (:CL "view") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-menu-view")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that represents the default view that is used inside " (:CL "menu-choose")
      " for frame managers that are using a gadget-oriented look and feel. It is a subclass of " (:CL "gadget-view")
      "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-dialog-view")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that represents the default view that is used inside " (:CL "accepting-values")
      " dialogs for frame managers that are using a gadget-oriented look and feel. It is a subclass of "
      (:CL "gadget-view") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-documentation-view")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that represents the default view that is used when computing pointer documentation. It is a subclass of "
      (:CL "textual-view") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "+textual-view+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+textual-menu-view+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+textual-dialog-view+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+gadget-view+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+gadget-menu-view+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+gadget-dialog-view+")) :PARAMS ((:I)) :KIND ("Constant"))
      (:SIGNATURE :NAME ((:CL "+pointer-documentation-view+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
      "These are objects of class " (:CL "textual-view") ", " (:CL "textual-menu-view") ", "
      (:CL "textual-dialog-view") ", " (:CL "gadget-view") ", " (:CL "gadget-menu-view") ", "
      (:CL "gadget-dialog-view") ", and " (:CL "pointer-documentation-view") ", respectively." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-default-view")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns the default view for the extended stream " (:GROUP (:FONT :FACE :I) "stream") ". " (:CL "accept")
      " and " (:CL "present") " get the default value for the " (:GROUP (:FONT :FACE :I) "view")
      " argument from this. All extended input and output streams must implement a method for this generic function."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf stream-default-view)")) :PARAMS ((:I "view stream")) :KIND ("Generic Function"))
      (:PAR) "Changes the default view for " (:GROUP (:FONT :FACE :I) "stream") " to the " (:TERM "view") " "
      (:GROUP (:FONT :FACE :I) "view")
      ". All extended input and output streams must implement a method for this generic function." (:PAR) " "))
    (:SECTION :TITLE ("23.7 " "Presentation Translators") :KIND :SECTION :NAME (8 5 10) (:PAR)
     "CLIM provides a mechanism for " (:CONCEPT "translating")
     " between types. In other words, within an input context for presentation type " (:GROUP (:FONT :FACE :I) "A")
     " the translator mechanism allows a programmer to define a translation from presentations of some other type "
     (:GROUP (:FONT :FACE :I) "B") " to objects that are of type " (:GROUP (:FONT :FACE :I) "A") "." (:PAR)
     "Note that the exact representation of a presentation translator has been left explicitly unspecified." (:PAR) " "
     (:SECTION :TITLE ("23.7.1 " "Defining Presentation Translators") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-presentation-translator")) :PARAMS
        ((:I "name  (from-type to-type command-table  " (:GROUP (:FONT :FACE :TT) "&key ")
          "gesture  tester tester-definitive  documentation pointer-documentation  menu priority)  arglist  "
          (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "Defines a presentation translator named " (:GROUP (:FONT :FACE :I) "name")
       " that translates from objects of type " (:GROUP (:FONT :FACE :I) "from-type") " to objects of type "
       (:GROUP (:FONT :FACE :I) "to-type") ". " (:GROUP (:FONT :FACE :I) "from-type") " and "
       (:GROUP (:FONT :FACE :I) "to-type")
       " are presentation type specifiers, but must not include any presentation type options. "
       (:GROUP (:FONT :FACE :I) "from-type") " and " (:GROUP (:FONT :FACE :I) "to-type")
       " may be presentation type abbreviations." (:PAR) (:GROUP (:FONT :FACE :I) "command-table") " is a "
       (:TERM "command table designator") ". The translator created by this invocation of "
       (:CL "define-presentation-translator") " will be stored in the command table "
       (:GROUP (:FONT :FACE :I) "command-table") "." (:PAR) (:GROUP (:FONT :FACE :I) "gesture")
       " is a gesture name that names a pointer gesture (described in Section " (:REF :NAME "gesture-names")
       "). The body of the translator will be run only if the translator is applicable and gesture used by the user matches the gesture name in the translator. (We will explain "
       (:CONCEPT "applicability") ", or " (:CONCEPT "matching") ", in detail below.) "
       (:GROUP (:FONT :FACE :I) "gesture") " defaults to " (:CL ":select") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "tester") " is either a function or a list of the form " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(tester-arglist . tester-body)") " " (:BR) " where "
       (:GROUP (:FONT :FACE :I) "tester-arglist") " takes the same form as " (:GROUP (:FONT :FACE :I) "arglist")
       " (see below), and " (:GROUP (:FONT :FACE :I) "tester-body")
       " is the body of the tester. The tester must return either " (:TERM "true") " or " (:TERM "false")
       ". If it returns " (:TERM "false") ", then the translator is definitely not applicable. If it returns "
       (:TERM "true") ", then the translator might be applicable, and the body of the translator might be run (if "
       (:GROUP (:FONT :FACE :I) "tester-definitive") " is " (:TERM "false")
       ") in order to definitively decide if the translator is applicable (this is described in more detail below). If no tester is supplied, CLIM supplies a tester that always returns "
       (:TERM "true") "." (:PAR) "When the boolean " (:GROUP (:FONT :FACE :I) "tester-definitive") " is "
       (:TERM "true")
       ", the body of the translator will never be run in order to decide if the translator is applicable, that is, the tester is assumed to definitively decide whether the translator applies. The default for "
       (:GROUP (:FONT :FACE :I) "tester-definitive") " is " (:TERM "false")
       ". When there is no explicitly supplied tester, the tester supplied by CLIM is assumed to be definitive." (:PAR)
       "Both " (:GROUP (:FONT :FACE :I) "documentation") " and " (:GROUP (:FONT :FACE :I) "pointer-documentation")
       " are objects that will be used for documenting the translator. "
       (:GROUP (:FONT :FACE :I) "pointer-documentation")
       " will be used to generate documentation for the pointer documentation window; the documentation generated by "
       (:GROUP (:FONT :FACE :I) "pointer-documentation")
       " should be very brief and computing it should be very fast and preferably not cons. "
       (:GROUP (:FONT :FACE :I) "documentation") " is used to generate such things as items in the " (:CL ":menu")
       "-gesture menu. If the object is a string, the string itself will be used as the documentation. Otherwise, the object must be the name of a function or a list of the form "
       (:BR) " " (:GROUP (:FONT :FACE :I) "(doc-arglist . doc-body)") " " (:BR) " where "
       (:GROUP (:FONT :FACE :I) "doc-arglist") " takes the same form as " (:GROUP (:FONT :FACE :I) "arglist")
       ", but includes a named (keyword) " (:GROUP (:FONT :FACE :I) "stream") " argument as well (see below), and "
       (:GROUP (:FONT :FACE :I) "doc-body")
       " is the body of the documentation function. The body of the documentation function should write the documentation to "
       (:GROUP (:FONT :FACE :I) "stream") ". The default for " (:GROUP (:FONT :FACE :I) "documentation") " is "
       (:CL "nil")
       ", meaning that there is no explicitly supplied documentation; in this case, CLIM is free to generate the documentation in other ways. The default for "
       (:GROUP (:FONT :FACE :I) "pointer-documentation") " is " (:GROUP (:FONT :FACE :I) "documentation") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "menu") " must be " (:CL "t") " or " (:CL "nil") ". When it is " (:CL "t")
       ", the translator will be included in the " (:CL ":menu") "-gesture menu if it matches. When it is " (:CL "nil")
       ", the translator will not be included in the " (:CL ":menu") "-gesture menu. Other non-" (:CL "nil")
       " values are reserved for future extensions to allow multiple presentation translator menus." (:PAR)
       (:GROUP (:FONT :FACE :I) "priority") " is either " (:CL "nil")
       " (the default, which corresponds to 0) or an integer that represents the priority of the translator. When there are several translators that match for the same gesture, the one with the highest priority is chosen."
       (:PAR) (:GROUP (:FONT :FACE :I) "arglist") ", " (:GROUP (:FONT :FACE :I) "tester-arglist") ", and "
       (:GROUP (:FONT :FACE :I) "doc-arglist")
       " are each an argument list that must \"match\" the following \"canonical\" argument list. " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(object " (:GROUP (:FONT :FACE :TT) "&key ")
        "presentation context-type frame event window x y)")
       " " (:BR)
       " In order to \"match\" the canonical argument list, there must be a single positional argument that corresponds to the presentation's object, and several named arguments that must match the canonical names above (using "
       (:CL "string-equal") " to do the comparison)." (:PAR)
       "In the body of the translator (or the tester), the positional " (:GROUP (:FONT :FACE :I) "object")
       " argument will be bound to the presentation's object. The named arguments "
       (:GROUP (:FONT :FACE :I) "presentation") " will be bound to the presentation that was clicked on, "
       (:GROUP (:FONT :FACE :I) "context-type")
       " will be bound to the presentation type of the context that actually matched, "
       (:GROUP (:FONT :FACE :I) "frame") " will be bound to the application frame that is currently active (usually "
       (:CL "*application-frame*") "), " (:GROUP (:FONT :FACE :I) "event")
       " will be bound to the pointer button event that the user used, " (:GROUP (:FONT :FACE :I) "window")
       " will be bound to the window stream from which the event came, and " (:GROUP (:FONT :FACE :I) "x") " and "
       (:GROUP (:FONT :FACE :I) "y") " will be bound to the " (:MATH "x") " and " (:MATH "y") " positions within "
       (:GROUP (:FONT :FACE :I) "window") " that the pointer was at when the event occurred. The special variable "
       (:CL "*input-context*") " will be bound to the current input context. Note that, in many implementations "
       (:GROUP (:FONT :FACE :I) "context-type") " and " (:CL "*input-context*")
       " will have dynamic extent, so programmers should not store without first copying them." (:PAR)
       (:GROUP (:FONT :FACE :I) "body")
       " is the body of the translator, and is run in the context of the application. "
       (:GROUP (:FONT :FACE :I) "body")
       " may have zero or more declarations as its first forms. It should return either one, two, or three values. The first value is an object which must be "
       (:CL "presentation-typep") " of " (:GROUP (:FONT :FACE :I) "to-type")
       ", and the second value is a presentation type that must be " (:CL "presentation-subtypep") " of "
       (:GROUP (:FONT :FACE :I) "to-type") ". The consequences are unspecified if the object is not "
       (:CL "presentation-typep") " of " (:GROUP (:FONT :FACE :I) "to-type") " or the type is not "
       (:CL "presentation-subtypep") " of " (:GROUP (:FONT :FACE :I) "to-type") ". The first two returned values of "
       (:GROUP (:FONT :FACE :I) "body") " are used, in effect, as the returned values for the call to " (:CL "accept")
       " that established the matching input context." (:PAR) "The third value returned by "
       (:GROUP (:FONT :FACE :I) "body") " must either be " (:CL "nil")
       " or a list of options (as keyword-value pairs) that will be interpreted by " (:CL "accept")
       ". The only option defined so far is " (:CL ":echo") ", whose value must be either " (:TERM "true")
       " (the default) or " (:TERM "false") ". If it is " (:TERM "true")
       ", the object returned by the translator will be \"echoed\" by " (:CL "accept") ", which will use "
       (:CL "presentation-replace-input")
       " to insert the textual representation of the object into the input buffer. If it is " (:TERM "false")
       ", the object will not be echoed." (:PAR) "None of " (:CL "define-presentation-translator")
       "'s arguments is evaluated." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-presentation-to-command-translator")) :PARAMS
        ((:I "name  (from-type command-name command-table  " (:GROUP (:FONT :FACE :TT) "&key ")
          "gesture tester  documentation pointer-documentation  menu priority echo)  arglist  "
          (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "This is similar to " (:CL "define-presentation-translator") ", except that the "
       (:GROUP (:FONT :FACE :I) "to-type") " will be derived to be the command named by "
       (:GROUP (:FONT :FACE :I) "command-name") " in the command table " (:GROUP (:FONT :FACE :I) "command-table") ". "
       (:GROUP (:FONT :FACE :I) "command-name") " is the name of the command that this translator will translate to."
       (:PAR) "The " (:GROUP (:FONT :FACE :I) "echo") " option is a boolean value (the default is " (:TERM "true")
       ") that indicates whether the command line should be echoed when a user invokes the translator." (:PAR)
       "The other arguments to " (:CL "define-presentation-to-command-translator") " are the same as for "
       (:CL "define-presentation-translator")
       ". Note that the tester for command translators is always assumed to be definitive, so there is no "
       (:CL ":tester-definitive") " option. The default for " (:GROUP (:FONT :FACE :I) "pointer-documentation")
       " is the string " (:GROUP (:FONT :FACE :I) "command-name")
       " with dash characters replaced by spaces, and each word capitalized (as in "
       (:CL "add-command-to-command-table") ")." (:PAR)
       "The body of the translator must return a list of the arguments to the command named by "
       (:GROUP (:FONT :FACE :I) "command-name") ". " (:GROUP (:FONT :FACE :I) "body")
       " is run in the context of the application. The returned value of the body, appended to the command name, are eventually passed to "
       (:CL "execute-frame-command") ". " (:GROUP (:FONT :FACE :I) "body")
       " may have zero or more declarations as its first forms." (:PAR) "None of "
       (:CL "define-presentation-to-command-translator") "'s arguments is evaluated." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-presentation-action")) :PARAMS
        ((:I "name  (from-type to-type command-table  " (:GROUP (:FONT :FACE :TT) "&key ")
          "gesture tester  documentation pointer-documentation  menu priority)  arglist  "
          (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) (:CL "define-presentation-action") " is similar to " (:CL "define-presentation-translator")
       ", except that the body of the action is not intended to return a value, but should instead side-effect some sort of application state."
       (:PAR)
       "A presentation action does not satisfy a request for input the way an ordinary translator does. Instead, an action is something that happens while waiting for input. After the action has been executed, the program continues to wait for the same input that it was waiting for prior to executing the action."
       (:PAR) "The other arguments to " (:CL "define-presentation-action") " are the same as for "
       (:CL "define-presentation-translator")
       ". Note that the tester for presentation actions is always assumed to be definitive." (:PAR) "None of "
       (:CL "define-presentation-action") "'s arguments is evaluated." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "define-drag-and-drop-translator")) :PARAMS
        ((:I "name  (from-type to-type destination-type command-table  " (:GROUP (:FONT :FACE :TT) "&key ")
          "gesture tester  documentation pointer-documentation  menu priority  feedback highlighting)  arglist  "
          (:GROUP (:FONT :FACE :TT) "&body ") "body"))
        :KIND ("Macro"))
       (:PAR) "Defines a \"drag and drop\" (or \"direct manipulation\") translator named "
       (:GROUP (:FONT :FACE :I) "name") " that translates from objects of type " (:GROUP (:FONT :FACE :I) "from-type")
       " to objects of type " (:GROUP (:FONT :FACE :I) "to-type")
       " when a \"from presentation\" is \"picked up\", \"dragged\" over, and \"dropped\" on to a \"to presentation\" having type "
       (:GROUP (:FONT :FACE :I) "destination-type") ". " (:GROUP (:FONT :FACE :I) "from-type") ", "
       (:GROUP (:FONT :FACE :I) "to-type") ", and " (:GROUP (:FONT :FACE :I) "destination-type")
       " are presentation type specifiers, but must not include any presentation type options. "
       (:GROUP (:FONT :FACE :I) "from-type") ", " (:GROUP (:FONT :FACE :I) "to-type") " and "
       (:GROUP (:FONT :FACE :I) "destination-type") " may be presentation type abbreviations." (:PAR)
       "The interaction style used by these translators is that a user points to a \"from presentation\" with the pointer, picks it up by pressing a pointer button matching "
       (:GROUP (:FONT :FACE :I) "gesture")
       ", drags the \"from presentation\" to a \"to presentation\" by moving the pointer, and then drops the \"from presentation\" onto the \"to presentation\". The dropping might be accomplished by either releasing the pointer button or clicking again, depending on the frame manager. When the pointer button is released, the translator whose "
       (:GROUP (:FONT :FACE :I) "destination-type")
       " matches the presentation type of the \"to presentation\" is chosen. For example, dragging a file to the TrashCan on a Macintosh could be implemented by a drag and drop translator."
       (:PAR) "While the pointer is being dragged, the function specified by " (:GROUP (:FONT :FACE :I) "feedback")
       " is invoked to provide feedback to the user. The function is called with eight arguments: the application frame object, the \"from presentation\", the stream, the initial "
       (:MATH "x") " and " (:MATH "y") " positions of the pointer, the current " (:MATH "x") " and " (:MATH "y")
       " positions of the pointer, and a feedback state (either " (:CL ":highlight") " to draw feedback, or "
       (:CL ":unhighlight")
       " to erase it). The feedback function is called to draw some feedback the first time pointer moves, and is then called twice each time the pointer moves thereafter (once to erase the previous feedback, and then to draw the new feedback). It is called a final time to erase the last feedback when the pointer button is released. "
       (:GROUP (:FONT :FACE :I) "feedback") " defaults to " (:CL "frame-drag-and-drop-feedback") "." (:PAR)
       "When the \"from presentation\" is dragged over any other presentation that has a direct manipulation translator, the function specified by "
       (:GROUP (:FONT :FACE :I) "highlighting")
       " is invoked to highlight that object. The function is called with four arguments: the application frame object, the \"to presentation\" to be highlighted or unhighlighted, the stream, and a highlighting state (either "
       (:CL ":highlight") " or " (:CL ":unhighlight") "). " (:GROUP (:FONT :FACE :I) "highlighting") " defaults to "
       (:CL "frame-drag-and-drop-highlighting") "." (:PAR)
       "Note that it is possible for there to be more than one drag and drop translator that applies to the same from-type, to-type, and gesture. In this case, the exact translator that is chosen for use during the dragging phase is unspecified. If these translators have different feedback, highlighting, documentation, or pointer documentation, the exact behavior is unspecified."
       (:PAR) "The other arguments to " (:CL "define-drag-and-drop-translator") " are the same as for "
       (:CL "define-presentation-translator") "." (:PAR) " "))
     (:SECTION :TITLE ("23.7.2 " "Presentation Translator Functions") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "find-presentation-translators")) :PARAMS ((:I "from-type to-type command-table")) :KIND
        ("Function"))
       (:PAR) "Returns a list of all of the translators in the " (:TERM "command table") " "
       (:GROUP (:FONT :FACE :I) "command-table") " that translate from " (:GROUP (:FONT :FACE :I) "from-type") " to "
       (:GROUP (:FONT :FACE :I) "to-type") ", without taking into account any type parameters or testers. "
       (:GROUP (:FONT :FACE :I) "from-type") " and " (:GROUP (:FONT :FACE :I) "to-type")
       " are presentation type specifiers, and must not be abbreviations. " (:GROUP (:FONT :FACE :I) "frame")
       " must be an application frame." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " Because "
       (:CL "find-presentation-translators")
       " is called during pointer sensitivity computations (that is, whenever the user mouses the pointer around in any CLIM pane), it should cache its result in order to avoid consing. Therefore, the resulting list of translators should not be modified; the consequences of doing so are unspecified."
       (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
       " The ordering of the list of translators is left unspecified, but implementations may find it convenient to return the list using the ordering specified for "
       (:CL "find-applicable-translators") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "test-presentation-translator")) :PARAMS
        ((:I "translator presentation context-type frame window x y  " (:GROUP (:FONT :FACE :TT) "&key ")
          "event modifier-state for-menu"))
        :KIND ("Function"))
       (:PAR) "Returns " (:TERM "true") " if the translator " (:GROUP (:FONT :FACE :I) "translator")
       " applies to the presentation " (:GROUP (:FONT :FACE :I) "presentation") " in input context type "
       (:GROUP (:FONT :FACE :I) "context-type") ", otherwise returns " (:TERM "false") ". (There is no "
       (:GROUP (:FONT :FACE :I) "from-type") " argument because it is derived from "
       (:GROUP (:FONT :FACE :I) "presentation") ".) " (:GROUP (:FONT :FACE :I) "x") " and "
       (:GROUP (:FONT :FACE :I) "y") " are the " (:MATH "x") " and " (:MATH "y")
       " positions of the pointer within the window stream " (:GROUP (:FONT :FACE :I) "window") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "event") " and " (:GROUP (:FONT :FACE :I) "modifier-state")
       " are a pointer button event and modifier state (see " (:CL "event-modifier-key-state")
       "), and are compared against the translator's gesture. " (:GROUP (:FONT :FACE :I) "event") " defaults to "
       (:CL "nil") ", and " (:GROUP (:FONT :FACE :I) "modifier-state")
       " defaults to 0, meaning that no modifier keys are held down. Only one of " (:GROUP (:FONT :FACE :I) "event")
       " or " (:GROUP (:FONT :FACE :I) "modifier-state")
       " may be supplied; it is unspecified what will happen if both are supplied." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "for-menu") " is " (:TERM "true") ", the comparison against "
       (:GROUP (:FONT :FACE :I) "event") " and " (:GROUP (:FONT :FACE :I) "modifier-state") " is not done." (:PAR)
       (:GROUP (:FONT :FACE :I) "presentation") ", " (:GROUP (:FONT :FACE :I) "context-type") ", "
       (:GROUP (:FONT :FACE :I) "frame") ", " (:GROUP (:FONT :FACE :I) "window") ", " (:GROUP (:FONT :FACE :I) "x")
       ", " (:GROUP (:FONT :FACE :I) "y") ", and " (:GROUP (:FONT :FACE :I) "event")
       " are passed along to the translator's tester if and when the tester is called." (:PAR)
       (:CL "test-presentation-translator")
       " is responsible for matching type parameters and calling the translator's tester. Under some circumstances, "
       (:CL "test-presentation-translator")
       " may also call the body of the translator to ensure that its value matches "
       (:GROUP (:FONT :FACE :I) "to-type") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "find-applicable-translators")) :PARAMS
        ((:I "presentation input-context frame window x y  " (:GROUP (:FONT :FACE :TT) "&key ")
          "event modifier-state for-menu fastp"))
        :KIND ("Function"))
       (:PAR) "Returns a list that describes the translators that definitely apply to the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation") " in the input context " (:GROUP (:FONT :FACE :I) "input-context")
       ". Each element in the returned list is of the form " (:BR) " "
       (:GROUP (:FONT :FACE :I) "(translator the-presentation context-type . rest)") " " (:BR) " where "
       (:GROUP (:FONT :FACE :I) "translator") " is a presentation translator, "
       (:GROUP (:FONT :FACE :I) "the-presentation")
       " is the presentation that the translator applies to (and can be different from "
       (:GROUP (:FONT :FACE :I) "presentation") " due to nesting of presentations), "
       (:GROUP (:FONT :FACE :I) "context-type") " is the context type in which the translator applies, and "
       (:GROUP (:FONT :FACE :I) "rest") " is other unspecified data reserved for internal use by CLIM. "
       (:GROUP (:FONT :FACE :I) "translator") ", " (:GROUP (:FONT :FACE :I) "the-presentation") ", and "
       (:GROUP (:FONT :FACE :I) "context-type") " can be passed to such functions as "
       (:CL "call-presentation-translator") " and " (:CL "document-presentation-translator") "." (:PAR)
       "Since input contexts can be nested, " (:CL "find-applicable-translators")
       " must iterate over all the contexts in " (:GROUP (:FONT :FACE :I) "input-context") ". "
       (:GROUP (:FONT :FACE :I) "window") ", " (:GROUP (:FONT :FACE :I) "x") ", and " (:GROUP (:FONT :FACE :I) "y")
       " are as for " (:CL "test-presentation-translator") ". " (:GROUP (:FONT :FACE :I) "event") " and "
       (:GROUP (:FONT :FACE :I) "modifier-state") " (which default to " (:CL "nil")
       " and the current modifier state for " (:GROUP (:FONT :FACE :I) "window")
       ", respectively) are used to further restrict the set of applicable translators. (Only one of "
       (:GROUP (:FONT :FACE :I) "event") " or " (:GROUP (:FONT :FACE :I) "modifier-state")
       " may be supplied; it is unspecified what will happen if both are supplied.)" (:PAR)
       "Presentations can also be nested. The ordering of the translators returned by "
       (:CL "find-applicable-translators")
       " is that translators matching inner contexts should precede translators matching outer contexts, and, in the same input context, inner presentations precede outer presentations."
       (:PAR) "When " (:GROUP (:FONT :FACE :I) "for-menu") " is non-" (:CL "nil") ", this matches the value of "
       (:GROUP (:FONT :FACE :I) "for-menu")
       " against the presentation's menu specification, and returns only those translators that match. "
       (:GROUP (:FONT :FACE :I) "event") " and " (:GROUP (:FONT :FACE :I) "modifier-state")
       " are disregarded in this case. " (:GROUP (:FONT :FACE :I) "for-menu") " defaults to " (:CL "nil") "." (:PAR)
       "When the boolean " (:GROUP (:FONT :FACE :I) "fastp") " is " (:TERM "true") ", "
       (:CL "find-applicable-translators") " will simply return " (:TERM "true") " if there are any translators. "
       (:GROUP (:FONT :FACE :I) "fastp") " defaults to " (:TERM "false") "." (:PAR) "When "
       (:GROUP (:FONT :FACE :I) "fastp") " is " (:TERM "false") ", the list of translators returned by "
       (:CL "find-applicable-translators")
       " must be in order of their \"desirability\", that is, translators having more specific from-types and/or higher priorities must precede translators having less specific from-types and lower priorities."
       (:PAR) "The rules used for ordering the translators returned by " (:CL "find-applicable-translators")
       " are as follows (in order):" (:PAR)
       (:OL
        (:LI
         "Translators with a higher \"high order\" priority precede translators with a lower \"high order\" priority. This allows programmers to set the priority of a translator in such a way that it always precedes all other translators."
         (:PAR))
        (:LI "Translators with a more specific \"from type\" precede translators with a less specific \"from type\"."
         (:PAR))
        (:LI
         "Translators with a higher \"low order\" priority precede translators with a lower \"low order\" priority. This allows programmers to break ties between translators that translate from the same type."
         (:PAR))
        (:LI
         "Translators from the current command table precede translators inherited from superior command tables. "))
       (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " " (:CL "find-applicable-translators")
       " could be implemented by looping over " (:GROUP (:FONT :FACE :I) "input-context") ", calling "
       (:CL "find-presentation-translators") " to generate all the translators, and then calling "
       (:CL "test-presentation-translator")
       " to filter out the ones that do not apply. The consequences of modifying the returned value are unspecified. Note that the ordering of translators can be done by "
       (:CL "find-presentation-translators") ", provided that " (:CL "find-applicable-translators")
       " takes care to preserve this ordering." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
       (:GROUP (:FONT :FACE :SL) "Describe and implement the " (:CL "class-nondisjoint-classes")
        " idea. Be very clear and precise about when the translator body gets run. --- SWM")
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "presentation-matches-context-type")) :PARAMS
        ((:I "presentation context-type frame window x y  " (:GROUP (:FONT :FACE :TT) "&key ") "event modifier-state"))
        :KIND ("Function"))
       (:PAR) "Returns " (:TERM "true") " if there are any translators that translate from the " (:TERM "presentation")
       " " (:GROUP (:FONT :FACE :I) "presentation") "'s type to the input context type "
       (:GROUP (:FONT :FACE :I) "context-type") ", otherwise returns " (:TERM "false") ". (There is no "
       (:GROUP (:FONT :FACE :I) "from-type") " argument because it is derived from "
       (:GROUP (:FONT :FACE :I) "presentation") ".) " (:GROUP (:FONT :FACE :I) "frame") ", "
       (:GROUP (:FONT :FACE :I) "window") ", " (:GROUP (:FONT :FACE :I) "x") ", " (:GROUP (:FONT :FACE :I) "y") ", "
       (:GROUP (:FONT :FACE :I) "event") ", and " (:GROUP (:FONT :FACE :I) "modifier-state") " are as for "
       (:CL "test-presentation-translator") "." (:PAR) "If there are no applicable translators, "
       (:CL "presentation-matches-context-type") " will return " (:TERM "false") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "call-presentation-translator")) :PARAMS
        ((:I "translator presentation context-type  frame event window x y")) :KIND ("Function"))
       (:PAR) "Calls the function that implements the body of the translator " (:GROUP (:FONT :FACE :I) "translator")
       " on the " (:TERM "presentation") " " (:GROUP (:FONT :FACE :I) "presentation") "'s object, and passes "
       (:GROUP (:FONT :FACE :I) "presentation") ", " (:GROUP (:FONT :FACE :I) "context-type") ", "
       (:GROUP (:FONT :FACE :I) "frame") ", " (:GROUP (:FONT :FACE :I) "event") ", " (:GROUP (:FONT :FACE :I) "window")
       ", " (:GROUP (:FONT :FACE :I) "x") ", and " (:GROUP (:FONT :FACE :I) "y")
       " to the body of the translator as well." (:PAR)
       "The returned values are the same as the values returned by the body of the translator, namely, the translated object and the translated type."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "document-presentation-translator")) :PARAMS
        ((:I "translator presentation context-type  frame event window x y  " (:GROUP (:FONT :FACE :TT) "&key ")
          "(stream " (:CL "*standard-output*") ") documentation-type"))
        :KIND ("Function"))
       (:PAR) "Computes the documentation string for the translator " (:GROUP (:FONT :FACE :I) "translator")
       " and outputs it to the stream " (:GROUP (:FONT :FACE :I) "stream") ". "
       (:GROUP (:FONT :FACE :I) "presentation") ", " (:GROUP (:FONT :FACE :I) "context-type") ", "
       (:GROUP (:FONT :FACE :I) "frame") ", " (:GROUP (:FONT :FACE :I) "event") ", " (:GROUP (:FONT :FACE :I) "window")
       ", " (:GROUP (:FONT :FACE :I) "x") ", and " (:GROUP (:FONT :FACE :I) "y") " are as for "
       (:CL "test-presentation-translator") "." (:PAR) (:CL "documentation-type") " must be either " (:CL ":normal")
       " or " (:CL ":pointer") ". If it is " (:CL ":normal")
       ", the usual translator documentation function is called. If it is " (:CL ":pointer")
       ", the translator's pointer documentation is called." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "call-presentation-menu")) :PARAMS
        ((:I "presentation input-context frame window x y  " (:GROUP (:FONT :FACE :TT) "&key ") "for-menu label"))
        :KIND ("Function"))
       (:PAR) "Finds all the applicable translators for the " (:TERM "presentation") " "
       (:GROUP (:FONT :FACE :I) "presentation") " in the input context " (:GROUP (:FONT :FACE :I) "input-context")
       ", creates a menu that contains all of the translators, and pops up the menu from which the user can choose a translator. After the translator is chosen, it is called with the arguments supplied to "
       (:CL "call-presentation-menu") " and the matching input context that was established by "
       (:CL "with-input-context") " is terminated." (:PAR) (:GROUP (:FONT :FACE :I) "window") ", "
       (:GROUP (:FONT :FACE :I) "x") ", " (:GROUP (:FONT :FACE :I) "y") ", and " (:GROUP (:FONT :FACE :I) "event")
       " are as for " (:CL "find-applicable-translators") ". " (:GROUP (:FONT :FACE :I) "for-menu")
       ", which defaults to " (:CL "t")
       ", is used to decide which of the applicable translators will go into the menu; only those translators whose "
       (:CL ":menu") " option matches " (:GROUP (:FONT :FACE :I) "menu") " will be included." (:PAR)
       (:GROUP (:FONT :FACE :I) "label") " is either a string to use as a label for the menu, or is " (:CL "nil")
       " (the default), meaning the menu will not be labelled." (:PAR) " "))
     (:SECTION :TITLE ("23.7.3 " "Finding Applicable Presentations") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "find-innermost-applicable-presentation")) :PARAMS
        ((:I "input-context window x y  " (:GROUP (:FONT :FACE :TT) "&key ") "frame modifier-state event")) :KIND
        ("Function"))
       (:PAR) "Given an input context " (:GROUP (:FONT :FACE :I) "input-context")
       ", an output recording window stream " (:GROUP (:FONT :FACE :I) "window") ", " (:MATH "x") " and " (:MATH "y")
       " positions " (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       ", returns the innermost presentation whose sensitivity region contains " (:GROUP (:FONT :FACE :I) "x") " and "
       (:GROUP (:FONT :FACE :I) "y")
       " that matches the innermost input context, using the translator matching algorithm described below. If there is no such presentation, this function will return "
       (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :I) "event") " and " (:GROUP (:FONT :FACE :I) "modifier-state")
       " are a pointer button event and modifier state (see " (:CL "event-modifier-key-state") "). "
       (:GROUP (:FONT :FACE :I) "event") " defaults to " (:CL "nil") ", and "
       (:GROUP (:FONT :FACE :I) "modifier-state") " defaults to the current modifier state for "
       (:GROUP (:FONT :FACE :I) "window") ". Only one of " (:GROUP (:FONT :FACE :I) "event") " or "
       (:GROUP (:FONT :FACE :I) "modifier-state")
       " may be supplied; it is unspecified what will happen if both are supplied." (:PAR)
       (:GROUP (:FONT :FACE :I) "frame") " defaults to the current frame, " (:CL "*application-frame*") "." (:PAR)
       "The default method for " (:CL "frame-find-innermost-applicable-presentation") " will call this function."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "throw-highlighted-presentation")) :PARAMS
        ((:I "presentation input-context button-press-event")) :KIND ("Function"))
       (:PAR) "Given a " (:TERM "presentation") " " (:GROUP (:FONT :FACE :I) "presentation") ", input context "
       (:GROUP (:FONT :FACE :I) "input-context") ", and a button press event (which contains the window, pointer, "
       (:MATH "x") " and " (:MATH "y")
       " position of the pointer within the window, the button pressed, and the modifier state), find the translator that matches the innermost presentation in the innermost input context, then call the translator to produce an object and a presentation type. Finally, the matching input context that was established by "
       (:CL "with-input-context") " will be terminated." (:PAR)
       "Note that it is possible that more than one translator having the same gesture may be applicable to "
       (:GROUP (:FONT :FACE :I) "presentation")
       " in the specified input context. In this case, the translator having the highest priority will be chosen. If there is more than one having the same priority, it is unspecified what translator will be chosen."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "highlight-applicable-presentation")) :PARAMS
        ((:I "frame stream input-context  " (:GROUP (:FONT :FACE :TT) "&optional ") "prefer-pointer-window")) :KIND
        ("Function"))
       (:PAR) "This is the core of the \"input wait\" handler used by " (:CL "with-input-context") " on behalf of the "
       (:TERM "application frame") " " (:GROUP (:FONT :FACE :I) "frame")
       ". It is responsible for locating the innermost applicable presentation on " (:GROUP (:FONT :FACE :I) "stream")
       " in the input context " (:GROUP (:FONT :FACE :I) "input-context")
       ", unhighlighting presentations that are not applicable, and highlighting the presentation that is applicable. Typically on entry to "
       (:CL "highlight-applicable-presentation") ", " (:GROUP (:FONT :FACE :I) "input-context")
       " will be the value of " (:CL "*input-context*") " and " (:GROUP (:FONT :FACE :I) "frame")
       " will be the value of " (:CL "*application-frame*") "." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "prefer-pointer-window") " is " (:TERM "true")
       " (the default), CLIM will highlight the applicable presentation on the same window that the pointer is located over. Otherwise, CLIM will highlight an applicable presentation on "
       (:GROUP (:FONT :FACE :I) "stream") "." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:")
       " This will probably use " (:CL "frame-find-innermost-applicable-presentation-at-position")
       " to locate the innermost presentation, and " (:CL "unhighlight-highlighted-presentation") " and "
       (:CL "set-highlighted-presentation") " to unhighlight and highlight presentations." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "set-highlighted-presentation")) :PARAMS
        ((:I "stream presentation " (:GROUP (:FONT :FACE :TT) "&optional ") "prefer-pointer-window")) :KIND
        ("Function"))
       (:PAR) "Highlights the " (:TERM "presentation") " " (:GROUP (:FONT :FACE :I) "presentation") " on "
       (:GROUP (:FONT :FACE :I) "stream") ". This must call " (:CL "highlight-presentation")
       " methods if that is appropriate." (:PAR) (:GROUP (:FONT :FACE :I) "prefer-pointer-window") " is as for "
       (:CL "highlight-applicable-presentation") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "unhighlight-highlighted-presentation")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&optional ") "prefer-pointer-window")) :KIND ("Function"))
       (:PAR) "Unhighlights any highlighted presentations on " (:GROUP (:FONT :FACE :I) "stream") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "prefer-pointer-window") " is as for " (:CL "highlight-applicable-presentation") "."
       (:PAR) " "))
     (:SECTION :TITLE ("23.7.4 " "Translator Applicability") :KIND :SUBSECTION :NAME (4 8 5 10) (:PAR)
      "The top-level \"input wait\", which is what you are in when inside of a " (:CL "with-input-context")
      ", is responsible for determining what translators are applicable to which presentations in a given input context. This loop both provides feedback in the form of highlighting sensitive presentation, and is responsible for calling the applicable translator when the user presses a pointer button."
      (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " " (:CL "with-input-context") " uses "
      (:CL "frame-find-innermost-applicable-presentation-at-position") " (via "
      (:CL "highlight-applicable-presentation") ") as its \"input wait\" handler, and "
      (:CL "frame-input-context-button-press-handler") " as its button press \"event handler\"." (:PAR)
      "Given a presentation, an input context established by " (:CL "with-input-context")
      ", and an event corresponding to a user gesture, translator matching proceeds as follows." (:PAR)
      "The set of candidate translators is initially those translators accessible in the command table in use by the current application. A translator is said to \"match\" if all of the following are true (in this order):"
      (:PAR)
      (:OL
       (:LI "The presentation's type is " (:CL "presentation-subtypep") " of the translator's "
        (:GROUP (:FONT :FACE :I) "from-type") ", ignoring type parameters." (:PAR))
       (:LI "The translator's " (:GROUP (:FONT :FACE :I) "to-type") " is " (:CL "presentation-subtypep")
        " of the input context type, ignoring type parameters." (:PAR))
       (:LI "The translator's gesture is either " (:CL "t")
        ", or matches the event corresponding to the user's gesture." (:PAR))
       (:LI "If there are parameters in the " (:GROUP (:FONT :FACE :I) "from-type")
        ", the presentation's object must be " (:CL "presentation-typep") " of the "
        (:GROUP (:FONT :FACE :I) "from-type") "." (:PAR))
       (:LI "The translator's tester returned " (:TERM "true")
        ". If there is no tester, the translator behaves as though there is a tester that always returns "
        (:TERM "true") "." (:PAR))
       (:LI
        "If there are parameters in the input context type and the tester is not declared to be definitive, the value returned by body of the translator must be "
        (:CL "presentation-typep") " of the context type. "))
      (:PAR) "Note that the type parameters from the presentation's type have no effect on translator lookup." (:PAR)
      (:CL "find-presentation-translator") " is responsible for the first two steps of the matching algorithm, and "
      (:CL "test-presentation-translator") " is responsible for the remaining steps." (:PAR)
      "When a single translator is being chosen (such as is done by " (:CL "throw-highlighted-presentation")
      "), it is possible that more than one translator having the same gesture may be applicable to the presentation in the specified input context. In this case, the translator having the highest priority will be chosen. If there is more than one having the same priority, it is unspecified what translator will be chosen."
      (:PAR)
      "The matching algorithm is somewhat more complicated in face of nested presentations and nested input contexts. In this case, the applicable presentation is the "
      (:GROUP (:FONT :FACE :SL) "smallest") " presentation that matches the " (:GROUP (:FONT :FACE :SL) "innermost")
      " input context." (:PAR)
      "Sometimes there may be nested presentations that have exactly the same bounding rectangle. In this case, it is not possible for a user to unambiguously point to just one of the nested presentations. Therefore, when CLIM has located the innermost applicable presentation in the innermost input context, it must then search for outer presentations having exactly the same bounding rectangle, checking to see if there are any applicable translators for those presentations. If there are multiple applicable translators, the one having the highest priority is chosen. "
      (:CL "find-applicable-translators") ", " (:CL "call-presentation-menu") ", "
      (:CL "throw-highlighted-presentation")
      ", and the computation of pointer documentation must all take this situation into account." (:PAR)
      "The translators are searched in the order that they are returned by " (:CL "find-presentation-translators")
      ". The rules for the ordering of the translators are described under that function." (:PAR) " "))
    (:SECTION :TITLE ("23.8 " "Standard Presentation Types") :KIND :SECTION :NAME (8 5 10) (:PAR)
     "The following sections document the presentation types supplied by CLIM. Any presentation type with the same name as a Common Lisp type accepts the same parameters as the Common Lisp type (and additional parameters in a few cases)."
     (:PAR) " "
     (:SECTION :TITLE ("23.8.1 " "Basic Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "t")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The supertype of all other presentation types." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "nil")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The subtype of all other presentation types. This has no printed representation, and it useful only in writing \"context independent\" translators, that is, translators whose "
       (:GROUP (:FONT :FACE :I) "to-type") " is " (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "null")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents \"nothing\". The single object associated with this type is " (:CL "nil")
       ", and its printed representation is \"None\"." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "boolean")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents " (:TERM "true") " or " (:TERM "false")
       ". The printed representation is \"Yes\" or \"No\", respectively." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "symbol")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents a symbol." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "keyword")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents a symbol in the keyword package. It is a subtype of " (:CL "symbol") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "blank-area")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents all the places in a window where there is no presentation that is applicable in the current input context. CLIM provides a single \"null presentation\" as the object associated with this type."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "*null-presentation*")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
       "The null presentation, which occupies all parts of a window in which there are no applicable presentations. This will have a presentation type of "
       (:CL "blank-area") "." (:PAR) " "))
     (:SECTION :TITLE ("23.8.2 " "Numeric Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "number")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents a general number. It is the supertype of all the number types." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "complex")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "type")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that represents a complex number. It is a subtype of " (:CL "number") "." (:PAR)
       "The components of the complex number are of type " (:GROUP (:FONT :FACE :I) "type") ", which must be "
       (:CL "real") " or a subtype of " (:CL "real") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "real")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "low high")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that represents either a ratio, an integer, or a floating point number between "
       (:GROUP (:FONT :FACE :I) "low") " and " (:GROUP (:FONT :FACE :I) "high") ". " (:GROUP (:FONT :FACE :I) "low")
       " and " (:GROUP (:FONT :FACE :I) "high")
       " can be inclusive or exclusive, as in Common Lisp type specifiers. Options to this type are "
       (:GROUP (:FONT :FACE :I) "base") " (default 10) and " (:GROUP (:FONT :FACE :I) "radix") " (default " (:CL "nil")
       "). " (:CL "real") " is a subtype of " (:CL "number") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "rational")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "low high")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that represents either a ratio or an integer between " (:GROUP (:FONT :FACE :I) "low") " and "
       (:GROUP (:FONT :FACE :I) "high") ". Options to this type are " (:GROUP (:FONT :FACE :I) "base") " and "
       (:GROUP (:FONT :FACE :I) "radix") ". " (:CL "rational") " is a subtype of " (:CL "real") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "integer")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "low high")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that represents an integer between " (:GROUP (:FONT :FACE :I) "low") " and "
       (:GROUP (:FONT :FACE :I) "high") ". Options to this type are " (:GROUP (:FONT :FACE :I) "base") " and "
       (:GROUP (:FONT :FACE :I) "radix") ". " (:CL "integer") " is a subtype of " (:CL "rational") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "ratio")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "low high")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that represents a ratio between " (:GROUP (:FONT :FACE :I) "low") " and "
       (:GROUP (:FONT :FACE :I) "high") ". Options to this type are " (:GROUP (:FONT :FACE :I) "base") " and "
       (:GROUP (:FONT :FACE :I) "radix") ". " (:CL "ratio") " is a subtype of " (:CL "rational") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "float")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "low high")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that represents a floating point number between " (:GROUP (:FONT :FACE :I) "low") " and "
       (:GROUP (:FONT :FACE :I) "high") ". " (:CL "float") " is a subtype of " (:CL "number") "." (:PAR) " "))
     (:SECTION :TITLE ("23.8.3 " "Character and String Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "character")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents a character object." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "string")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "length")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that represents a string. If " (:GROUP (:FONT :FACE :I) "length")
       " is supplied, the string must contain exactly that many characters." (:PAR) " "))
     (:SECTION :TITLE ("23.8.4 " "Pathname Presentation Type") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "pathname")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type that represents a pathname. The options are " (:GROUP (:FONT :FACE :I) "default-version")
       ", which defaults to " (:CL ":newest") ", " (:GROUP (:FONT :FACE :I) "default-type") ", which defaults to "
       (:CL "nil") ", and " (:GROUP (:FONT :FACE :I) "merge-default") ", which defaults to " (:TERM "true") ". If "
       (:GROUP (:FONT :FACE :I) "merge-default") " is " (:TERM "false") ", " (:CL "accept")
       " returns the exact pathname that was entered, otherwise " (:CL "accept") " merges against the default and "
       (:GROUP (:FONT :FACE :I) "default-version") ". If no default is supplied, it defaults to "
       (:CL "*default-pathname-defaults*") ". The " (:CL "pathname")
       " type should have a default preprocessor that merges the options into the default." (:PAR) " "))
     (:SECTION :TITLE ("23.8.5 " "\"One-of\" and \"Some-of\" Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10)
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "completion")) :PARAMS
        ((:I "sequence " (:GROUP (:FONT :FACE :TT) "&key ") "test value-key")) :KIND ("Presentation Type"))
       (:PAR)
       "The type that selects one from a finite set of possibilities, with \"completion\" of partial inputs. The member types below, "
       (:CL "token-or-type") ", and " (:CL "null-or-type") " are implemented in terms of the " (:CL "completion")
       " type." (:PAR) (:GROUP (:FONT :FACE :I) "sequence")
       " is a list or vector whose elements are the possibilities. Each possibility has a printed representation, called its name, and an internal representation, called its value. "
       (:CL "accept") " reads a name and returns a value. " (:CL "present") " is given a value and outputs a name."
       (:PAR) (:GROUP (:FONT :FACE :I) "test") " is a function that compares two values for equality. The default is "
       (:CL "eql") "." (:PAR) (:GROUP (:FONT :FACE :I) "value-key")
       " is a function that returns a value given an element of " (:GROUP (:FONT :FACE :I) "sequence")
       ". The default is " (:CL "identity") "." (:PAR) "The following presentation type options are available:" (:PAR)
       (:GROUP (:FONT :FACE :I) "name-key") " is a function that returns a name, as a string, given an element of "
       (:GROUP (:FONT :FACE :I) "sequence") ". The default is a function that behaves as follows: " (:BR) " "
       (:TABULAR
        (:TR
         (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " string "))
         (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:MATH (:ENTITY :NAME "rArr")) " "))
         (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " the string ")))
        (:TR
         (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " null "))
         (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:MATH (:ENTITY :NAME "rArr")) " "))
         (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:CL "\"NIL\"") " ")))
        (:TR
         (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1 (:GROUP " cons "))
         (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:MATH (:ENTITY :NAME "rArr")) " "))
         (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:CL "string") " of the " (:CL "car") " ")))
        (:TR
         (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " symbol "))
         (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:MATH (:ENTITY :NAME "rArr")) " "))
         (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:CL "string-capitalize") " of its name ")))
        (:TR
         (:TD :ALIGN :RIGHT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " otherwise "))
         (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:MATH (:ENTITY :NAME "rArr")) " "))
         (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
          (:GROUP " " (:CL "princ-to-string") " of it "))))
       (:PAR) (:GROUP (:FONT :FACE :I) "documentation-key") " is a function that returns either " (:CL "nil")
       " or a descriptive string, given an element of " (:GROUP (:FONT :FACE :I) "sequence")
       ". The default always returns " (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :I) "test") ", "
       (:GROUP (:FONT :FACE :I) "value-key") ", " (:GROUP (:FONT :FACE :I) "name-key") ", and "
       (:GROUP (:FONT :FACE :I) "documentation-key") " must have indefinite extent." (:PAR)
       (:GROUP (:FONT :FACE :I) "partial-completers")
       " is a possibly-empty list of characters that delimit portions of a name that can be completed separately. The default is a list of one character, "
       (:CODE "#\\Space") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "member")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "elements")) :KIND
        ("Presentation Type Abbreviation"))
       (:PAR) "The type that specifies one of " (:GROUP (:FONT :FACE :I) "elements")
       ". The options are the same as for " (:CL "completion") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "member-sequence")) :PARAMS ((:I "sequence " (:GROUP (:FONT :FACE :TT) "&key ") "test"))
        :KIND ("Presentation Type Abbreviation"))
       (:PAR) "Like " (:CL "member") ", except that the set of possibilities is the sequence "
       (:GROUP (:FONT :FACE :I) "sequence") ". The parameter " (:GROUP (:FONT :FACE :I) "test")
       " and the options are the same as for " (:CL "completion") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "member-alist")) :PARAMS ((:I "alist " (:GROUP (:FONT :FACE :TT) "&key ") "test")) :KIND
        ("Presentation Type Abbreviation"))
       (:PAR) "Like " (:CL "member") ", except that the set of possibilities is the alist "
       (:GROUP (:FONT :FACE :I) "alist") ". Each element of " (:GROUP (:FONT :FACE :I) "alist")
       " is either an atom as in " (:CL "member-sequence") " or a list whose " (:CL "car")
       " is the name of that possibility and whose " (:CL "cdr") " is one of the following:" (:PAR)
       (:UL (:LI "The value (which must not be a cons)" (:PAR)) (:LI "A list of one element, the value" (:PAR))
        (:LI "A property list that can contain the following properties:  "
         (:UL (:LI (:CL ":value") "---the value  ") (:LI (:CL ":documentation") "---a descriptive string  ")) " "))
       (:PAR) "The " (:GROUP (:FONT :FACE :I) "test") " parameter and the options are the same as for "
       (:CL "completion") " except that " (:GROUP (:FONT :FACE :I) "value-key") " and "
       (:GROUP (:FONT :FACE :I) "documentation-key") " default to functions that support the specified alist format."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "subset-completion")) :PARAMS
        ((:I "sequence " (:GROUP (:FONT :FACE :TT) "&key ") "test value-key")) :KIND ("Presentation Type"))
       (:PAR)
       "The type that selects one or more from a finite set of possibilities, with \"completion\" of partial inputs. The parameters and options are the same as for "
       (:CL "completion") ", plus the additional options " (:GROUP (:FONT :FACE :I) "separator") " and "
       (:GROUP (:FONT :FACE :I) "echo-space") ", which are as for the " (:CL "sequence")
       " type. The subset types below are implemented in terms of the " (:CL "subset-completion") " type." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "subset")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "elements")) :KIND
        ("Presentation Type Abbreviation"))
       (:PAR) "The type that specifies a subset of " (:GROUP (:FONT :FACE :I) "elements")
       ". Values of this type are lists of zero or more values chosen from the possibilities in "
       (:GROUP (:FONT :FACE :I) "elements")
       ". The printed representation is the names of the elements separated by commas. The options are the same as for "
       (:CL "completion") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "subset-sequence")) :PARAMS ((:I "sequence " (:GROUP (:FONT :FACE :TT) "&key ") "test"))
        :KIND ("Presentation Type Abbreviation"))
       (:PAR) "Like " (:CL "subset") ", except that the set of possibilities is the sequence "
       (:GROUP (:FONT :FACE :I) "sequence") ". The parameter " (:GROUP (:FONT :FACE :I) "test")
       " and the options are the same as for " (:CL "completion") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "subset-alist")) :PARAMS ((:I "alist " (:GROUP (:FONT :FACE :TT) "&key ") "test")) :KIND
        ("Presentation Type Abbreviation"))
       (:PAR) "Like " (:CL "subset")
       ", except that the set of possibilities, the parameters, and the options are as for " (:CL "member-alist") "."
       (:PAR) " "))
     (:SECTION :TITLE ("23.8.6 " "Sequence Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "sequence")) :PARAMS ((:I "type")) :KIND ("Presentation Type")) (:PAR)
       "The type that represents a sequence of elements of type " (:GROUP (:FONT :FACE :I) "type") ". "
       (:GROUP (:FONT :FACE :I) "type") " can be a presentation type abbreviation. The printed representation of a "
       (:CL "sequence") " type is the elements separated by commas. It is unspecified whether " (:CL "accept")
       " returns a list or a vector." (:PAR) "The options to this type are " (:GROUP (:FONT :FACE :I) "separator")
       " and " (:GROUP (:FONT :FACE :I) "echo-space") ". " (:GROUP (:FONT :FACE :I) "separator")
       " is used to specify a character that will act as the separator between elements of the sequence; the default is the comma character "
       (:CODE "#\\,") ". " (:GROUP (:FONT :FACE :I) "echo-space") " must be " (:TERM "true") " or " (:TERM "false")
       "; when it is " (:TERM "true")
       " (the default) a space will be automatically inserted into the input buffer when the user types a separator character."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "sequence-enumerated")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "types")) :KIND
        ("Presentation Type"))
       (:PAR) (:CL "sequence-enumerated") " is like " (:CL "sequence")
       ", except that the type of each element in the sequence is individually specified. The elements of "
       (:GROUP (:FONT :FACE :I) "types") " can be presentation type abbreviations. It is unspecified whether "
       (:CL "accept") " returns a list or a vector." (:PAR) "The options to this type are "
       (:GROUP (:FONT :FACE :I) "separator") " and " (:GROUP (:FONT :FACE :I) "echo-space") ", which are as for the "
       (:CL "sequence") " type." (:PAR) " "))
     (:SECTION :TITLE ("23.8.7 " "\"Meta\" Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "or")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "types")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that is used to specify one of several types, for example, "
       (:CL "(or (member :all :none) integer)") ". The elements of " (:GROUP (:FONT :FACE :I) "types")
       " can be presentation type abbreviations. " (:CL "accept")
       " returns one of the possible types as its second value, not the original " (:CL "or")
       " presentation type specifier." (:PAR) "The " (:CL "accept") " method for " (:CL "or")
       " could be implemented by iteratively calling " (:CL "accept") " on each of the presentation types in "
       (:GROUP (:FONT :FACE :I) "types") ". It would establish a condition handler for " (:CL "parse-error") ", call "
       (:CL "accept") " on one of the types and return the result if no condition was signalled. If a "
       (:CL "parse-error") " is signalled, the " (:CL "accept") " method for " (:CL "or") " would call " (:CL "accept")
       " on the next type. When there are no more types, the " (:CL "accept") " method for " (:CL "or")
       " would itself signal a " (:CL "parse-error") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "and")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "types")) :KIND
        ("Presentation Type"))
       (:PAR) "The type that is used for \"multiple inheritance\". " (:CL "and")
       " is frequently used in conjunction with " (:CL "satisfies") ", for example, "
       (:CL "(and integer (satisfies oddp))") ". The elements of " (:GROUP (:FONT :FACE :I) "types")
       " can be presentation type abbreviations." (:PAR) "The " (:CL "and")
       " type has special syntax that supports the two \"predicates\", " (:CL "satisfies") " and " (:CL "not") ". "
       (:CL "satisfies") " and " (:CL "not") " cannot stand alone as presentation types and cannot be first in "
       (:GROUP (:FONT :FACE :I) "types") ". " (:CL "not") " can surround either " (:CL "satisfies")
       " or a presentation type." (:PAR) "The first type in " (:GROUP (:FONT :FACE :I) "types")
       " is the type whose methods will be used during calls to " (:CL "accept") " and " (:CL "present") "." (:PAR)
       " "))
     (:SECTION :TITLE ("23.8.8 " "Compound Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "token-or-type")) :PARAMS ((:I "tokens type")) :KIND ("Presentation Type Abbreviation"))
       (:PAR) "A compound type that is used to select one of a set of special tokens, or an object of type "
       (:GROUP (:FONT :FACE :I) "type") ". " (:GROUP (:FONT :FACE :I) "tokens") " is anything that can be used as the "
       (:GROUP (:FONT :FACE :I) "sequence") " parameter to " (:CL "member-alist")
       "; typically it is a list of symbols." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "null-or-type")) :PARAMS ((:I "type")) :KIND ("Presentation Type Abbreviation"))
       (:PAR) "A compound type that is used to select " (:CL "nil")
       ", whose printed representation is the special token \"None\", or an object of type "
       (:GROUP (:FONT :FACE :I) "type") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "type-or-string")) :PARAMS ((:I "type")) :KIND ("Presentation Type Abbreviation"))
       (:PAR) "A compound type that is used to select an object of type " (:GROUP (:FONT :FACE :I) "type")
       " or an arbitrary string, for example, " (:CL "(type-or-string integer)") ". Any input that " (:CL "accept")
       " cannot parse as the representation of an object of type " (:GROUP (:FONT :FACE :I) "type")
       " is returned as a string." (:PAR) " "))
     (:SECTION :TITLE ("23.8.9 " "Lisp Expression Presentation Types") :KIND :SUBSECTION :NAME (9 8 5 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "expression")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type used to represent any Lisp object. The standard " (:CL "print") " and " (:CL "read")
       " functions produce and accept the textual view of this type." (:PAR)
       "If a presentation history is maintained for the " (:CL "expression")
       " presentation type, it should be maintained separately for each instance of an application frame." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "form")) :PARAMS ((:I)) :KIND ("Presentation Type")) (:PAR)
       "The type used to represent a Lisp form. This is a subtype of " (:CL "expression")
       " and is equivalent except that some presentation translators produce " (:CL "quote") " forms." (:PAR)))))
   " "
   (:SECTION :TITLE ("24 " "Input Editing and Completion Facilities") :KIND :CHAPTER :NAME (5 10) " "
    (:LABEL :NAME "input-editing") (:PAR)
    "CLIM provides number of facilities to assist in writing presentation type parser functions, such as an interactive input editor and some \"completion\" facilities."
    (:PAR) " "
    (:SECTION :TITLE ("24.1 " "The Input Editor") :KIND :SECTION :NAME (5 5 10) (:PAR)
     "An input editing stream \"encapsulates\" an interactive stream, that is, most operations are handled by the encapsulated interactive stream, but some operations are handled directly by the input editing stream itself. (See Appendix "
     (:REF :NAME "encapsulating-streams") " for a discussion of encapsulating streams.)" (:PAR)
     "An input editing stream will have the following components:" (:PAR)
     (:UL (:LI "The encapsulated interactive stream." (:PAR))
      (:LI "A buffer with a fill pointer, which we shall refer to as " (:MATH "FP")
       ". The buffer contains all of the user's input, and " (:MATH "FP") " is the length of that input." (:PAR))
      (:LI "An insertion pointer, which we shall refer to as " (:MATH "IP")
       ". The insertion pointer is the point in the buffer at which the \"editing cursor\" is." (:PAR))
      (:LI "A scan pointer, which we shall refer to as " (:MATH "SP")
       ". The scan pointer is the point in the buffer from which CLIM will get the next input gesture object (in the sense of "
       (:CL "read-gesture") ")." (:PAR))
      (:LI
       "A \"rescan queued\" flag indicating that the programmer (or CLIM) requested that a \"rescan\" operation should take place before the next gesture is read from the user."
       (:PAR))
      (:LI
       "A \"rescan in progress\" flag that indicates that CLIM is rescanning the user's input, rather than reading freshly supplied gestures from the user. "))
     (:PAR)
     "The input editing stream may also have other components to store internal state, such as a slot to accumulate a numeric argument or remember the most recently used presentation history, and so forth. These other components are explicitly left unspecified."
     (:PAR)
     "The high level description of the operation of the input editor is that it reads either \"real\" gestures from the user (such as characters from the keyboard or pointer button events) or input editing commands. The input editing commands can modify the state of the input buffer. When such modifications take place, it is necessary to \"rescan\" the input buffer, that is, reset the scan pointer "
     (:MATH "SP")
     " to its original state and reparse the contents of the input editor buffer before reading any other gestures from the user. While this rescanning operation is taking place, the \"rescan in progress\" flag is set to "
     (:TERM "true") ". The relationship " (:MATH "SP" (:ENTITY :NAME "le") "IP" (:ENTITY :NAME "le") "FP")
     " always holds." (:PAR) "The overall control structure of the input editor is:" (:PAR)
     (:PRE "
(catch 'rescan                  ;thrown to when a rescan is invoked
  (reset-scan-pointer stream)   ;sets STREAM-RESCANNING-P to T
  (loop
     (funcall continuation stream)))
")
     (:PAR) "where " (:GROUP (:FONT :FACE :I) "stream") " is the input editing stream and "
     (:GROUP (:FONT :FACE :I) "continuation")
     " is the code supplied by the programmer, and typically contains calls to such functions as " (:CL "accept")
     " and " (:CL "read-token") " (which will eventually call " (:CL "stream-read-gesture")
     "). When a rescan operation is invoked, it has the effect of throwing to the " (:CL "rescan")
     " tag in the example above. The loop is terminated when an activation gesture is seen, and at that point the values produced by "
     (:GROUP (:FONT :FACE :I) "continuation") " are returned as values from the input editor." (:PAR)
     "The important point is that functions such as " (:CL "accept") ", " (:CL "read-gesture") ", and "
     (:CL "unread-gesture")
     " read (or restore) the next gesture object from the buffer at the position pointed to by the scan pointer "
     (:MATH "SP") ". However, insertion and input editing commands take place at the position pointed to by "
     (:MATH "IP")
     ". The purpose of the rescanning operation is to eventually ensure that all the input gestures issued by the user (typed characters, pointer button presses, and so forth) have been read by CLIM. During input editing, the input editor should maintain some sort of visible cursor to remind the user of the position of "
     (:MATH "IP") "." (:PAR) "The overall structure of " (:CL "stream-read-gesture") " on an input editing stream is:"
     (:PAR)
     (:PRE "
(progn
  (rescan-if-necessary stream)
  (loop
    ;; If SP is less than FP
    ;;   Then get the next gesture from the input editor buffer at SP
    ;;   and increment SP
    ;;   Else read the next gesture from the encapsulated stream
    ;;   and insert it into the buffer at IP
    ;; Set the \"rescan in progress\" flag to false
    ;; Call STREAM-PROCESS-GESTURE on the gesture
    ;;   If it was a \"real\" gesture
    ;;     Then exit with the gesture as the result
    ;;     Else it was an input editing command (which has already been
    ;;     processed), so continue looping
    ))
")
     (:PAR)
     "When a new gesture object is inserted into the input editor buffer, it is inserted at the insertion pointer "
     (:MATH "IP") ". If " (:MATH "IP = FP") ", this is accomplished by a " (:CL "vector-push-extend")
     "-like operation on the input buffer and " (:MATH "FP") ", and then incrementing " (:MATH "IP") ". If "
     (:MATH "IP<FP")
     ", CLIM must first \"make room\" for the new gesture in the input buffer, then insert the gesture at "
     (:MATH "IP") ", then increment both " (:MATH "IP") " and " (:MATH "FP") "." (:PAR)
     "When the user requests an input editor motion command, only the insertion pointer " (:MATH "IP")
     " is affected. Motion commands do not need to request a rescan operation." (:PAR)
     "When the user requests an input editor deletion command, the sequence of gesture objects at " (:MATH "IP")
     " are removed, and " (:MATH "IP") " and " (:MATH "FP")
     " must be modified to reflect the new state of the input buffer. Deletion commands (and other commands that modify the input buffer) must arrange for a rescan to occur when they are done modifying the buffer, either by calling "
     (:CL "queue-rescan") " or " (:CL "immediate-rescan") "." (:PAR)
     "CLIM implementations are free to put special objects in the input editor buffer, such as \"noise strings\" and \"accept results\". A \"noise string\" is used to represent some sort of in-line prompt and is never seen as input; the "
     (:CL "prompt-for-accept")
     " method may insert a noise string into the input buffer. An \"accept result\" is an object in the input buffer that is used to represent some object that was inserted into the input buffer (typically via a pointer gesture) that has no readable representation (in the Lisp sense); "
     (:CL "presentation-replace-input")
     " may create accept results. Noise strings are skipped over by input editing commands, and accept results are treated as a single gesture."
     (:PAR) " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "interactive-stream-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object")
      " is an interactive stream, that is, a bidrectional stream intended for user interactions. Otherwise it returns "
      (:TERM "false")
      ". This is exactly the same function as in X3J13 Common Lisp, except that in CLIM it is a generic function."
      (:PAR) "The input editor need only be fully implemented for interactive streams." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "input-editing-stream")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to an input editing stream. If you want to create a new class that behaves like an input editing stream, it should be a subclass of "
      (:CL "input-editing-stream") ". All instantiable subclasses of " (:CL "input-editing-stream")
      " must obey the input editing stream protocol. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "input-editing-stream-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an "
      (:TERM "input editing stream") " (that is, a stream of the sort created by a call to " (:CL "with-input-editing")
      "), otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-input-editing-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that implements CLIM's standard input editor. This is the class of stream created by calling "
      (:CL "with-input-editing") "." (:PAR) "Members of this class are mutable. " (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-input-editing")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "input-sensitizer initial-contents class)  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Establishes a context in which the user can edit the input typed in on the interactive stream "
      (:GROUP (:FONT :FACE :I) "stream") ". " (:GROUP (:FONT :FACE :I) "body")
      " is then executed in this context, and the values returned by " (:GROUP (:FONT :FACE :I) "body")
      " are returned as the values of " (:CL "with-input-editing") ". " (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to an input stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-input*") " is used. If "
      (:GROUP (:FONT :FACE :I) "stream") " is a stream that is not an interactive stream, then "
      (:CL "with-input-editing") " is equivalent to " (:CL "progn") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "input-sensitizer")
      ", if supplied, is a function of two arguments, a stream and a continuation function; the function has dynamic extent. The continuation, supplied by CLIM, is responsible for displaying output corresponding to the user's input on the stream. The "
      (:GROUP (:FONT :FACE :I) "input-sensitizer") " function will typically call " (:CL "with-output-as-presentation")
      " in order to make the output produced by the continuation sensitive." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "initial-contents")
      " is supplied, it must be either a string or a list of two elements, an object and a presentation type. If it is a string, the string will be inserted into the input buffer using "
      (:CL "replace-input")
      ". If it is a list, the printed representation of the object will be inserted into the input buffer using "
      (:CL "presentation-replace-input") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-input-editor-typeout")) :PARAMS
       ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream " (:GROUP (:FONT :FACE :TT) "&key ") "erase) "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Establishes a context inside of " (:CL "with-input-editing") " in which output can be done by "
      (:GROUP (:FONT :FACE :I) "body") " to the input editing stream " (:GROUP (:FONT :FACE :I) "stream") ". If "
      (:GROUP (:FONT :FACE :I) "erase") " is " (:TERM "true")
      ", the area underneath the typeout will be erased before the typeout is done. " (:CL "with-input-editor-typeout")
      " should call " (:CL "fresh-line") " before and after evaluating the body. " (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-input*") " is used. If "
      (:GROUP (:FONT :FACE :I) "stream") " is a stream that is not an input editing stream, then "
      (:CL "with-input-editor-typeout") " is equivalent to calling " (:CL "fresh-line")
      ", evaluating the body, and then calling " (:CL "fresh-line") " again." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "input-editor-format")) :PARAMS
       ((:I "stream format-string " (:GROUP (:FONT :FACE :TT) "&rest ") "format-args")) :KIND ("Generic Function"))
      (:PAR) "This function is like " (:CL "format")
      ", except that it is intended to be called on input editing streams. It arranges to insert \"noise strings\" in the input editor's input buffer. Programmers can use this to display in-line prompts in "
      (:CL "accept") " methods." (:PAR) "If " (:GROUP (:FONT :FACE :I) "stream")
      " is a stream that is not an input editing stream, then " (:CL "input-editor-format") " is equivalent to "
      (:CL "format") "." (:PAR) " ")
     (:SECTION :TITLE ("24.1.1 " "The Input Editing Stream Protocol") :KIND :SUBSECTION :NAME (2 5 5 10) (:PAR)
      "Input editing streams obey both the extended input and extended output stream protocols, and must support the generic functions that comprise those protocols. For the most part, this will simply entail \"trampolining\" those operations to the encapsulated interactive stream. However, some generic functions as "
      (:CL "stream-read-gesture") " and " (:CL "stream-unread-gesture")
      " will need methods that observe the use of the input editor's scan pointer." (:PAR)
      "Input editing streams will typically also implement methods for " (:CL "prompt-for-accept")
      " (in order to provide in-line prompting that interacts correctly with input editing) and " (:CL "stream-accept")
      " (in order to cause " (:CL "accept") " to obey the scan pointer)." (:PAR)
      "The following generic functions comprise the remainder of the input editing protocol, and must be implemented for all classes that inherit from "
      (:CL "input-editing-stream") "." (:PAR) " "
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-input-buffer")) :PARAMS ((:I "(stream " (:CL "input-editing-stream") ")")) :KIND
        ("Method"))
       (:PAR) "Returns the input buffer (that is, the string being edited) associated with the "
       (:TERM "input editing stream") " " (:GROUP (:FONT :FACE :I) "stream")
       ". This must be an unspecialized vector with a fill pointer. The fill pointer of the vector points past the last gesture object in the buffer. During input editing, this buffer is side-effected. The consequences of modifying the input buffer by means other than the specified API (such as "
       (:CL "replace-input") ") are unspecified." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-insertion-pointer")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "Returns an integer corresponding to the current input position in the " (:TERM "input editing stream")
       " " (:GROUP (:FONT :FACE :I) "stream")
       "'s buffer, that is, the point in the buffer at which the next user input gesture will be inserted. The insertion pointer will always be less than "
       (:CL "(fill-pointer (stream-input-buffer " (:GROUP (:FONT :FACE :I) "stream") "))")
       ". The insertion pointer can also be thought of as an editing cursor." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf stream-insertion-pointer)")) :PARAMS ((:I "pointer stream")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the input position of the " (:TERM "input editing stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " to " (:GROUP (:FONT :FACE :I) "pointer") ". "
       (:GROUP (:FONT :FACE :I) "pointer") " is an integer, and must be less than "
       (:CL "(fill-pointer (stream-input-buffer " (:GROUP (:FONT :FACE :I) "stream") "))") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-scan-pointer")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "Returns an integer corresponding to the current scan pointer in the " (:TERM "input editing stream") " "
       (:GROUP (:FONT :FACE :I) "stream") "'s buffer, that is, the point in the buffer at which calls to "
       (:CL "accept") " have stopped parsing input. The scan pointer will always be less than or equal to "
       (:CL "(stream-insertion-pointer " (:GROUP (:FONT :FACE :I) "stream") ")") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf stream-scan-pointer)")) :PARAMS ((:I "pointer stream")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the scan pointer of the " (:TERM "input editing stream") " " (:GROUP (:FONT :FACE :I) "stream")
       " to " (:GROUP (:FONT :FACE :I) "pointer") ". " (:GROUP (:FONT :FACE :I) "pointer")
       " is an integer, and must be less than or equal to "
       (:CL "(stream-insertion-pointer " (:GROUP (:FONT :FACE :I) "stream") ")") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "stream-rescanning-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
       (:PAR) "Returns the state of the " (:TERM "input editing stream") " " (:GROUP (:FONT :FACE :I) "stream")
       "'s \"rescan in progress\" flag, which is " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "stream")
       " is performing a rescan operation, otherwise it is " (:TERM "false")
       ". All extended input streams must implement a method for this, but non-input editing streams will always returns "
       (:TERM "false") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "reset-scan-pointer")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&optional ") "(scan-pointer " (:CL "0") ")")) :KIND
        ("Generic Function"))
       (:PAR) "Sets the " (:TERM "input editing stream") " " (:GROUP (:FONT :FACE :I) "stream") "'s scan pointer to "
       (:GROUP (:FONT :FACE :I) "scan-pointer") ", and sets the state of " (:CL "stream-rescanning-p") " to "
       (:TERM "true") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "immediate-rescan")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
       "Invokes a rescan operation immediately by \"throwing\" out to the most recent invocation of "
       (:CL "with-input-editing") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "queue-rescan")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
       "Indicates that a rescan operation on the " (:TERM "input editing stream") " "
       (:GROUP (:FONT :FACE :I) "stream")
       " should take place after the next non-input editing gesture is read by setting the \"rescan queued\" flag to "
       (:TERM "true") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "rescan-if-necessary")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&optional ") "inhibit-activation")) :KIND ("Generic Function"))
       (:PAR) "Invokes a rescan operation on the " (:TERM "input editing stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " if " (:CL "queue-rescan")
       " was called on the same stream and no intervening rescan operation has taken place. Resets the state of the \"rescan queued\" flag to "
       (:TERM "false") "." (:PAR) "If " (:GROUP (:FONT :FACE :I) "inhibit-activation") " is " (:TERM "false")
       ", the input line will not be activated even if there is an activation character in it." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "erase-input-buffer")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&optional ") "(start-position " (:CL "0") ")")) :KIND
        ("Generic Function"))
       (:PAR) "Erases the part of the display that corresponds to the input editor's buffer starting at the position "
       (:GROUP (:FONT :FACE :I) "start-position") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "redraw-input-buffer")) :PARAMS
        ((:I "stream " (:GROUP (:FONT :FACE :TT) "&optional ") "(start-position " (:CL "0") ")")) :KIND
        ("Generic Function"))
       (:PAR) "Displays the input editor's buffer starting at the position " (:GROUP (:FONT :FACE :I) "start-position")
       " on the interactive stream that is encapsulated by the " (:TERM "input editing stream") " "
       (:GROUP (:FONT :FACE :I) "stream") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-process-gesture")) :PARAMS ((:I "stream gesture type")) :KIND
        ("Generic Function"))
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "gesture") " is an input editing command, " (:CL "stream-process-gesture")
       " performs the input editing operation on the " (:TERM "input editing stream") " "
       (:GROUP (:FONT :FACE :I) "stream") " and returns " (:CL "nil") ". Otherwise, it returns the two values "
       (:GROUP (:FONT :FACE :I) "gesture") " and " (:GROUP (:FONT :FACE :I) "type") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-read-gesture")) :PARAMS
        ((:I "(stream " (:CL "standard-input-editing-stream") ") " (:GROUP (:FONT :FACE :TT) "&key "))) :KIND
        ("Method"))
       (:PAR) "Reads and returns a gesture from the user on the " (:TERM "input editing stream") " "
       (:GROUP (:FONT :FACE :I) "stream") "." (:PAR) "The " (:CL "stream-read-gesture") " method must call "
       (:CL "stream-process-gesture")
       ", which will either return a \"real\" gesture (such as a typed character, a pointer gesture, or a timeout) or will return "
       (:CL "nil") " (indicating that some sort of input editing operation was performed). "
       (:CL "stream-read-gesture")
       " must only return when a real gesture was been read; if an input editing operation was performed, "
       (:CL "stream-read-gesture") " will loop until a \"real\" gesture is typed by the user." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "stream-unread-gesture")) :PARAMS
        ((:I "(stream " (:CL "standard-input-editing-stream") ") gesture")) :KIND ("Method"))
       (:PAR) "Inserts the gesture " (:GROUP (:FONT :FACE :I) "gesture")
       " back into the input editor's buffer, maintaining the scan pointer." (:PAR) " "))
     (:SECTION :TITLE ("24.1.2 " "Suggestions for Input Editing Commands") :KIND :SUBSECTION :NAME (2 5 5 10) (:PAR)
      "An implementation of the input editor should provide a set of generally useful input editing commands. The exact set of these commands is unspecified, and the key bindings for these commands may vary from platform to platform. The following is a suggested minimum set of input editing commands and key bindings, taken roughly from EMACS."
      (:PAR)
      (:TABULAR
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-top: 1px solid;" :COLSPAN
         1 (:GROUP (:GROUP)))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-top: 1px solid;" :COLSPAN
         1 (:GROUP (:GROUP (:FONT :FACE :SL) "Suggested"))))
       (:TR
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP (:GROUP (:FONT :FACE :SL) "Input editor command")))
        (:TD :ALIGN :CENTER :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; " :COLSPAN 1
         (:GROUP (:GROUP (:FONT :FACE :SL) "key binding"))))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP " " " Forward character "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-right: 1px solid;border-top: 1px solid;" :COLSPAN 1
         (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-F") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Forward word "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-F") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Backward character "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-B") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Backward word "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-B") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Beginning of line "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-A") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " End of line "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-E") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Next line "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-N") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Previous line "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-P") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Beginning of buffer "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-<") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " End of buffer "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-<") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Delete next character "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-D") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Delete next word "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-D") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Delete previous character "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "Rubout") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Delete previous word "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "m-Rubout") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Kill to end of line "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-K") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Clear input buffer "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :SL) "varies") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Insert new line "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-O") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Transpose adjacent characters "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-T") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Transpose adjacent words "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-T") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Yank from kill ring "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-Y") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Yank from presentation history "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-meta-Y") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1 (:GROUP " Yank next item "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-Y") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Scroll output history forward "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE "padding: 0 .5ex; border-right: 1px solid;" :COLSPAN
         1 (:GROUP " " (:GROUP (:FONT :FACE :TT) "control-V") " ")))
       (:TR
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "border-bottom: 1px solid;padding: 0 .5ex; border-left: 1px solid;border-right: 1px solid;" :COLSPAN 1
         (:GROUP " Scroll output history backward "))
        (:TD :ALIGN :LEFT :VALIGN :BASELINE :NOWRAP :NOWRAP :STYLE
         "border-bottom: 1px solid;padding: 0 .5ex; border-right: 1px solid;" :COLSPAN 1
         (:GROUP " " (:GROUP (:FONT :FACE :TT) "meta-V") " "))))
      (:PAR) "An implementation of the input may also support \"numeric arguments\" (such as "
      (:GROUP (:FONT :FACE :TT) "control-0") ", " (:GROUP (:FONT :FACE :TT) "control-1") ", "
      (:GROUP (:FONT :FACE :TT) "meta-0")
      ", and so forth) that modify the behavior of the input editing commands. For instance, the motion and deletion commands should be repeated as many times as specified by the numeric argument. Furthermore, the accumulated numeric argument should be passed to the command processor in such a way that "
      (:CL "substitute-numeric-argument-marker")
      " can be used to insert the numeric argument into a command that was read via a keystroke accelerator." (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "add-input-editor-command")) :PARAMS ((:I "gestures function")) :KIND ("Function"))
       (:PAR) "Adds an input editing command that causes " (:GROUP (:FONT :FACE :I) "function")
       " to be executed when the specified gesture(s) are typed by the user. " (:GROUP (:FONT :FACE :I) "gestures")
       " is either a single gesture name, or a list of gesture names. When " (:GROUP (:FONT :FACE :I) "gestures")
       " is a sequence of gesture names, the function is executed only after all of the gestures are typed in order with no intervening gestures. (This is used to implement \"prefixed\" commands, such as the "
       (:GROUP (:FONT :FACE :TT) "control-X control-F") " command one might fix in EMACS.)" (:PAR) " ")))
    (:SECTION :TITLE ("24.2 " "Activation and Delimiter Gestures") :KIND :SECTION :NAME (5 5 10) (:PAR)
     "Activation gestures terminate an input \"sentence\", such as a command or anything else being read by "
     (:CL "accept")
     ". When an activation gesture is entered by the user, CLIM will cease reading input and \"execute\" the input that has been entered."
     (:PAR) "Delimiter gestures terminate an input \"word\", such as a recursive call to " (:CL "accept") "." (:PAR)
     " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "*activation-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "The set of currently active activation gestures. The global value of this must be " (:CL "nil")
      ". The exact format of " (:CL "*activation-gestures*") " is unspecified. " (:CL "*activation-gestures*")
      " and the elements in it may have dynamic extent." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*standard-activation-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "The default set of activation gestures. The exact set of standard activation is unspecified, but must include the gesture that corresponds to the "
      (:CODE "#\\Newline") " character." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-activation-gestures")) :PARAMS
       ((:I "(gestures " (:GROUP (:FONT :FACE :TT) "&key ") "override) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Specifies a list of gestures that terminate input during the execution of "
      (:GROUP (:FONT :FACE :I) "body") ". " (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms. " (:GROUP (:FONT :FACE :I) "gestures")
      " must be either a single gesture name or a form that evaluates to a list of gesture names." (:PAR)
      "If the boolean " (:GROUP (:FONT :FACE :I) "override") " is " (:TERM "true") ", then "
      (:GROUP (:FONT :FACE :I) "gestures") " will override the current activation gestures. If it is " (:TERM "false")
      " (the default), then " (:GROUP (:FONT :FACE :I) "gestures")
      " will be added to the existing set of activation gestures. " (:CL "with-activation-gestures") " must bind "
      (:CL "*activation-gestures*") " to the new set of activation gestures." (:PAR) "See also the "
      (:CL ":activation-gestures") " and " (:CL ":additional-activation-gestures") " options to " (:CL "accept") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "activation-gesture-p")) :PARAMS ((:I "gesture")) :KIND ("Function")) (:PAR)
      "Returns " (:TERM "true") " if the gesture object " (:GROUP (:FONT :FACE :I) "gesture")
      " is an activation gesture, otherwise returns " (:TERM "false") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "*delimiter-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "The set of currently active delimiter gestures. The global value of this must be " (:CL "nil")
      ". The exact format of " (:CL "*delimiter-gestures*") " is unspecified. " (:CL "*delimiter-gestures*")
      " and the elements in it may have dynamic extent." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-delimiter-gestures")) :PARAMS
       ((:I "(gestures " (:GROUP (:FONT :FACE :TT) "&key ") "override) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR)
      "Specifies a list of gestures that terminate an individual token, but not the entire input, during the execution of "
      (:GROUP (:FONT :FACE :I) "body") ". " (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms. " (:GROUP (:FONT :FACE :I) "gestures")
      " must be either a single gesture name or a form that evaluates to a list of gesture names." (:PAR)
      "If the boolean " (:GROUP (:FONT :FACE :I) "override") " is " (:TERM "true") ", then "
      (:GROUP (:FONT :FACE :I) "gestures") " will override the current delimiter gestures. If it is " (:TERM "false")
      " (the default), then " (:GROUP (:FONT :FACE :I) "gestures")
      " will be added to the existing set of delimiter gestures. " (:CL "with-delimiter-gestures") " must bind "
      (:CL "*delimiter-gestures*") " to the new set of delimiter gestures." (:PAR) "See also the "
      (:CL ":delimiter-gestures") " and " (:CL ":additional-delimiter-gestures") " options to " (:CL "accept") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "delimiter-gesture-p")) :PARAMS ((:I "gesture")) :KIND ("Function")) (:PAR)
      "Returns " (:TERM "true") " if the gesture object " (:GROUP (:FONT :FACE :I) "gesture")
      " is a delimiter gesture, otherwise returns " (:TERM "false") "." (:PAR) " "))
    (:SECTION :TITLE ("24.3 " "Signalling Errors Inside " (:GROUP (:FONT :FACE :TT) "present") " Methods") :KIND
     :SECTION :NAME (5 5 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "simple-parse-error")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The error that is signalled by " (:CL "simple-parse-error") ". This is a subclass of " (:CL "parse-error") "."
      (:PAR) "This condition handles two initargs, " (:CL ":format-string") " and " (:CL ":format-arguments")
      ", which are used to specify a control string and arguments for a call to " (:CL "format") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "simple-parse-error")) :PARAMS
       ((:I "format-string " (:GROUP (:FONT :FACE :TT) "&rest ") "format-arguments")) :KIND ("Function"))
      (:PAR) "Signals a " (:CL "simple-parse-error") " error while parsing an input token. Does not return. "
      (:GROUP (:FONT :FACE :I) "format-string") " and " (:GROUP (:FONT :FACE :I) "format-args") " are as for "
      (:CL "format") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "input-not-of-required-type")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The error that is signalled by " (:CL "input-not-of-required-type") ". This is a subclass of "
      (:CL "parse-error") "." (:PAR) "This condition handles two initargs, " (:CL ":string") " and " (:CL ":type")
      ", which specify a string to be used in an error message and the expected presentation type." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "input-not-of-required-type")) :PARAMS ((:I "object type")) :KIND ("Function"))
      (:PAR) "Reports that input does not satisfy the specified type by signalling an "
      (:CL "input-not-of-required-type") " error. " (:GROUP (:FONT :FACE :I) "object")
      " is a parsed object or an unparsed token (a string). " (:GROUP (:FONT :FACE :I) "type")
      " is a presentation type specifier. Does not return." (:PAR) " "))
    (:SECTION :TITLE ("24.4 " "Reading and Writing of Tokens") :KIND :SECTION :NAME (5 5 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "replace-input")) :PARAMS
       ((:I "stream new-input  " (:GROUP (:FONT :FACE :TT) "&key ") "start end buffer-start rescan")) :KIND
       ("Generic Function"))
      (:PAR) "Replaces the part of the " (:TERM "input editing stream") " " (:GROUP (:FONT :FACE :I) "stream")
      "'s input buffer that extends from " (:GROUP (:FONT :FACE :I) "buffer-start")
      " to its scan pointer with the string " (:GROUP (:FONT :FACE :I) "new-input") ". "
      (:GROUP (:FONT :FACE :I) "buffer-start") " defaults to the current input position of "
      (:GROUP (:FONT :FACE :I) "stream") ". " (:GROUP (:FONT :FACE :I) "start") " and " (:GROUP (:FONT :FACE :I) "end")
      " can be supplied to specify a subsequence of " (:GROUP (:FONT :FACE :I) "new-input") "; "
      (:GROUP (:FONT :FACE :I) "start") " defaults to 0 and " (:GROUP (:FONT :FACE :I) "end")
      " defaults to the length of " (:GROUP (:FONT :FACE :I) "new-input") "." (:PAR) (:CL "replace-input")
      " must queue a rescan by calling " (:CL "queue-rescan") " if the new input does not match the old input, or "
      (:GROUP (:FONT :FACE :I) "rescan") " is " (:TERM "true") "." (:PAR)
      "The returned value is the position in the input buffer." (:PAR)
      "All input editing streams must implement a method for this function." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "presentation-replace-input")) :PARAMS
       ((:I "stream object type view  " (:GROUP (:FONT :FACE :TT) "&key ")
         "buffer-start rescan  query-identifier for-context-type"))
       :KIND ("Generic Function"))
      (:PAR) "Like " (:CL "replace-input")
      ", except that the new input to insert into the input buffer is gotten by presenting "
      (:GROUP (:FONT :FACE :I) "object") " with the presentation type " (:GROUP (:FONT :FACE :I) "type") " and view "
      (:GROUP (:FONT :FACE :I) "view") ". " (:GROUP (:FONT :FACE :I) "buffer-start") " and "
      (:GROUP (:FONT :FACE :I) "rescan") " are as for " (:CL "replace-input") ", and "
      (:GROUP (:FONT :FACE :I) "query-identifier") " and " (:GROUP (:FONT :FACE :I) "for-context-type") " as as for "
      (:CL "present") "." (:PAR)
      "All input editing streams must implement a method for this function. Typically, this will be implemented by calling "
      (:CL "present-to-string") " on " (:GROUP (:FONT :FACE :I) "object") ", " (:GROUP (:FONT :FACE :I) "type") ", "
      (:GROUP (:FONT :FACE :I) "view") ", and " (:GROUP (:FONT :FACE :I) "for-context-type") ", and then calling "
      (:CL "replace-input") " on the resulting string." (:PAR)
      "If the object does not have a readable representation (in the Lisp sense), " (:CL "presentation-replace-input")
      " may create an \"accept result\" to represent the object, and insert that into the input buffer. For the purposes of input editing, \"accept results\" must be treated as a single input gesture."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "read-token")) :PARAMS
       ((:I "stream " (:GROUP (:FONT :FACE :TT) "&key ") "input-wait-handler pointer-button-press-handler click-only"))
       :KIND ("Function"))
      (:PAR) "Reads characters from the " (:TERM "interactive stream") " " (:GROUP (:FONT :FACE :I) "stream")
      " until it encounters a delimiter or activation gesture, or a pointer gesture. Returns the accumulated string that was delimited by the delimiter or activation gesture, leaving the delimiter unread."
      (:PAR) "If the first character of typed input is a quotation mark (" (:CODE "#\\\"") "), then "
      (:CL "read-token")
      " will ignore delimiter gestures until until another quotation mark is seen. When the closing quotation mark is seen, "
      (:CL "read-token") " will proceed as above." (:PAR) "If the boolean " (:GROUP (:FONT :FACE :I) "click-only")
      " is " (:TERM "true") ", then no keyboard input is allowed. In this case " (:CL "read-token")
      " will simply ignore any typed characters." (:PAR) (:GROUP (:FONT :FACE :I) "input-wait-handler") " and "
      (:GROUP (:FONT :FACE :I) "pointer-button-press-handler") " are as for " (:CL "stream-read-gesture") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "write-token")) :PARAMS
       ((:I "token stream " (:GROUP (:FONT :FACE :TT) "&key ") "acceptably")) :KIND ("Function"))
      (:PAR) (:CL "write-token") " is the opposite of " (:CL "read-token") " given the string "
      (:GROUP (:FONT :FACE :I) "token") ", it writes it to the " (:TERM "interactive stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ". If " (:GROUP (:FONT :FACE :I) "acceptably") " is " (:TERM "true")
      " and there are any characters in the token that are delimiter gestures (see the macro "
      (:CL "with-delimiter-gestures") "), then " (:CL "write-token") " will surround the token with quotation marks ("
      (:CODE "#\\\"") ")." (:PAR) "Typically, " (:CL "present") " methods will use " (:CL "write-token") " instead of "
      (:CL "write-string") "." (:PAR) " "))
    (:SECTION :TITLE ("24.5 " "Completion") :KIND :SECTION :NAME (5 5 10) (:PAR) "CLIM provides a "
     (:CONCEPT "completion")
     " facility that completes a string provided by a user against some set of possible completions (which are themselves strings). Each completion is associated with some Lisp object. CLIM implementations are encouraged to provide \"chunkwise\" completion, that is, if the user input consists of several tokens separated by \"partial delimiters\", CLIM should complete each token separately against the set of possibilities."
     (:PAR) " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "*completion-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "A list of the gesture names that cause " (:CL "complete-input")
      " to complete the user's input as fully as possible. The exact global contents of this list is unspecified, but must include the "
      (:CL ":complete") " gesture name." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*help-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "A list of the gesture names that cause " (:CL "accept") " and " (:CL "complete-input")
      " to display a (possibly input context-sensitive) help message, and for some presentation types a list of possibilities as well. The exact global contents of this list is unspecified, but must include the "
      (:CL ":help") " gesture name." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*possibilities-gestures*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "A list of the gesture names that cause " (:CL "complete-input")
      " to display a (possibly input context-sensitive) help message and a list of possibilities. The exact global contents of this list is unspecified, but must include the "
      (:CL ":possibilities") " gesture name." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "complete-input")) :PARAMS
       ((:I "stream function  " (:GROUP (:FONT :FACE :TT) "&key ")
         "partial-completers allow-any-input  possibility-printer (help-displays-possibilities t)"))
       :KIND ("Function"))
      (:PAR) "Reads input from the user from the " (:TERM "input editing stream") " "
      (:GROUP (:FONT :FACE :I) "stream") ", completing over a set of possibilities. " (:CL "complete-input")
      " is only required to work on input editing streams, but implementations may extend it to work on interactive streams as well."
      (:PAR) (:GROUP (:FONT :FACE :I) "function")
      " is a function of two arguments. It is called to generate the completion possibilities that match the user's input; it has dynamic extent. Usually, programmers will pass either "
      (:CL "complete-from-possibilities") " or " (:CL "complete-from-generator") " as the value of "
      (:GROUP (:FONT :FACE :I) "function")
      ". Its first argument is a string containing the user's input \"so far\". Its second argument is the completion mode, one of the following:"
      (:PAR)
      (:UL
       (:LI (:CL ":complete-limited")
        "---the function must complete the input up to the next partial delimiter. This is the mode used when the user types one of the partial completers."
        (:PAR))
       (:LI (:CL ":complete-maximal")
        "---the function must complete the input as much as possible. This is the mode used when the user issues a gesture that matches any of the gesture names in "
        (:CL "*completion-gestures*") "." (:PAR))
       (:LI (:CL ":complete")
        "---the function must complete the input as much as possible, except that if the user's input exactly matches one of the possibilities, even if it is a left substring of another possibility, the shorter possibility is returned as the result. This is the mode used when the user issues a delimiter or activation gesture that is not a partial completer."
        (:PAR))
       (:LI (:CL ":possibilities")
        "---the function must return an alist of the possible completions as its fifth value. This is the mode used when the user a gesture that matches any of the gesture names in "
        (:CL "*possibilities-gestures*") " or " (:CL "*help-gestures*") " (if "
        (:GROUP (:FONT :FACE :I) "help-displays-possibilities") " is " (:TERM "true") "). "))
      (:PAR) (:GROUP (:FONT :FACE :I) "function") " must return five values:" (:PAR)
      (:UL (:LI (:GROUP (:FONT :FACE :I) "string") "---the completed input string." (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "success") "---" (:TERM "true") " if completion was successful, otherwise "
        (:TERM "false") "." (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "object") "---the object corresponding to the completion, or " (:CL "nil")
        " if the completion was unsuccessful." (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "nmatches") "---the number of possible completions of the input." (:PAR))
       (:LI (:GROUP (:FONT :FACE :I) "possibilities")
        "---an alist of completions whose entries are a list of a string and an object, returned only when the completion mode is "
        (:CL ":possibilities") ". This list will be freshly created. "))
      (:PAR) (:CL "complete-input") " returns three values: " (:GROUP (:FONT :FACE :I) "object") ", "
      (:GROUP (:FONT :FACE :I) "success") ", and " (:GROUP (:FONT :FACE :I) "string")
      ". In addition, the printed representation of the completed input will be inserted into the input buffer of "
      (:GROUP (:FONT :FACE :I) "stream") " in place of the user-supplied string by calling " (:CL "replace-input") "."
      (:PAR) (:GROUP (:FONT :FACE :I) "partial-completers")
      " is a list of characters that delimit portions of a name that can be completed separately. The default is an empty list."
      (:PAR) "If the boolean " (:GROUP (:FONT :FACE :I) "allow-any-input") " is " (:TERM "true") ", then "
      (:CL "complete-input")
      " will return as soon as the user issues an activation gesture, even if the input is not any of the possibilities. If the input is not one of the possibilities, the three values returned by "
      (:CL "complete-input") " will be " (:CL "nil") ", " (:CL "t") ", and the string. The default for "
      (:GROUP (:FONT :FACE :I) "allow-any-input") " is " (:TERM "false") "." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "possibility-printer")
      " is supplied, it must be a function of three arguments, a possibility, a presentation type, and a stream; it has dynamic extent. The function displays the possibility on the stream. The possibility will be a list of two elements, the first being a string and the second being the object corresponding to the string."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "help-display-possibilities") " is " (:TERM "true")
      " (the default), then when the user issues a help gesture (a gesture that matches one of the gesture names in "
      (:CL "*help-gestures*") "), CLIM will display all the matching possibilities. If it is " (:TERM "false")
      ", then CLIM will not display the possibilities unless the user issues a possibility gesture (a gesture that matches one of the gesture names in "
      (:CL "*possibilities-gestures*") ")." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "simple-completion-error")) :PARAMS ((:I)) :KIND ("Condition")) (:PAR)
      "The error that is signalled by " (:CL "complete-input") " when no completion is found. This is a subclass of "
      (:CL "simple-parse-error") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "completing-from-suggestions")) :PARAMS
       ((:I "(stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "partial-completers allow-any-input  possibility-printer  (help-displays-possibilities " (:CL "t") "))  "
         (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Reads input from the " (:TERM "input editing stream") " " (:GROUP (:FONT :FACE :I) "stream")
      ", completing over a set of possibilities generated by calls to " (:CL "suggest") " within "
      (:GROUP (:FONT :FACE :I) "body") ". " (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms." (:PAR) (:CL "completing-from-suggestions")
      " returns three values, " (:GROUP (:FONT :FACE :I) "object") ", " (:GROUP (:FONT :FACE :I) "success") ", and "
      (:GROUP (:FONT :FACE :I) "string") (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to a stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-input*") " is used."
      (:PAR) (:GROUP (:FONT :FACE :I) "partial-completers") ", " (:GROUP (:FONT :FACE :I) "allow-any-input") ", and "
      (:GROUP (:FONT :FACE :I) "possibility-printer") " are as for " (:CL "complete-input") "." (:PAR)
      "Implementations will probably use " (:CL "complete-from-generator") " to implement this." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "suggest")) :PARAMS ((:I "completion object")) :KIND ("Function")) (:PAR)
      "Specifies one possibility for " (:CL "completing-from-suggestions") ". " (:GROUP (:FONT :FACE :I) "completion")
      " is a string, the printed representation of " (:GROUP (:FONT :FACE :I) "object") ". "
      (:GROUP (:FONT :FACE :I) "object") " is the internal representation." (:PAR)
      "It is permitted for this function to have lexical scope, and be defined only within the body of "
      (:CL "completing-from-suggestions") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "complete-from-generator")) :PARAMS
       ((:I "string function delimiters  " (:GROUP (:FONT :FACE :TT) "&key ") "(action " (:CL ":complete")
         ") predicate"))
       :KIND ("Function"))
      (:PAR) "Given an input string " (:GROUP (:FONT :FACE :I) "string") " and a list of delimiter characters "
      (:GROUP (:FONT :FACE :I) "delimiters") " that act as partial completion characters, "
      (:CL "complete-from-generator") " completes against the possibilities that are generated by the function "
      (:GROUP (:FONT :FACE :I) "generator") ". " (:GROUP (:FONT :FACE :I) "generator")
      " is a function of two arguments, the string " (:GROUP (:FONT :FACE :I) "string")
      " and another function that it calls in order to process the possibility; it has dynamic extent." (:PAR)
      (:GROUP (:FONT :FACE :I) "action") " will be one of " (:CL ":complete") ", " (:CL ":complete-maximal") ", "
      (:CL ":complete-limited") ", or " (:CL ":possibilities") ". These are described under the function "
      (:CL "complete-input") "." (:PAR) (:GROUP (:FONT :FACE :I) "predicate")
      " must be a function of one argument, an object. If the predicate returns " (:TERM "true")
      ", the possibility corresponding to the object is processed, otherwise it is not. It has dynamic extent." (:PAR)
      (:CL "complete-from-generator") " returns five values, the completed input string, the success value ("
      (:TERM "true") " if the completion was successful, otherwise " (:TERM "false")
      "), the object matching the completion (or " (:CL "nil")
      " if unsuccessful), the number of matches, and a list of possible completions if "
      (:GROUP (:FONT :FACE :I) "action") " was " (:CL ":possibilities") "." (:PAR)
      "This function is one that will typically be passed as the second argument to " (:CL "complete-input") "."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "complete-from-possibilities")) :PARAMS
       ((:I "string completions delimiters  " (:GROUP (:FONT :FACE :TT) "&key ") "(action " (:CL ":complete")
         ") predicate  name-key value-key"))
       :KIND ("Function"))
      (:PAR) " Given an input string " (:GROUP (:FONT :FACE :I) "string") " and a list of delimiter characters "
      (:GROUP (:FONT :FACE :I) "delimiters") " that act as partial completion characters, "
      (:CL "complete-from-possibilities") " completes against the possibilities in the sequence "
      (:GROUP (:FONT :FACE :I) "completions")
      ". The completion string is extracted from the possibilities in completions by applying "
      (:GROUP (:FONT :FACE :I) "name-key")
      ", which is a function of one argument. The object is extracted by applying "
      (:GROUP (:FONT :FACE :I) "value-key") ", which is a function of one argument. "
      (:GROUP (:FONT :FACE :I) "name-key") " defaults to " (:CL "first") ", and " (:GROUP (:FONT :FACE :I) "value-key")
      " defaults to " (:CL "second") "." (:PAR) (:GROUP (:FONT :FACE :I) "action") " will be one of " (:CL ":complete")
      ", " (:CL ":complete-maximal") ", " (:CL ":complete-limited") ", or " (:CL ":possibilities")
      ". These are described under the function " (:CL "complete-input") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "predicate") " must be a function of one argument, an object. If the predicate returns "
      (:TERM "true") ", the possibility corresponding to the object is processed, otherwise it is not." (:PAR)
      (:GROUP (:FONT :FACE :I) "predicate") ", " (:GROUP (:FONT :FACE :I) "name-key") ", and "
      (:GROUP (:FONT :FACE :I) "value-key") " have dynamic extent." (:PAR) (:CL "complete-from-possibilities")
      " returns five values, the completed input string, the success value (" (:TERM "true")
      " if the completion was successful, otherwise " (:TERM "false") "), the object matching the completion (or "
      (:CL "nil") " if unsuccessful), the number of matches, and a list of possible completions if "
      (:GROUP (:FONT :FACE :I) "action") " was " (:CL ":possibilities") "." (:PAR)
      "This function is one that will typically be passed as the second argument to " (:CL "complete-input") "." (:PAR)
      " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-accept-help")) :PARAMS ((:I "options " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR)
      "Binds the dynamic environment to control the documentation produced by help and possibilities gestures during user input in calls to "
      (:CL "accept") " with the dynamic scope of " (:GROUP (:FONT :FACE :I) "body") ". "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      (:GROUP (:FONT :FACE :I) "options")
      " is a list of option specifications. Each specification is itself a list of the form "
      (:GROUP (:FONT :FACE :I) "(help-option help-string)") ". " (:GROUP (:FONT :FACE :I) "help-option")
      " is either a symbol that is a " (:GROUP (:FONT :FACE :I) "help-type") " or a list of the form "
      (:GROUP (:FONT :FACE :I) "(help-type mode-flag)") "." (:PAR) (:GROUP (:FONT :FACE :I) "help-type")
      " must be one of:" (:PAR)
      (:UL
       (:LI (:CL ":top-level-help") "---specifies that " (:GROUP (:FONT :FACE :I) "help-string")
        " be used instead of the default help documentation provided by " (:CL "accept") "." (:PAR))
       (:LI (:CL ":subhelp") "---specifies that " (:GROUP (:FONT :FACE :I) "help-string")
        " be used in addition to the default help documentation provided by " (:CL "accept") ". "))
      (:PAR) (:GROUP (:FONT :FACE :I) "mode-flag") " must be one of:" (:PAR)
      (:UL
       (:LI (:CL ":append")
        "---specifies that the current help string be appended to any previous help strings of the same help type. This is the default mode."
        (:PAR))
       (:LI (:CL ":override")
        "---specifies that the current help string is the help for this help type; no lower-level calls to "
        (:CL "with-accept-help") " can override this. (" (:CL ":override") " works from the out-side in.)" (:PAR))
       (:LI (:CL ":establish-unless-overridden")
        "---specifies that the current help string be the help for this help type unless a higher-level call to "
        (:CL "with-accept-help") " has already established a help string for this help type in the " (:CL ":override")
        " mode. This is what " (:CL "accept") " uses to establish the default help. "))
      (:PAR) (:GROUP (:FONT :FACE :I) "help-string")
      " is a string or a function that returns a string. If it is a function, it receives three arguments, the stream, an action (either "
      (:CL ":help") " or " (:CL ":possibilities") ") and the help string generated so far." (:PAR)
      "None of the arguments is evaluated." (:PAR))))
   " "
   (:SECTION :TITLE ("25 " "Menu Facilities") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "menus") (:PAR)
    (:GROUP (:FONT :FACE :B) "Major issue: ") " "
    (:GROUP (:FONT :FACE :SL)
     "There is a general issue about how these menus fit in with the menus that might be provided by the underlying toolkit. For example, under what circumstances is CLIM allowed to directly use the menu facilities provided by the host? Should "
     (:CL ":leave-menu-visible t") " interact with the \"pushpin\" facility provided by OpenLook? --- SWM")
    (:PAR) " "
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "menu-choose")) :PARAMS
      ((:I "items " (:GROUP (:FONT :FACE :TT) "&key ")
        "associated-window printer presentation-type  default-item text-style label  cache unique-id id-test cache-value cache-test  max-width max-height n-rows n-columns  x-spacing y-spacing row-wise  cell-align-x cell-align-y  scroll-bars pointer-documentation"))
      :KIND ("Generic Function"))
     (:PAR) "Displays a menu whose choices are given by the elements of the sequence "
     (:GROUP (:FONT :FACE :I) "items")
     ". It returns three values: the value of the chosen item, the item itself, and the pointer button event corresponding to the gesture that the user used to select it. If the user aborts out of the menu, a single value is returned, "
     (:CL "nil") "." (:PAR) (:CL "menu-choose") " will call " (:CL "frame-manager-menu-choose")
     " on the frame manager being used by " (:GROUP (:FONT :FACE :I) "associated-window")
     " (or the frame manager of the current application frame). All of the arguments to " (:CL "menu-choose")
     " will be passed on to " (:CL "frame-manager-menu-choose") "." (:PAR))
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "frame-manager-menu-choose")) :PARAMS
      ((:I "frame-manager items  " (:GROUP (:FONT :FACE :TT) "&key ")
        "associated-window printer presentation-type  default-item text-style label  cache unique-id id-test cache-value cache-test  max-width max-height n-rows n-columns  x-spacing y-spacing row-wise  cell-align-x cell-align-y  scroll-bars pointer-documentation"))
      :KIND ("Generic Function"))
     (:PAR) "Displays a menu whose choices are given by the elements of the sequence "
     (:GROUP (:FONT :FACE :I) "items")
     ". It returns three values: the value of the chosen item, the item itself, and the pointer button event corresponding to the gesture that the user used to select it. If the user aborts out of the menu, a single value is returned, "
     (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :B) "Implementation note:") " the default method on "
     (:CL "standard-frame-manager")
     " will generally be implemented in terms of CLIM's own window stream and formatting facilities, such as using "
     (:CL "menu-choose-from-drawer") " on a stream allocated by " (:CL "with-menu")
     ". However, some frame managers may be able to use a native menu facility to handle most (if not all) menus. If the native menu facility cannot handle some cases, it can simply use "
     (:CL "call-next-method") " to invoke the default method." (:PAR) (:GROUP (:FONT :FACE :I) "items")
     " is a sequence of menu items. Each menu item has a visual representation derived from a display object, an internal representation that is a value object, and a set of menu item options. The form of a menu item is one of the following:"
     (:PAR)
     (:UL (:LI "An atom. The item is both the display object and the value object." (:PAR))
      (:LI "A cons. The " (:CL "car") " is the display object and the " (:CL "cdr")
       " is the value object. The value object must be an atom. If you need to return a list as the value, use the :value option in the list menu item format described below."
       (:PAR))
      (:LI "A list. The " (:CL "car")
       " is the display object and the cdr is a list of alternating option keywords and values. The value object is specified with the keyword "
       (:CL ":value") " and defaults to the display object if " (:CL ":value") " is not present. "))
     (:PAR) "The menu item options are:" (:PAR)
     (:UL (:LI (:CL ":value") "---specifies the value object." (:PAR))
      (:LI (:CL ":style") "---specifies the text style used to " (:CL "princ") " the display object when neither "
       (:GROUP (:FONT :FACE :I) "presentation-type") " nor " (:GROUP (:FONT :FACE :I) "printer") " is supplied."
       (:PAR))
      (:LI (:CL ":items") "---specifies a sequence of menu items for a sub-menu to be used if this item is selected."
       (:PAR))
      (:LI (:CL ":documentation") "---associates some documentation with the menu item. When "
       (:GROUP (:FONT :FACE :I) ":pointer-documentation") " is not " (:CL "nil")
       ", this will be used as pointer documentation for the item." (:PAR))
      (:LI (:CL ":active") "---when " (:TERM "true") " (the default), this item is active. When " (:TERM "false")
       ", the item is inactive, and cannot be selected. CLIM will generally provide some visual indication that an item is inactive, such as by \"graying over\" the item."
       (:PAR))
      (:LI (:CL ":type") "---specifies the type of the item. " (:CL ":item")
       " (the default) indicates that the item is a normal menu item. " (:CL ":label")
       " indicates that the item is simply an inactive label; labels will not be \"grayed over\". " (:CL ":divider")
       " indicates that the item serves as a divider between groups of other items; divider items will usually be drawn as a horizontal line. "))
     (:PAR) "The visual representation of an item depends on the " (:GROUP (:FONT :FACE :I) "printer") " and "
     (:GROUP (:FONT :FACE :I) "presentation-type") " keyword arguments. If "
     (:GROUP (:FONT :FACE :I) "presentation-type") " is supplied, the visual representation is produced by "
     (:CL "present") " of the menu item with that presentation type. Otherwise, if "
     (:GROUP (:FONT :FACE :I) "printer") " is supplied, the visual representation is produced by the "
     (:GROUP (:FONT :FACE :I) "printer") " function, which receives two arguments, the "
     (:GROUP (:FONT :FACE :I) "item") " and a " (:GROUP (:FONT :FACE :I) "stream") " to do output on. The "
     (:GROUP (:FONT :FACE :I) "printer")
     " function should output some text or graphics at the stream's cursor position, but need not call "
     (:CL "present") ". If neither " (:GROUP (:FONT :FACE :I) "presentation-type") " nor "
     (:GROUP (:FONT :FACE :I) "printer") " is supplied, the visual representation is produced by " (:CL "princ")
     " of the display object. Note that if " (:GROUP (:FONT :FACE :I) "presentation-type") " or "
     (:GROUP (:FONT :FACE :I) "printer")
     " is supplied, the visual representation is produced from the entire menu item, not just from the display object. CLIM implementations are free to use the menus provided by the underlying window system when possible; this is likely to be the case when the printer and presentation-type are the default, and no other options are supplied."
     (:PAR) (:GROUP (:FONT :FACE :I) "associated-window")
     " is the CLIM window with which the menu is associated. This defaults to the top-level window of the current application frame."
     (:PAR) (:GROUP (:FONT :FACE :I) "default-item") " is the menu item where the mouse will appear." (:PAR)
     (:GROUP (:FONT :FACE :I) "text-style") " is a text style that defines how the menu items are presented." (:PAR)
     (:GROUP (:FONT :FACE :I) "label") " is a string to which the menu title will be set." (:PAR)
     (:GROUP (:FONT :FACE :I) "printer")
     " is a function of two arguments used to print the menu items in the menu. The two arguments are the menu item and the stream to output it on. It has dynamic extent."
     (:PAR) (:GROUP (:FONT :FACE :I) "presentation-type") " specifies the presentation type of the menu items." (:PAR)
     (:GROUP (:FONT :FACE :I) "cache")
     " is a boolean that indicates whether CLIM should cache this menu for later use. (Caching menus might speed up later uses of the same menu.) If "
     (:GROUP (:FONT :FACE :I) "cache") " is " (:TERM "true") ", then " (:GROUP (:FONT :FACE :I) "unique-id") " and "
     (:GROUP (:FONT :FACE :I) "id-test") " serve to uniquely identify this menu. When cache is " (:TERM "true") ", "
     (:GROUP (:FONT :FACE :I) "unique-id") " defaults to " (:GROUP (:FONT :FACE :I) "items")
     ", but programmers will generally wish to specify a more efficient tag. " (:GROUP (:FONT :FACE :I) "id-test")
     " is a function of two arguments used to compare unique-ids, which defaults to " (:CL "equal") ". "
     (:GROUP (:FONT :FACE :I) "cache-value")
     " is the value that is used to indicate that a cached menu is still valid. It defaults to "
     (:GROUP (:FONT :FACE :I) "items") ", but programmers may wish to supply a more efficient cache value than that. "
     (:GROUP (:FONT :FACE :I) "cache-test")
     " is a function of two arguments that is used to compare cache values, which defaults to " (:CL "equal") ". Both "
     (:GROUP (:FONT :FACE :I) "cache-value") " and " (:GROUP (:FONT :FACE :I) "unique-id") " have dynamic extent."
     (:PAR) (:GROUP (:FONT :FACE :I) "max-width") " and " (:GROUP (:FONT :FACE :I) "max-height")
     " specify the maximum width and height of the menu, in device units. They can be overridden by "
     (:GROUP (:FONT :FACE :I) "n-rows") " and " (:GROUP (:FONT :FACE :I) "n-columns") "." (:PAR)
     (:GROUP (:FONT :FACE :I) "n-rows") " and " (:GROUP (:FONT :FACE :I) "n-columns")
     " specify the number of rows and columns in the menu." (:PAR) (:GROUP (:FONT :FACE :I) "x-spacing")
     " specifies the amount of space to be inserted between columns of the table; the default is the width of a space character. It is specified the same way as the "
     (:CL ":x-spacing") " option to " (:CL "formatting-table") "." (:PAR) (:GROUP (:FONT :FACE :I) "y-spacing")
     " specifies the amount of blank space inserted between rows of the table; the default is the vertical spacing for the stream. The possible values for this option are the same as for the "
     (:GROUP (:FONT :FACE :I) ":y-spacing") " option to " (:CL "formatting-table") "." (:PAR)
     (:GROUP (:FONT :FACE :I) "cell-align-x")
     " specifies the horizontal placement of the contents of the cell. Can be one of " (:CL ":left") ", "
     (:CL ":right") ", or " (:CL ":center") ". The default is " (:CL ":left")
     ". The semantics are the same as for the " (:CL ":align-x") " option to " (:CL "formatting-cell") "." (:PAR)
     (:GROUP (:FONT :FACE :I) "cell-align-y")
     " specifies the vertical placement of the contents of the cell. Can be one of " (:CL ":top") ", " (:CL ":bottom")
     ", or " (:CL ":center") ". The default is " (:CL ":top") ". The semantics are the same as for the "
     (:CL ":align-y") " option to " (:CL "formatting-cell") "." (:PAR) (:GROUP (:FONT :FACE :I) "row-wise")
     " is as for " (:CL "formatting-item-list") ". It defaults to " (:CL "t") "." (:PAR)
     (:GROUP (:FONT :FACE :I) "scroll-bars")
     " specifies whether the menu should have scroll bars. It acts the same way as the " (:CL ":scroll-bars")
     " option to " (:CL "make-clim-stream-pane") ". It defaults to " (:CL ":vertical") "." (:PAR)
     (:GROUP (:FONT :FACE :I) "pointer-documentation") " is either " (:CL "nil")
     " (the default), meaning that no pointer documentation should be computed, or a stream on which pointer documentation should be displayed."
     (:PAR) " ")
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "menu-choose-from-drawer")) :PARAMS
      ((:I "menu presentation-type drawer  " (:GROUP (:FONT :FACE :TT) "&key ")
        "x-position y-position  cache unique-id id-test cache-value cache-test  default-presentation pointer-documentation"))
      :KIND ("Generic Function"))
     (:PAR)
     "This is a a lower-level routine for displaying menus. It allows the programmer much more flexibility in the menu layout. Unlike "
     (:CL "menu-choose") ", which automatically creates and lays out the menu, " (:CL "menu-choose-from-drawer")
     " takes a programmer-provided window and drawing function. The drawing function is responsible for drawing the contents of the menu; generally it will be a lexical closure that closes over the menu items."
     (:PAR) (:CL "menu-choose-from-drawer")
     " draws the menu items into that window using the drawing function. The drawing function gets called with two arguments, "
     (:GROUP (:FONT :FACE :I) "stream") " and " (:GROUP (:FONT :FACE :I) "presentation-type") ". It can use "
     (:GROUP (:FONT :FACE :I) "presentation-type")
     " for its own purposes, such as using it as the presentation type argument in a call to " (:CL "present") "."
     (:PAR) (:CL "menu-choose-from-drawer")
     " returns two values: the object the user clicked on, and the pointer button event. If the user aborts out of the menu, a single value is returned, "
     (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :I) "menu")
     " is a CLIM window to use for the menu. This argument may be specialized to provide a different look-and-feel for different host window systems."
     (:PAR) (:GROUP (:FONT :FACE :I) "presentation-type")
     " is a presentation type specifier for each of the mouse-sensitive items in the menu. This is the input context that will be established once the menu is displayed. For programmers who don't need to define their own types, a useful presentation type is "
     (:CL "menu-item") "." (:PAR) (:GROUP (:FONT :FACE :I) "drawer") " is a function that takes two arguments, "
     (:GROUP (:FONT :FACE :I) "stream") " and " (:GROUP (:FONT :FACE :I) "presentation-type")
     ", draws the contents of the menu. It has dynamic extent." (:PAR) (:GROUP (:FONT :FACE :I) "x-position") " and "
     (:GROUP (:FONT :FACE :I) "y-position") " are the requested " (:MATH "x") " and " (:MATH "y")
     " positions of the menu. They may be " (:CL "nil") ", meaning that the position is unspecified." (:PAR) "If "
     (:GROUP (:FONT :FACE :I) "leave-menu-visible") " is " (:TERM "true")
     ", the window will not be deexposed once the selection has been made. The default is " (:TERM "false")
     ", meaning that the window will be deexposed once the selection has been made." (:PAR)
     (:GROUP (:FONT :FACE :I) "default-presentation")
     " is used to identify the presentation that the mouse is pointing to when the menu comes up." (:PAR)
     (:GROUP (:FONT :FACE :I) "cache") ", " (:GROUP (:FONT :FACE :I) "unique-id") ", "
     (:GROUP (:FONT :FACE :I) "id-test") ", " (:GROUP (:FONT :FACE :I) "cache-value") ", and "
     (:GROUP (:FONT :FACE :I) "cache-test") " are as for " (:CL "menu-choose") "." (:PAR))
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "draw-standard-menu")) :PARAMS
      ((:I "stream presentation-type items default-item  " (:GROUP (:FONT :FACE :TT) "&key ")
        "item-printer  max-width max-height n-rows n-columns  x-spacing y-spacing row-wise  cell-align-x cell-align-y"))
      :KIND ("Function"))
     (:PAR) (:CL "draw-standard-menu")
     " is the function used by CLIM to draw the contents of a menu, unless the current frame manager determines that host window toolkit should be used to draw the menu instead. "
     (:GROUP (:FONT :FACE :I) "stream") " is the stream onto which to draw the menu, "
     (:GROUP (:FONT :FACE :I) "presentation-type") " is the presentation type to use for the menu items (usually "
     (:CL "menu-item") "), and " (:GROUP (:FONT :FACE :I) "item-printer") " is a function used to draw each item. "
     (:GROUP (:FONT :FACE :I) "item-printer") " defaults to " (:CL "print-menu-item") "." (:PAR)
     (:GROUP (:FONT :FACE :I) "items") ", " (:GROUP (:FONT :FACE :I) "default-item") ", "
     (:GROUP (:FONT :FACE :I) "max-width") ", " (:GROUP (:FONT :FACE :I) "max-height") ", "
     (:GROUP (:FONT :FACE :I) "n-rows") ", " (:GROUP (:FONT :FACE :I) "n-columns") ", "
     (:GROUP (:FONT :FACE :I) "x-spacing") ", " (:GROUP (:FONT :FACE :I) "y-spacing") ", "
     (:GROUP (:FONT :FACE :I) "row-wise") ", " (:GROUP (:FONT :FACE :I) "cell-align-x") ", and "
     (:GROUP (:FONT :FACE :I) "cell-align-y") " are as for " (:CL "menu-choose") (:PAR))
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "print-menu-item")) :PARAMS
      ((:I "menu-item " (:GROUP (:FONT :FACE :TT) "&optional ") "(stream " (:CL "*standard-output*") ")")) :KIND
      ("Function"))
     (:PAR) "Given a menu item " (:GROUP (:FONT :FACE :I) "menu-item") ", displays it on the stream "
     (:GROUP (:FONT :FACE :I) "stream") ". This is the function that " (:CL "menu-choose")
     " uses to display menu items if no printer is supplied." (:PAR) " ")
    (:DEFUN (:SIGNATURE :NAME ((:CL "menu-item-value")) :PARAMS ((:I "menu-item")) :KIND ("Function")) (:PAR)
     "Returns the value of the menu item " (:GROUP (:FONT :FACE :I) "menu-item")
     ", where the format of a menu item is described under " (:CL "menu-choose") ". If "
     (:GROUP (:FONT :FACE :I) "menu-item") " is not a menu item, the result is unspecified." (:PAR))
    (:DEFUN (:SIGNATURE :NAME ((:CL "menu-item-display")) :PARAMS ((:I "menu-item")) :KIND ("Function")) (:PAR)
     "Returns the display object of the menu item " (:GROUP (:FONT :FACE :I) "menu-item")
     ", where the format of a menu item is described under " (:CL "menu-choose") ". If "
     (:GROUP (:FONT :FACE :I) "menu-item") " is not a menu item, the result is unspecified." (:PAR))
    (:DEFUN (:SIGNATURE :NAME ((:CL "menu-item-options")) :PARAMS ((:I "menu-item")) :KIND ("Function")) (:PAR)
     "Returns the options of the menu item " (:GROUP (:FONT :FACE :I) "menu-item")
     ", where the format of a menu item is described under " (:CL "menu-choose") ". If "
     (:GROUP (:FONT :FACE :I) "menu-item") " is not a menu item, the result is unspecified." (:PAR) " ")
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "with-menu")) :PARAMS
      ((:I "(menu " (:GROUP (:FONT :FACE :TT) "&optional ") "associated-window " (:GROUP (:FONT :FACE :TT) "&key ")
        "(deexpose t))  " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
      :KIND ("Macro"))
     (:PAR) "Binds " (:GROUP (:FONT :FACE :I) "menu")
     " to a \"temporary\" window, exposes the window on the same screen as the "
     (:GROUP (:FONT :FACE :I) "associated-window")
     " and runs the body. After the body has been run, the window is deexposed only if the boolean "
     (:GROUP (:FONT :FACE :I) "deexpose") " is " (:TERM "true") " (the default)." (:PAR) "The values returned by "
     (:CL "with-menu") " are the values returned by " (:GROUP (:FONT :FACE :I) "body") ". "
     (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
     (:GROUP (:FONT :FACE :I) "menu") " must be a variable name. " (:GROUP (:FONT :FACE :I) "associated-window")
     " is as for " (:CL "menu-choose") "." (:PAR) "None of the arguments is evaluated." (:PAR)))
   " "
   (:SECTION :TITLE ("26 " "Dialog Facilities") :KIND :CHAPTER :NAME (5 10) " " (:LABEL :NAME "dialogs") (:PAR)
    (:GROUP (:FONT :FACE :B) "Major issue: ") " "
    (:GROUP (:FONT :FACE :SL)
     "There is a general issue about how these dialogs fit in with the dialogs that might be provided by the underlying toolkit. For example, under what circumstances is CLIM allowed to directly use the dialog facility provided by the host? --- SWM")
    (:PAR) " "
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "accepting-values")) :PARAMS
      ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ")
        "own-window exit-boxes  initially-select-query-identifier modify-initial-query  resynchronize-every-pass resize-frame  align-prompts label scroll-bars  x-position y-position width height  command-table frame-class)  "
        (:GROUP (:FONT :FACE :TT) "&body ") "body"))
      :KIND ("Macro"))
     (:PAR) "Builds a dialog for user interaction based on calls to " (:CL "accept") " within "
     (:GROUP (:FONT :FACE :I) "body")
     ". The user can select the values and change them, or use defaults if they are supplied. The dialog will also contain some sort of \"end\" and \"abort\" choices. If \"end\" is selected, then "
     (:CL "accepting-values") " returns whatever values the body returns. If \"abort\" is selected, "
     (:CL "accepting-values") " will invoke the " (:CL "abort") " restart." (:PAR) (:GROUP (:FONT :FACE :I) "stream")
     " is an interactive stream that " (:CL "accepting-values") " will use to build up the dialog. The "
     (:GROUP (:FONT :FACE :I) "stream")
     " argument is not evaluated, and must be a symbol that is bound to a stream. If "
     (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-input*") " is used." (:PAR)
     (:GROUP (:FONT :FACE :I) "body") " is the body of the dialog, which contains calls to " (:CL "accept")
     " that will be intercepted by " (:CL "accepting-values") " and used to build up the dialog. "
     (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) "An "
     (:CL "accepting-values") " dialog is implemented as an application frame with a looping structure. First, "
     (:GROUP (:FONT :FACE :I) "body")
     " is evaluated in order to collect the output. While the body is being evaluated, all calls to " (:CL "accept")
     " call the " (:CL "accept-present-default") " presentation methods instead of calling the " (:CL "accept")
     " presentation methods. The output is then displayed, preferably using incremental redisplay in order to avoid unnecessary redisplay of unchanged output. If "
     (:GROUP (:FONT :FACE :I) "align-prompts") " is " (:TERM "true") " (the default is " (:CL "nil")
     "), then the fields of the dialog will be displayed within a call to " (:CL "formatting-table")
     " so that the prompts are aligned vertically on their right-hand sides and the input fields are aligned on their left-hand sides. This option is intended to support toolkits where users expect dialogs to have this sort of layout."
     (:PAR) "After " (:CL "accepting-values")
     " has displayed all of the fields, it awaits a user gesture, such as clicking on one of the fields of the dialog. When the user clicks on a field, "
     (:CL "accepting-values") " reads a new value for that field using " (:CL "accept")
     " and replaces the old value with the new value. Then the loop is started again, until the user either exits or aborts from the dialog."
     (:PAR) "Because of its looping structure, " (:CL "accepting-values")
     " needs to be able to uniquely identify each call to " (:CL "accept") " in the body of the dialog. The "
     (:CONCEPT "query identifier") " is used to identify the calls to " (:CL "accept")
     ". The query identifier for a call to " (:CL "accept")
     " is computed on each loop through the dialog, and should therefore be free of side-effects. Query identifiers are compared using "
     (:CL "equal") ". Inside of " (:CL "accepting-values") ", programmers should supply the " (:CL ":query-identifier")
     " argument to each call to " (:CL "accept") ". If " (:CL ":query-identifier")
     " is not explicitly supplied, the prompt for that call to " (:CL "accept")
     " is used as the query identifier. Thus, if " (:CL ":query-identifier")
     " is not supplied, programmers must ensure that all of the prompts are different. If there is more than one call to "
     (:CL "accept") " with the same query identifier, the behavior of " (:CL "accepting-values") " is unspecified."
     (:PAR) "While inside " (:CL "accepting-values") ", calls to " (:CL "accept")
     " return a third value, a boolean (\"changed-p\") that indicates whether the object is the result of new input by the user, or is just the previously supplied default. The third value will be "
     (:TERM "true") " in the former case, " (:TERM "false") " in the latter." (:PAR)
     (:GROUP (:FONT :FACE :B) "Implementation note:") " each invocation of " (:CL "accepting-values")
     " will probably need to maintain a table that maps from a query identifier to the output record for the field that used the query identifier, and the output record for each field in the dialog will probably need a mapping back to the query identifier. A mediating object (a \"query object\") is also useful, for instance, as a place to store the \"changed-p\" flag."
     (:PAR) "The class of the application frame created by " (:CL "accepting-values") " will be " (:CL "accept-values")
     " or a subclass of " (:CL "accept-values")
     ". Programmers can use a class of their own by supplying the name of a class via the "
     (:GROUP (:FONT :FACE :I) "frame-class") " argument. CLIM will use the command table " (:CL "accept-values")
     " as the command table for " (:CL "accepting-values")
     ". Programmers can supply a command table of their own by supplying the "
     (:GROUP (:FONT :FACE :I) "command-table") " argument." (:PAR) "When " (:GROUP (:FONT :FACE :I) "own-window")
     " is non-" (:CL "nil")
     ", the dialog will appear in its own \"popped-up\" window. In this case the initial value of "
     (:GROUP (:FONT :FACE :I) "stream") " is a window with which the dialog is associated. (This is similar to the "
     (:GROUP (:FONT :FACE :I) "associated-window") " argument to " (:CL "menu-choose") ".) Within the "
     (:GROUP (:FONT :FACE :I) "body") ", the value of " (:GROUP (:FONT :FACE :I) "stream")
     " will be the \"popped-up\" window. " (:GROUP (:FONT :FACE :I) "own-window") " is either " (:CL "t")
     " or a list of alternating keyword options and values. The accepted options are " (:CL ":right-margin") " and "
     (:CL ":bottom-margin")
     "; their values control the amount of extra space to the right of and below the dialog (useful if the user's responses to the dialog take up more space than the initially displayed defaults). The allowed values for "
     (:CL ":right-margin") " are the same as for the " (:CL ":x-spacing") " option to " (:CL "formatting-table")
     "; the allowed values for " (:CL ":bottom-margin") " are the same as for the " (:CL ":y-spacing") " option."
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL) "When the programmer supplies " (:CL ":right-margin") " or " (:CL ":bottom-margin")
      " options in the own-window argument, how is he supposed to determine what's needed? How about providing an option to permit the window to resize itself dynamically? There really needs to be a hook into "
      (:CL "note-space-requirements-changed") " or something. --- barmar, SWM")
     (:PAR) (:GROUP (:FONT :FACE :I) "exit-boxes")
     " specifies what the exit boxes should look like. The default behavior is though the following were supplied:"
     (:PAR)
     (:PRE "
'((:exit \"<End> uses these values\")
  (:abort \"<Abort> aborts\"))
")
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL) "We need to describe the interpretation of the " (:GROUP (:FONT :FACE :I) "exit-boxes")
      " argument. Are other keywords beside " (:CL ":exit") " and " (:CL ":abort") " permitted, such as " (:CL ":help")
      "? It's pretty common for a dialog to have multiple ways to exit; perhaps " (:CL "accepting-values")
      " should return a second value that indicates which exit box was selected. This alist looks sort of like a menu item list; perhaps the full generality should be permitted (so that the style of the exit box messages can be specified). The text strings that are shown in the default value look more like documentation than button labels; I think both are necessary, and the programmer must be able to find out what the default labels are so that he can include them in the documentation (rather than hard-coding \"<End>\" and \"<Abort>\"). --- barmar")
     (:PAR) (:GROUP (:FONT :FACE :I) "initially-select-query-identifier")
     " specifies that a particular field in the dialog should be pre-selected when the user interaction begins. The field to be selected is tagged by the "
     (:CL ":query-identifier") " option to " (:CL "accept")
     ". When the initial display is output, the input editor cursor appears after the prompt of the tagged field, just as if the user had selected that field by clicking on it. The default value, if any, for the selected field is not displayed. When "
     (:GROUP (:FONT :FACE :I) "modify-initial-query") " is " (:TERM "true")
     ", the initially selected field is selected for modification rather than for replacement; the default is "
     (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :I) "resynchronize-every-pass")
     " is a boolean option specifying whether earlier queries depend on later values; the default is " (:TERM "false")
     ". When it is " (:TERM "true")
     ", the contents of the dialog are redisplayed an additional time after each user interaction. This has the effect of ensuring that, when the value of some field of a dialog depends on the value of another field, all of the displayed fields will be up to date."
     (:PAR) "When " (:GROUP (:FONT :FACE :I) "resize-frame") " is " (:TERM "true")
     ", own-window dialogs will be resized after each pass through the redisplay loop. The default is " (:CL "nil") "."
     (:PAR) (:GROUP (:FONT :FACE :I) "label") " is as for " (:CL "menu-choose") ". "
     (:GROUP (:FONT :FACE :I) "x-position") " and " (:GROUP (:FONT :FACE :I) "y-position") " are as for "
     (:CL "menu-choose-from-drawer") ". " (:GROUP (:FONT :FACE :I) "width") " and " (:GROUP (:FONT :FACE :I) "height")
     " are real numbers that specify the initial width and height of own-window dialogs." (:PAR) " ")
    (:DEFUN (:SIGNATURE :NAME ((:CL "accept-values")) :PARAMS ((:I)) :KIND ("Application Frame")) (:PAR)
     (:CL "accepting-values") " must be implemented as a CLIM application frame that uses " (:CL "accept-values")
     " as the name of the frame class." (:PAR) " ")
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "display-exit-boxes")) :PARAMS ((:I "frame stream view")) :KIND ("Generic Function"))
     (:PAR) "Displays the exits boxes for the " (:CL "accepting-values") " frame " (:GROUP (:FONT :FACE :I) "frame")
     " on the stream " (:GROUP (:FONT :FACE :I) "strea,") " in the view " (:GROUP (:FONT :FACE :I) "view")
     ". The exit boxes specification is not passed in directly, but is a slot in the frame. The default method (on "
     (:CL "accept-values")
     ") simply writes a line of text associating the Exit and Abort strings with presentations that either exit or abort from the dialog."
     (:PAR) "The " (:GROUP (:FONT :FACE :I) "frame") ", " (:GROUP (:FONT :FACE :I) "stream") ", and "
     (:GROUP (:FONT :FACE :I) "view")
     " arguments may be specialized to provide a different look-and-feel for different host window systems." (:PAR))
    (:DEFUN (:SIGNATURE :NAME ((:CL "accept-values-resynchronize")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
     (:PAR) "Causes " (:CL "accepting-values") " to resynchronizes the dialog once on the accepting values stream "
     (:GROUP (:FONT :FACE :I) "stream") " before it restarts the dialog loop." (:PAR) " ")
    (:DEFUN
     (:SIGNATURE :NAME ((:CL "accept-values-command-button")) :PARAMS
      ((:I "(" (:GROUP (:FONT :FACE :TT) "&optional ") "stream  " (:GROUP (:FONT :FACE :TT) "&key ")
        "documentation query-identifier  cache-value cache-test resynchronize)  prompt  "
        (:GROUP (:FONT :FACE :TT) "&body ") "body"))
      :KIND ("Macro"))
     (:PAR) "Displays the prompt " (:GROUP (:FONT :FACE :I) "prompt") " on the stream "
     (:GROUP (:FONT :FACE :I) "stream")
     " and creates an area (the \"button\"). When a pointer button is clicked in this area at runtime, "
     (:GROUP (:FONT :FACE :I) "body") " will be evaluated." (:PAR) (:CL "accept-values-command-button")
     " must be implemented by expanding into a call to " (:CL "invoke-accept-values-command-button")
     ", supplying a function that executes " (:GROUP (:FONT :FACE :I) "body") " as the "
     (:GROUP (:FONT :FACE :I) "continuation") " argument to " (:CL "accept-values-command-button") "." (:PAR) "The "
     (:GROUP (:FONT :FACE :I) "stream")
     " argument is not evaluated, and must be a symbol that is bound to a stream. If "
     (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") " (the default), " (:CL "*standard-input*") " is used. "
     (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
    (:DEFUN (:SIGNATURE :NAME ((:CL "invoke-accept-values-command-button")) :PARAMS ((:I)) :KIND ("Method"))
     (:GROUP "stream continuation view prompt  " (:GROUP (:FONT :FACE :TT) "&key ")
      "documentation query-identifier cache-value cache-test resynchronize")
     (:PAR) "Displays the prompt " (:GROUP (:FONT :FACE :I) "prompt") " on the stream "
     (:GROUP (:FONT :FACE :I) "stream")
     " and creates an area (the \"button\"). When a pointer button is clicked in this area at runtime, the continuation will be called. "
     (:GROUP (:FONT :FACE :I) "continuation") " is a function that takes no arguments. "
     (:GROUP (:FONT :FACE :I) "view") " is a view." (:PAR) (:GROUP (:FONT :FACE :I) "prompt")
     " may be either a string (which will be displayed via " (:CL "write-string")
     "), or a form that will be evaluated to draw the button." (:PAR) (:GROUP (:FONT :FACE :I) "documentation")
     " is an object that will be used to produce pointer documentation for the button. It defaults to "
     (:GROUP (:FONT :FACE :I) "prompt")
     ". If it is a string, the string itself will be used as the pointer documentation. Otherwise it must be a function of one argument, the stream to which the documentation should be written."
     (:PAR) "When " (:GROUP (:FONT :FACE :I) "resynchronize") " is " (:TERM "true")
     ", the dialog will be redisplayed an additional time whenever the command button is clicked on. See the "
     (:GROUP (:FONT :FACE :I) "resynchronize-every-pass") " argument to " (:CL "accepting-values") "." (:PAR)
     (:GROUP (:FONT :FACE :I) "cache-value") " and " (:GROUP (:FONT :FACE :I) "cache-test") " are as for "
     (:CL "updating-output") ". That is, " (:GROUP (:FONT :FACE :I) "cache-value")
     " should evaluate to the same value if and only if the output produced by " (:GROUP (:FONT :FACE :I) "prompt")
     " does not ever change. " (:GROUP (:FONT :FACE :I) "cache-test")
     " is a function of two arguments that is used to compare cache values. " (:GROUP (:FONT :FACE :I) "cache-value")
     " defaults to " (:CL "t") " and " (:GROUP (:FONT :FACE :I) "cache-test") " defaults to " (:CL "eql") "." (:PAR)
     "This function may only be used inside the dynamic context of an " (:CL "accepting-values") "." (:PAR)))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part VII: " "Building Applications") :NAME (10) " " " "
   (:SECTION :TITLE ("27 " "Command Processing") :KIND :CHAPTER :NAME (4 10) " " (:LABEL :NAME "command-processor")
    (:PAR)
    (:SECTION :TITLE ("27.1 " "Commands") :KIND :SECTION :NAME (6 4 10) (:PAR) "A " (:CONCEPT "command")
     " is an object that represents a user interaction. Commands are stored as a cons of the command name and a list of the command's arguments. All positional arguments will be represented in the command object, but only those keywords arguments that were explicitly supplied by the user will be included. When the first element of the cons is "
     (:CL "apply") "'ed to the rest of the cons, the code representing that interaction is executed." (:PAR) "A "
     (:CONCEPT "partial command") " is a command object with the value of " (:CL "*unsupplied-argument-marker*")
     " in place of any argument that needs to be filled in." (:PAR) "Every command is named by "
     (:CONCEPT "command name")
     ", which is a symbol. To avoid collisions among command names, application frames should reside in their own package; for example, the "
     (:CL "com-show-chart") " command might be defined for both a spreadsheet and a medical application." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-name")) :PARAMS ((:I "command")) :KIND ("Function")) (:PAR)
      "Given a command object " (:GROUP (:FONT :FACE :I) "command") ", returns the command name." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-arguments")) :PARAMS ((:I "command")) :KIND ("Function")) (:PAR)
      "Given a command object " (:GROUP (:FONT :FACE :I) "command") ", returns the command's arguments." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "partial-command-p")) :PARAMS ((:I "command")) :KIND ("Function")) (:PAR)
      "Returns " (:TERM "true") " if the " (:GROUP (:FONT :FACE :I) "command")
      " is a partial command, that is, has any occurrences of " (:CL "*unsupplied-argument-marker*")
      " in it. Otherwise, " (:CL "partial-command-p") " returns " (:TERM "false") "." (:PAR) " " (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "define-command")) :PARAMS
       ((:I "name-and-options arguments " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:PAR) "This is the most basic command-defining form. Usually, the programmer will not use "
      (:CL "define-command") " directly, but will instead use a "
      (:CL "define-" (:GROUP (:FONT :FACE :I) "frame") "-command") "  form that is automatically generated by "
      (:CL "define-application-frame") ". " (:CL "define-" (:GROUP (:FONT :FACE :I) "frame") "-command")
      "  adds the command to the application frame's command table. By default, " (:CL "define-command")
      " does not add the command to any command table." (:PAR) (:GROUP (:FONT :FACE :I) "name-and-options")
      " is either a command name, or a cons of the command name and a list of keyword-value pairs." (:PAR)
      (:CL "define-command")
      " defines two functions. The first function has the same name as the command name, and implements the body of the command. It takes as arguments the arguments to the command as specified by the "
      (:CL "define-command") " form, as required and keyword arguments." (:PAR)
      "The name of the other function defined by " (:CL "define-command")
      " is unspecified. It implements the code used by the command processor for parsing and returning the command's arguments."
      (:PAR) "The keywords from " (:GROUP (:FONT :FACE :I) "name-and-options") " can be:" (:PAR)
      (:UL
       (:LI (:CL ":command-table") " " (:GROUP (:FONT :FACE :I) "command-table-name") ", where "
        (:GROUP (:FONT :FACE :I) "command-table-name")
        " either names a command table to which the command will be added, or is " (:CL "nil")
        " (the default) to indicate that the command should not be added to any command table. If the command table does not exist, the "
        (:CL "command-table-not-found") " error will be signalled. This keyword is only accepted by "
        (:CL "define-command") ", not by " (:CL "define-" (:GROUP (:FONT :FACE :I) "frame") "-command") "." (:PAR))
       (:LI (:CL ":name") " " (:GROUP (:FONT :FACE :I) "string") ", where " (:GROUP (:FONT :FACE :I) "string")
        " is a string that will be used as the command-line name for the command for keyboard interactions in the command table specified by the "
        (:CL ":command-table") " option. The default is " (:CL "nil")
        ", meaning that the command will not be available via command-line interactions. If "
        (:GROUP (:FONT :FACE :I) "string") " is " (:CL "t")
        ", then the command-line name will be generated automatically, as described in "
        (:CL "add-command-to-command-table") "." (:PAR))
       (:LI (:CL ":menu") " " (:GROUP (:FONT :FACE :I) "menu-spec") ", where " (:GROUP (:FONT :FACE :I) "menu-spec")
        " describes an item in the menu of the command table specified by the " (:CL ":command-table")
        " option. The default is " (:CL "nil")
        ", meaning that the command will not be available via menu interactions. If "
        (:GROUP (:FONT :FACE :I) "menu-spec") " is a string, then that string will be used as the menu name. If "
        (:GROUP (:FONT :FACE :I) "menu-spec") " is " (:CL "t")
        ", then if a command-line name was supplied, it will be used as the menu name; otherwise the menu name will be generated automatically, as described in "
        (:CL "add-command-to-command-table") ". Otherwise, " (:GROUP (:FONT :FACE :I) "menu-spec")
        " must be a cons of the form "
        (:CL "(" (:GROUP (:FONT :FACE :I) "string") " . " (:GROUP (:FONT :FACE :I) "menu-options") ")") ", where "
        (:GROUP (:FONT :FACE :I) "string") " is the menu name and " (:GROUP (:FONT :FACE :I) "menu-options")
        " consists of keyword-value pairs. The valid keywords are " (:CL ":after") ", " (:CL ":documentation") ", and "
        (:CL ":text-style") ", which are interpreted as for " (:CL "add-menu-item-to-command-table") "." (:PAR))
       (:LI (:CL ":keystroke") " " (:GROUP (:FONT :FACE :I) "gesture") ", where " (:GROUP (:FONT :FACE :I) "gesture")
        " is a keyboard gesture name that specifies a keystroke accelerator to use for this command in the command table specified by the "
        (:CL ":command-table") " option. The default is " (:CL "nil")
        ", meaning that there is no keystroke accelerator. "))
      (:PAR) "The " (:CL ":name") ", " (:CL ":menu") ", and " (:CL ":keystroke") " options are only allowed if the "
      (:CL ":command-table") " option was supplied explicitly or implicitly, as in "
      (:CL "define-" (:GROUP (:FONT :FACE :I) "frame") "-command") "." (:PAR) (:GROUP (:FONT :FACE :I) "arguments")
      " is a list consisting of argument descriptions. A single occurrence of the symbol "
      (:CL (:GROUP (:FONT :FACE :TT) "&key ")) " may appear in " (:GROUP (:FONT :FACE :I) "arguments")
      " to separate required command arguments from keyword arguments. Each argument description consists of a parameter variable, followed by a presentation type specifier, followed by keyword-value pairs. The keywords can be:"
      (:PAR)
      (:UL
       (:LI (:CL ":default") " " (:GROUP (:FONT :FACE :I) "value") ", where " (:GROUP (:FONT :FACE :I) "value")
        " is the default that should be used for the argument, as for " (:CL "accept") "." (:PAR))
       (:LI (:CL ":default-type") " is the same as for " (:CL "accept") "." (:PAR))
       (:LI (:CL ":display-default") " is the same as for " (:CL "accept") "." (:PAR))
       (:LI (:CL ":mentioned-default") " " (:GROUP (:FONT :FACE :I) "value") ", where "
        (:GROUP (:FONT :FACE :I) "value")
        " is the default that should be used for the argument when a keyword is explicitly supplied via the command-line processor, but no value is supplied for it. "
        (:CL ":mentioned-default") " is only allowed on keyword arguments." (:PAR))
       (:LI (:CL ":prompt") " " (:GROUP (:FONT :FACE :I) "string") ", where " (:GROUP (:FONT :FACE :I) "string")
        " is a prompt to print out during command-line parsing, as for " (:CL "accept") "." (:PAR))
       (:LI (:CL ":documentation") " " (:GROUP (:FONT :FACE :I) "string") ", where " (:GROUP (:FONT :FACE :I) "string")
        " is a documentation string that describes what the argument is." (:PAR))
       (:LI (:CL ":when") " " (:GROUP (:FONT :FACE :I) "form") ". " (:GROUP (:FONT :FACE :I) "form")
        " is evaluated in a scope where the parameter variables for the required parameters are bound, and if the result is "
        (:CL "nil") ", the keyword argument is not available. " (:CL ":when")
        " is only allowed on keyword arguments, and " (:GROUP (:FONT :FACE :I) "form")
        " cannot use the values of other keyword arguments." (:PAR))
       (:LI (:CL ":gesture") " " (:GROUP (:FONT :FACE :I) "gesture") ", where " (:GROUP (:FONT :FACE :I) "gesture")
        " is either a pointer gesture name or a list of a pointer gesture name followed by keyword-value pairs. When a gesture is supplied, a presentation translator will be defined that translates from this argument's presentation type to an instance of this command with the selected object as the argument; the other arguments will be filled in with their default values. The keyword-value pairs are used as options for the translator. Valid keywords are "
        (:CL ":tester") ", " (:CL ":menu") ", " (:CL ":priority") ", " (:CL ":echo") ", " (:CL ":documentation")
        ", and " (:CL ":pointer-documentation") ". The default for " (:GROUP (:FONT :FACE :I) "gesture") " is "
        (:CL "nil") ", meaning no translator will be written. " (:CL ":gesture") " is only allowed when the "
        (:CL ":command-table") " option was supplied to the command-defining form. "))
      (:PAR) (:GROUP (:FONT :FACE :I) "body")
      " implements the body of the command. It has lexical access to all of the commands arguments. If the body of the command needs access to the application frame itself, it should use "
      (:CL "*application-frame*") ". The returned values of body are ignored. " (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms." (:PAR) (:CL "define-command")
      " must arrange for the function that implements the body of the command to get the proper values for unsupplied keyword arguments."
      (:PAR) (:GROUP (:FONT :FACE :I) "name-and-options") " and " (:GROUP (:FONT :FACE :I) "body")
      " are not evaluated. In the argument descriptions, the parameter variable name is not evaluated, and everything else is evaluated at run-time when argument parsing reaches that argument, except that the value for "
      (:CL ":when") " is evaluated when parsing reaches the keyword arguments, and " (:CL ":gesture")
      " isn't evaluated at all." (:PAR) " "))
    (:SECTION :TITLE ("27.2 " "Command Tables") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "There are four main styles of interaction: keyboard interaction using a command- line processor, keyboard interaction using keystroke accelerators, mouse interaction via command menus, and mouse interaction via translators. A "
     (:CONCEPT "command table")
     " is an object that serves to mediate between an application frame, a set of commands, and the four interaction styles. Command tables contain the following information:"
     (:PAR)
     (:UL (:LI "The name of the command table, which is a symbol." (:PAR))
      (:LI "An ordered list of command tables to inherit from." (:PAR))
      (:LI "The set of commands that are present in this command table." (:PAR))
      (:LI
       "A table that associates command-line names to command names (used to support command-line processor interactions)."
       (:PAR))
      (:LI "A set of presentation translators, defined via " (:CL "define-presentation-translator") " and "
       (:CL "define-presentation-to-command-translator") "." (:PAR))
      (:LI
       "A table that associates keyboard gesture names to menu items (used to support keystroke accelerator interactions). The keystroke accelerator table does not contain any items inherited from superior command tables."
       (:PAR))
      (:LI
       "A menu that associates menu names to command menu items (used to support interaction via command menus). The command menu items can invoke commands or sub-menus. By default, the menu does not contain any command menu items inherited from superior command tables, although this can be overridden by the "
       (:CL ":inherit-menu") " option to " (:CL "define-command-table") ". "))
     (:PAR) "We say that a command is " (:CONCEPT "present")
     " in a command table when it has been added to that command table. We say that a command is "
     (:CONCEPT "accessible")
     " in a command table when it is present in that command table or is present in any of the command tables from which that command table inherits."
     (:PAR) " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-table")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to command tables. If you want to create a new class that behaves like a command table, it should be a subclass of "
      (:CL "command-table") ". All instantiable subclasses of " (:CL "command-table")
      " must obey the command table protocol. Members of this class are mutable. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-table-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "command table")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-command-table")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class that implements command tables, a subclass of " (:CL "command-table") ". "
      (:CL "make-command-table") " returns objects that are members of this class." (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "Do we really want to advertise these classes, since all the functions below are vanilla functions instead of generic functions? Or should we make those functions be generic functions? --- SWM")
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-table-name")) :PARAMS ((:I "command-table")) :KIND ("Generic Function"))
      (:PAR) "Returns the name of the " (:TERM "command table") " " (:GROUP (:FONT :FACE :I) "command-table") "."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-table-inherit-from")) :PARAMS ((:I "command-table")) :KIND ("Generic Function"))
      (:PAR) "Returns a list of the command tables from which the " (:TERM "command table") " "
      (:GROUP (:FONT :FACE :I) "command-table")
      " inherits. This function returns objects that reveal CLIM's internal state; do not modify those objects. "
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "define-command-table")) :PARAMS
       ((:I "name " (:GROUP (:FONT :FACE :TT) "&key ") "inherit-from menu inherit-menu")) :KIND ("Macro"))
      (:PAR) "Defines a command table whose name is the symbol " (:GROUP (:FONT :FACE :I) "name")
      ". The new command table inherits from all of the command tables specified by "
      (:GROUP (:FONT :FACE :I) "inherit-from") ", which is a list of " (:CONCEPT "command table designators")
      " (that is, either a command table or a symbol that names a command table). The inheritance is done by union with shadowing. If no inheritance is specified, the command table will be made to inherit from CLIM's global command table. (This command table contains such things as the \"menu\" translator that is associated with the right-hand button on pointers.)"
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "inherit-menu") " is " (:TERM "true")
      ", the new command table will inherit the menu items and keystroke accelerators from all of the inherited command tables. If it is "
      (:TERM "false") " (the default), no menu items or keystroke accelerators will be inherited." (:PAR)
      (:GROUP (:FONT :FACE :I) "menu") " can be used to specify a menu for the command table. The value of "
      (:GROUP (:FONT :FACE :I) "menu") " is a list of clauses. Each clause is a list with the syntax "
      (:CL "("
           (:GROUP (:FONT :FACE :I) "string")
           " "
           (:GROUP (:FONT :FACE :I) "type")
           " "
           (:GROUP (:FONT :FACE :I) "value")
           " "
           (:GROUP (:FONT :FACE :TT) "&key ")
           (:GROUP (:FONT :FACE :I) "keystroke")
           " "
           (:GROUP (:FONT :FACE :I) "documentation")
           " "
           (:GROUP (:FONT :FACE :I) "text-style")
           ")")
      ", where " (:GROUP (:FONT :FACE :I) "string") ", " (:GROUP (:FONT :FACE :I) "type") ", "
      (:GROUP (:FONT :FACE :I) "value") ", " (:GROUP (:FONT :FACE :I) "keystroke") ", "
      (:GROUP (:FONT :FACE :I) "documentation") ", and " (:GROUP (:FONT :FACE :I) "text-style") " are as for "
      (:CL "add-menu-item-to-command-table") "." (:PAR) "If the command table named by "
      (:GROUP (:FONT :FACE :I) "name") " already exists, " (:CL "define-command-table")
      " will modify the existing command table to have the new value for " (:GROUP (:FONT :FACE :I) "inherit-from")
      " and " (:GROUP (:FONT :FACE :I) "menu")
      ", and leaves the other attributes for the existing command table alone." (:PAR) "None of "
      (:CL "define-command-table") "'s arguments are evaluated." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-command-table")) :PARAMS
       ((:I "name " (:GROUP (:FONT :FACE :TT) "&key ") "inherit-from menu inherit-menu (errorp t)")) :KIND
       ("Function"))
      (:PAR) "Creates a command table named " (:GROUP (:FONT :FACE :I) "name") ". "
      (:GROUP (:FONT :FACE :I) "inherit-from") ", " (:GROUP (:FONT :FACE :I) "menu") ", and "
      (:GROUP (:FONT :FACE :I) "inherit-menu") " are the same as for " (:CL "define-command-table") ". "
      (:CL "make-command-table")
      " does not implicitly include CLIM's global command table in the inheritance list for the new command table. If the command table already exists and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", the " (:CL "command-table-already-exists")
      " error will be signalled. If the command table already exists and " (:GROUP (:FONT :FACE :I) "errorp") " is "
      (:TERM "false") ", then the old command table will be discarded. The returned value is the command table." (:PAR)
      " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-command-table")) :PARAMS
       ((:I "name " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Returns the command table named by " (:GROUP (:FONT :FACE :I) "name") ". If "
      (:GROUP (:FONT :FACE :I) "name")
      " is itself a command table, it is returned. If the command table is not found and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", the " (:CL "command-table-not-found")
      " error will be signalled." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-table-error")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The class that is the superclass of the following four conditions. This class is a subclass of " (:CL "error")
      "." (:PAR) (:CL "command-table-error") " and its subclasses must handle the " (:CL ":format-string") " and "
      (:CL ":format-arguments") " initargs, which are used to specify a control string and arguments for a call to "
      (:CL "format") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-table-not-found")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The error that is signalled by such functions as " (:CL "find-command-table")
      " when a command table is not found." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-table-already-exists")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The error that is signalled when the programmer tries to create a command table that already exists." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-not-present")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The error that is signalled when a command is not present in a command table." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-not-accessible")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The error that is signalled when a command is not accessible in a command table." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-already-present")) :PARAMS ((:I)) :KIND ("Error Condition")) (:PAR)
      "The error that is signalled when a function tries to add a command to a command table when it is already present in the command table."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "add-command-to-command-table")) :PARAMS
       ((:I "command-name command-table  " (:GROUP (:FONT :FACE :TT) "&key ") "name menu keystroke (errorp t)")) :KIND
       ("Function"))
      (:PAR) "Adds the command named by " (:GROUP (:FONT :FACE :I) "command-name")
      " to the command table specified by the " (:TERM "command table designator") " "
      (:GROUP (:FONT :FACE :I) "command-table") "." (:PAR) (:GROUP (:FONT :FACE :I) "name")
      " is the command-line name for the command, and can be " (:CL "nil") ", " (:CL "t") ", or a string. When it is "
      (:CL "nil")
      ", the command will not be available via command-line interactions. When it is a string, that string is the command-line name for the command. When it is "
      (:CL "t") ", the command-line name is generated automatically by calling " (:CL "command-name-from-symbol")
      " on " (:GROUP (:FONT :FACE :I) "command-name")
      ". For the purposes of command-line name lookup, the character case of " (:GROUP (:FONT :FACE :I) "name")
      " is ignored." (:PAR) (:GROUP (:FONT :FACE :I) "menu") " is a menu item for the command, and can be " (:CL "nil")
      ", " (:CL "t") ", a string, or a cons. When it is " (:CL "nil")
      ", the command will not be available via menus. When it is a string, the string will be used as the menu name. When "
      (:GROUP (:FONT :FACE :I) "menu") " is " (:CL "t") " and " (:GROUP (:FONT :FACE :I) "name") " is a string, then "
      (:GROUP (:FONT :FACE :I) "name") " will be used as the menu name. When " (:GROUP (:FONT :FACE :I) "menu") " is "
      (:CL "t") " and " (:GROUP (:FONT :FACE :I) "name")
      " is not a string, an automatically generated menu name will be used. When " (:GROUP (:FONT :FACE :I) "menu")
      " is a cons of the form "
      (:CL "(" (:GROUP (:FONT :FACE :I) "string") " . " (:GROUP (:FONT :FACE :I) "menu-options") ")") ", "
      (:GROUP (:FONT :FACE :I) "string") " is the menu name and " (:GROUP (:FONT :FACE :I) "menu-options")
      " consists of keyword-value pairs. The valid keywords are " (:CL ":after") ", " (:CL ":documentation") ", and "
      (:CL ":text-style") ", which are interpreted as for " (:CL "add-menu-item-to-command-table") "." (:PAR)
      "The value for " (:GROUP (:FONT :FACE :I) "keystroke") " is either keyboard gesture name or " (:CL "nil")
      ". When it is a gesture name, it is the keystroke accelerator for the command; otherwise the command will not be available via keystroke accelerators."
      (:PAR) "If the command is already present in the command table and " (:GROUP (:FONT :FACE :I) "errorp") " is "
      (:TERM "true") ", the " (:CL "command-already-present")
      " error will be signalled. When the command is already present in the command table and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "false")
      ", then the old command-line name, menu, and keystroke accelerator will first be removed from the command table."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "remove-command-from-command-table")) :PARAMS
       ((:I "command-name command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Removes the command named by " (:GROUP (:FONT :FACE :I) "command-name")
      " from the command table specified by the " (:TERM "command table designator") " "
      (:GROUP (:FONT :FACE :I) "command-table") "." (:PAR) "If the command is not present in the command table and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", the " (:CL "command-not-present")
      " error will be signalled." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-name-from-symbol")) :PARAMS ((:I "symbol")) :KIND ("Function")) (:PAR)
      "Generates a string suitable for use as a command-line name from the symbol " (:GROUP (:FONT :FACE :I) "symbol")
      ". The string consists the symbol name with the hyphens replaced by spaces, and the words capitalized. If the symbol name is prefixed by \"COM-\", the prefix is removed. For example, if the symbol is "
      (:CL "com-show-file") ", the result string will be \"Show File\"." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "do-command-table-inheritance")) :PARAMS
       ((:I "(command-table-var command-table) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:PAR) "Successively executes " (:GROUP (:FONT :FACE :I) "body") " with "
      (:GROUP (:FONT :FACE :I) "command-table-var") " bound first to the command table specified by the "
      (:TERM "command table designator") " " (:GROUP (:FONT :FACE :I) "command-table")
      ", and then (recursively) to all of the command tables from which " (:GROUP (:FONT :FACE :I) "command-table")
      " inherits." (:PAR) "The " (:GROUP (:FONT :FACE :I) "command-table-var") " argument is not evaluated. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "map-over-command-table-commands")) :PARAMS
       ((:I "function command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(inherited t)")) :KIND ("Function"))
      (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function")
      " to all of the commands accessible in the command table specified by the " (:TERM "command table designator")
      " " (:GROUP (:FONT :FACE :I) "command-table") ". " (:GROUP (:FONT :FACE :I) "function")
      " must be a function that takes a single argument, the command name; it has dynamic extent." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "inherited") " is " (:TERM "false") ", this applies "
      (:GROUP (:FONT :FACE :I) "function") " only to those commands present in "
      (:GROUP (:FONT :FACE :I) "command-table") ", that is, it does not map over any inherited command tables. If "
      (:GROUP (:FONT :FACE :I) "inherited") " is " (:TERM "true")
      ", then the inherited command tables are traversed in the same order as for "
      (:CL "do-command-table-inheritance") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "map-over-command-table-names")) :PARAMS
       ((:I "function command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(inherited t)")) :KIND ("Function"))
      (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function")
      " to all of the command-line name accessible in the command table specified by the "
      (:TERM "command table designator") " " (:GROUP (:FONT :FACE :I) "command-table") ". "
      (:GROUP (:FONT :FACE :I) "function")
      " must be a function of two arguments, the command-line name and the command name; it has dynamic extent." (:PAR)
      "If " (:GROUP (:FONT :FACE :I) "inherited") " is " (:TERM "false") ", this applies "
      (:GROUP (:FONT :FACE :I) "function") " only to those command-line names present in "
      (:GROUP (:FONT :FACE :I) "command-table") ", that is, it does not map over any inherited command tables. If "
      (:GROUP (:FONT :FACE :I) "inherited") " is " (:TERM "true")
      ", then the inherited command tables are traversed in the same order as for "
      (:CL "do-command-table-inheritance") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-present-in-command-table-p")) :PARAMS ((:I "command-name command-table")) :KIND
       ("Function"))
      (:PAR) "Returns " (:TERM "true") " if the command named by " (:GROUP (:FONT :FACE :I) "command-name")
      " is present in the command table specified by the " (:TERM "command table designator") " "
      (:GROUP (:FONT :FACE :I) "command-table") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-accessible-in-command-table-p")) :PARAMS ((:I "command-name command-table"))
       :KIND ("Function"))
      (:PAR) "If the command named by " (:GROUP (:FONT :FACE :I) "command-name")
      " is not accessible in the command table specified by the " (:TERM "command table designator") " "
      (:GROUP (:FONT :FACE :I) "command-table") ", then this function returns " (:CL "nil")
      ". Otherwise, it returns the command table in which the command was found." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-command-from-command-line-name")) :PARAMS
       ((:I "name command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Given a command-line name " (:GROUP (:FONT :FACE :I) "name")
      " and a command table, returns two values, the command name and the command table in which the command was found. If the command is not accessible in "
      (:GROUP (:FONT :FACE :I) "command-table") " and " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true")
      ", the " (:CL "command-not-accessible") " error will be signalled. " (:GROUP (:FONT :FACE :I) "command-table")
      " is a " (:TERM "command table designator") "." (:PAR) (:CL "find-command-from-command-line-name")
      " ignores character case." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-line-name-for-command")) :PARAMS
       ((:I "command-name command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Returns the command-line name for " (:GROUP (:FONT :FACE :I) "command-name") " as it is installed in "
      (:GROUP (:FONT :FACE :I) "command-table") ". " (:GROUP (:FONT :FACE :I) "command-table") " is a "
      (:TERM "command table designator") "." (:PAR) "If the command is not accessible in "
      (:GROUP (:FONT :FACE :I) "command-table")
      " or has no command-line name, then there are three possible results. If " (:GROUP (:FONT :FACE :I) "errorp")
      " is " (:CL "nil") ", then the returned value will be " (:CL "nil") ". If " (:GROUP (:FONT :FACE :I) "errorp")
      " is " (:CL ":create") ", then a command-line name will be generated, as described in "
      (:CL "add-command-to-command-table") ". Otherwise, if " (:GROUP (:FONT :FACE :I) "errorp") " is " (:CL "t")
      ", then the " (:CL "command-not-accessible")
      " error will be signalled. The returned command-line name should not be modified." (:PAR)
      "This is the inverse of " (:CL "find-command-from-command-line-name")
      ". It should be implemented in such as way that it is fast, since it may be used by presentation translators to produce pointer documentation."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-table-complete-input")) :PARAMS
       ((:I "command-table string action " (:GROUP (:FONT :FACE :TT) "&key ") "frame")) :KIND ("Function"))
      (:PAR) "A function that can be used as in conjunction with " (:CL "complete-input")
      " in order to complete over all of the command lines names accessible in the " (:TERM "command table") " "
      (:GROUP (:FONT :FACE :I) "command-table") ". " (:GROUP (:FONT :FACE :I) "string")
      " is the input string to complete over, and " (:GROUP (:FONT :FACE :I) "action") " is as for "
      (:CL "complete-from-possibilities") "." (:PAR) (:GROUP (:FONT :FACE :I) "frame")
      " is either an application frame, or " (:CL "nil") ". If " (:GROUP (:FONT :FACE :I) "frame")
      " is supplied, no disabled commands should be offered as valid completions." (:PAR)
      (:CL "command-table-complete-input")
      " could be implemented by collecting all of the command line names accessible in the command table and then calling "
      (:CL "complete-from-possibilities")
      ", or it could be implemented more efficiently than that (such as by caching a sorted list of command line names and using a binary search)."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "global-command-table")) :PARAMS ((:I)) :KIND ("Command Table")) (:PAR)
      "The command table from which all other command tables inherit by default. Programmers should not explicitly add anything to or remove anything from this command table. CLIM can use this command to store internals or system-wide commands and translators (for example, the translator that implements the \"identity\" translation from a type to itself). Programmers should not casually install any commands or translators into this command table."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "user-command-table")) :PARAMS ((:I)) :KIND ("Command Table")) (:PAR)
      "A command table that can be used by the programmer for any purpose. CLIM does not use it for anything, and its contents are completely undefined."
      (:PAR) " "))
    (:SECTION :TITLE ("27.3 " "Command Menus") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "Each command table may have a menu consisting of an ordered sequence of command menu items. The menu specifies a mapping from a menu name (the name displayed in the menu) to a command menu item. The menu of an application frame's top-level command table may be presented in a window system specific way, for example, as a menu bar."
     (:PAR) "Command menu items are stored as a list of the form "
     (:CL "("
          (:GROUP (:FONT :FACE :I) "type")
          " "
          (:GROUP (:FONT :FACE :I) "value")
          " . "
          (:GROUP (:FONT :FACE :I) "options")
          ")")
     ", where " (:GROUP (:FONT :FACE :I) "type") " and " (:GROUP (:FONT :FACE :I) "value") " are as in "
     (:CL "add-menu-item-to-command-table") ", and " (:GROUP (:FONT :FACE :I) "options")
     " is a list of keyword-value pairs. The allowable keywords are " (:CL ":documentation")
     ", which is used to supply optional pointer documention for the command menu item, and " (:CL ":text-style")
     ", which is used to indicate what text style should be used for this command menu item when it is displayed in a command menu."
     (:PAR) (:CL "add-menu-item-to-command-table") ", " (:CL "remove-menu-item-from-command-table") ", and "
     (:CL "find-menu-item")
     " ignore the character case of the command menu item's name when searching through the command table's menu."
     (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "add-menu-item-to-command-table")) :PARAMS
       ((:I "command-table string type value  " (:GROUP (:FONT :FACE :TT) "&key ")
         "documentation (after ':end) keystroke  text-style (errorp t)"))
       :KIND ("Function"))
      (:PAR) "Adds a command menu item to " (:GROUP (:FONT :FACE :I) "command-table") "'s menu. "
      (:GROUP (:FONT :FACE :I) "string") " is the name of the command menu item; its character case is ignored. "
      (:GROUP (:FONT :FACE :I) "type") " is either " (:CL ":command") ", " (:CL ":function") ", " (:CL ":menu") ", or "
      (:CL ":divider") ". " (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "."
      (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL) "How do we make iconic command menus? Probably another keyword... --- SWM") (:PAR)
      "When " (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":command") ", " (:GROUP (:FONT :FACE :I) "value")
      " must be a command (a cons of a command name followed by a list of the command's arguments), or a command name. (When "
      (:GROUP (:FONT :FACE :I) "value")
      " is a command name, it behaves as though a command with no arguments was supplied.) In the case where all of the command's required arguments are supplied, clicking on an item in the menu invokes the command immediately. Otherwise, the user will be prompted for the remaining required arguments."
      (:PAR) "When " (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":function") ", " (:GROUP (:FONT :FACE :I) "value")
      " must be function having indefinite extent that, when called, returns a command. The function is called with two arguments, the gesture the user used to select the item (either a keyboard or button press event) and a \"numeric argument\"."
      (:PAR) "When " (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":menu")
      ", this item indicates that a sub-menu will be invoked, and so " (:GROUP (:FONT :FACE :I) "value")
      " must be another command table or the name of another command table." (:PAR) "When "
      (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":divider")
      ", some sort of a dividing line is displayed in the menu at that point. If " (:GROUP (:FONT :FACE :I) "string")
      " is supplied, it will be drawn as the divider instead of a line. If the look and feel provided by the underlying window system has no corresponding concept, "
      (:CL ":divider") " items may be ignored. " (:GROUP (:FONT :FACE :I) "value") " is ignored." (:PAR)
      (:GROUP (:FONT :FACE :I) "documentation")
      " is a documentation string, which can be used as mouse documentation for the command menu item." (:PAR)
      (:GROUP (:FONT :FACE :I) "text-style") " is either a text style spec or " (:CL "nil")
      ". It is used to indicate that the command menu item should be drawn with the supplied text style in command menus."
      (:PAR) (:GROUP (:FONT :FACE :I) "after") " must be either " (:CL ":start")
      " (meaning to add the new item to the beginning of the menu), " (:CL ":end") " or " (:CL "nil")
      " (meaning to add the new item to the end of the menu), or a string naming an existing entry (meaning to add the new item after that entry). If "
      (:GROUP (:FONT :FACE :I) "after") " is " (:CL ":sort")
      ", then the item is inserted in such as way as to maintain the menu in alphabetical order." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "keystroke")
      " is supplied, the item will be added to the command table's keystroke accelerator table. The value of "
      (:GROUP (:FONT :FACE :I) "keystroke") " must be a keyboard gesture name. This is exactly equivalent to calling "
      (:CL "add-keystroke-to-command-table") " with the arguments " (:GROUP (:FONT :FACE :I) "command-table") ", "
      (:GROUP (:FONT :FACE :I) "keystroke") ", " (:GROUP (:FONT :FACE :I) "type") " and "
      (:GROUP (:FONT :FACE :I) "value") ". When " (:GROUP (:FONT :FACE :I) "keystroke") " is supplied and "
      (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":command") " or " (:CL ":function")
      ", typing a key on the keyboard that matches to the keystroke accelerator gesture will invoke the command specified by "
      (:GROUP (:FONT :FACE :I) "value") ". When " (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":menu")
      ", the command will continue to be read from the sub-menu indicated by " (:GROUP (:FONT :FACE :I) "value")
      " in a window system specific manner." (:PAR) "If the item named by " (:GROUP (:FONT :FACE :I) "string")
      " is already present in the command table's menu and " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true")
      ", then the " (:CL "command-already-present")
      " error will be signalled. When the item is already present in the command table's menu and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "false")
      ", the old item will first be removed from the menu. Note that the character case of "
      (:GROUP (:FONT :FACE :I) "string") " is ignored when searching the command table's menu." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "remove-menu-item-from-command-table")) :PARAMS
       ((:I "command-table string " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Removes the item named by " (:GROUP (:FONT :FACE :I) "string") " from "
      (:GROUP (:FONT :FACE :I) "command-table") "'s menu. " (:GROUP (:FONT :FACE :I) "command-table") " is a "
      (:TERM "command table designator") "." (:PAR) "If the item is not present in the command table's menu and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", then the " (:CL "command-not-present")
      " error will be signalled. Note that the character case of " (:GROUP (:FONT :FACE :I) "string")
      " is ignored when searching the command table's menu." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "map-over-command-table-menu-items")) :PARAMS ((:I "function command-table")) :KIND
       ("Function"))
      (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all of the items in "
      (:GROUP (:FONT :FACE :I) "command-table") "'s menu. " (:GROUP (:FONT :FACE :I) "function")
      " must be a function of three arguments, the menu name, the keystroke accelerator gesture (which will be "
      (:CL "nil")
      " if there is none), and the command menu item; it has dynamic extent. The command menu items are mapped over in the order specified by "
      (:CL "add-menu-item-to-command-table") ". " (:GROUP (:FONT :FACE :I) "command-table") " is a "
      (:TERM "command table designator") "." (:PAR) (:CL "map-over-command-table-menu-items")
      " does not descend into sub-menus. If the programmer requires this behavior, he should examine the type of the command menu item to see if it is "
      (:CL ":menu") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-menu-item")) :PARAMS
       ((:I "menu-name command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR)
      "Given a menu name and a command table, returns two values, the command menu item and the command table in which it was found. (Since menus are not inherited, the second returned value will always be "
      (:GROUP (:FONT :FACE :I) "command-table") ".) " (:GROUP (:FONT :FACE :I) "command-table") " is a "
      (:TERM "command table designator")
      ". This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR)
      "If there is no command menu item corresponding to " (:GROUP (:FONT :FACE :I) "menu-name") " present in "
      (:GROUP (:FONT :FACE :I) "command-table") " and " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true")
      ", then the " (:CL "command-not-accessible") " error will be signalled. Note that the character case of "
      (:GROUP (:FONT :FACE :I) "string") " is ignored when searching the command table's menu." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-menu-item-type")) :PARAMS ((:I "menu-item")) :KIND ("Function")) (:PAR)
      "Returns the type of the command menu item " (:GROUP (:FONT :FACE :I) "menu-item") ", for example, "
      (:CL ":menu") " or " (:CL ":command") ". If " (:GROUP (:FONT :FACE :I) "menu-item")
      " is not a command menu item, the result is unspecified." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-menu-item-value")) :PARAMS ((:I "menu-item")) :KIND ("Function")) (:PAR)
      "Returns the value of the command menu item " (:GROUP (:FONT :FACE :I) "menu-item")
      ". For example, if the type of " (:GROUP (:FONT :FACE :I) "menu-item") " is " (:CL ":command")
      ", this will return a command or a command name. If " (:GROUP (:FONT :FACE :I) "menu-item")
      " is not a command menu item, the result is unspecified." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "command-menu-item-options")) :PARAMS ((:I "menu-item")) :KIND ("Function"))
      (:PAR) "Returns a list of the options for the command menu item " (:GROUP (:FONT :FACE :I) "menu-item") ". If "
      (:GROUP (:FONT :FACE :I) "menu-item") " is not a command menu item, the result is unspecified." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "display-command-table-menu")) :PARAMS
       ((:I "command-table stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "max-width max-height n-rows n-columns  x-spacing y-spacing initial-spacing row-wise  (cell-align-x "
         (:CL ":left") ") (cell-align-y " (:CL ":top") ")  (move-cursor " (:CL "t") ")"))
       :KIND ("Generic Function"))
      (:PAR) "Displays " (:GROUP (:FONT :FACE :I) "command-table") "'s menu on " (:GROUP (:FONT :FACE :I) "stream")
      ". Implementations may choose to use " (:CL "formatting-item-list")
      " or may display the command table's menu in a platform dependent manner, such as using the menu bar on a Macintosh. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "max-width") ", " (:GROUP (:FONT :FACE :I) "max-height") ", "
      (:GROUP (:FONT :FACE :I) "n-rows") ", " (:GROUP (:FONT :FACE :I) "n-columns") ", "
      (:GROUP (:FONT :FACE :I) "x-spacing") ", " (:GROUP (:FONT :FACE :I) "y-spacing") ", "
      (:GROUP (:FONT :FACE :I) "row-wise") ", " (:GROUP (:FONT :FACE :I) "initial-spacing") ", "
      (:GROUP (:FONT :FACE :I) "cell-align-x") ", " (:GROUP (:FONT :FACE :I) "cell-align-y") ", and "
      (:GROUP (:FONT :FACE :I) "move-cursor") " are as for " (:CL "formatting-item-list") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "menu-choose-command-from-command-table")) :PARAMS
       ((:I "command-table  " (:GROUP (:FONT :FACE :TT) "&key ")
         "associated-window default-style label  cache unique-id id-test  cache-value cache-test"))
       :KIND ("Function"))
      (:PAR) "Invokes a window system specific routine that displays a menu of commands from "
      (:GROUP (:FONT :FACE :I) "command-table") "'s menu, and allows the user to choose one of the commands. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator")
      ". The returned value is a command object. This may invoke itself recursively when there are sub-menus." (:PAR)
      (:GROUP (:FONT :FACE :I) "associated-window") ", " (:GROUP (:FONT :FACE :I) "default-style") ", "
      (:GROUP (:FONT :FACE :I) "label") ", " (:GROUP (:FONT :FACE :I) "cache") ", "
      (:GROUP (:FONT :FACE :I) "unique-id") ", " (:GROUP (:FONT :FACE :I) "id-test") ", "
      (:GROUP (:FONT :FACE :I) "cache-value") ", and " (:GROUP (:FONT :FACE :I) "cache-test") " are as for "
      (:CL "menu-choose") "." (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL) "Should this be generic on application frames? --- SWM") (:PAR) " "))
    (:SECTION :TITLE ("27.4 " "Keystroke Accelerators") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "Each command table may have a mapping from keystroke accelerator gesture names to command menu items. When a user types a key on the keyboard that corresponds to the gesture for keystroke accelerator, the corresponding command menu item will be invoked. Note that command menu items are shared among the command table's menu and the accelerator table. There are several reasons for this. One is that it is common to have menus display the keystroke associated with a particular item, if there is one."
     (:PAR)
     "Note that, despite the fact the keystroke accelerators are specified using keyboard gesture names rather than characters, the conventions for typed characters vary widely from one platform to another. Therefore the programmer must be careful in choosing keystroke accelerators. Some sort of per-platform conditionalization is to be expected."
     (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "add-keystroke-to-command-table")) :PARAMS
       ((:I "command-table gesture type value  " (:GROUP (:FONT :FACE :TT) "&key ") "documentation (errorp t)")) :KIND
       ("Function"))
      (:PAR) "Adds a command menu item to " (:GROUP (:FONT :FACE :I) "command-table")
      "'s keystroke accelerator table. " (:GROUP (:FONT :FACE :I) "gesture")
      " is a keyboard gesture name to be used as the accelerator. " (:GROUP (:FONT :FACE :I) "type") " and "
      (:GROUP (:FONT :FACE :I) "value") " are as in " (:CL "add-menu-item-to-command-table") ", except that "
      (:GROUP (:FONT :FACE :I) "type") " must be either " (:CL ":command") ", " (:CL ":function") " or " (:CL ":menu")
      ". " (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR)
      (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL) "Should we allow " (:GROUP (:FONT :FACE :I) "gesture")
       " to be a gesture specification as well as just a gesture name? It simplifies its use by avoiding a profusion of defined gesture names, but we may want to encourage the use of gesture names. --- SWM")
      (:PAR) (:GROUP (:FONT :FACE :I) "documentation")
      " is a documentation string, which can be used as documentation for the keystroke accelerator." (:PAR)
      "If the command menu item associated with " (:GROUP (:FONT :FACE :I) "gesture")
      " is already present in the command table's accelerator table and " (:GROUP (:FONT :FACE :I) "errorp") " is "
      (:TERM "true") ", then the " (:CL "command-already-present")
      " error will be signalled. When the item is already present in the command table's accelerator table and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "false") ", the old item will first be removed." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "remove-keystroke-from-command-table")) :PARAMS
       ((:I "command-table gesture " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Removes the command menu item named by keyboard gesture name " (:GROUP (:FONT :FACE :I) "gesture")
      " from " (:GROUP (:FONT :FACE :I) "command-table") "'s accelerator table. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR)
      "If the command menu item associated with " (:GROUP (:FONT :FACE :I) "gesture")
      " is not present in the command table's menu and " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true")
      ", then the " (:CL "command-not-present") " error will be signalled." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "map-over-command-table-keystrokes")) :PARAMS ((:I "function command-table")) :KIND
       ("Function"))
      (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all of the keystroke accelerators in "
      (:GROUP (:FONT :FACE :I) "command-table") "'s accelerator table. " (:GROUP (:FONT :FACE :I) "function")
      " must be a function of three arguments, the menu name (which will be " (:CL "nil")
      " if there is none), the keystroke accelerator, and the command menu item; it has dynamic extent. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR)
      (:CL "map-over-command-table-keystrokes")
      " does not descend into sub-menus. If the programmer requires this behavior, he should examine the type of the command menu item to see if it is "
      (:CL ":menu") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-keystroke-item")) :PARAMS
       ((:I "gesture command-table " (:GROUP (:FONT :FACE :TT) "&key ") "test (errorp t)")) :KIND ("Function"))
      (:PAR) "Given a keyboard gesture " (:GROUP (:FONT :FACE :I) "gesture")
      " and a command table, returns two values, the command menu item associated with the gesture and the command table in which it was found. (Since keystroke accelerators are not inherited, the second returned value will always be "
      (:GROUP (:FONT :FACE :I) "command-table") ".)" (:PAR)
      "This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR)
      (:GROUP (:FONT :FACE :I) "test")
      " is the test used to compare the supplied gesture to the gesture name in the command table. The supplied gesture will generally be an event object, so the default for "
      (:GROUP (:FONT :FACE :I) "test") " is " (:CL "event-matches-gesture-name-p") "." (:PAR)
      "If the keystroke accelerator is not present in " (:GROUP (:FONT :FACE :I) "command-table") " and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", then the " (:CL "command-not-present")
      " error will be signalled. " (:GROUP (:FONT :FACE :I) "command-table") " is a "
      (:TERM "command table designator") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "lookup-keystroke-item")) :PARAMS
       ((:I "gesture command-table " (:GROUP (:FONT :FACE :TT) "&key ") "test")) :KIND ("Function"))
      (:PAR) "Given a keyboard gesture " (:GROUP (:FONT :FACE :I) "gesture")
      " and a command table, returns two values, the command menu item associated with the gesture and the command table in which it was found. Note that "
      (:GROUP (:FONT :FACE :I) "gesture")
      " may be either a keyboard gesture name of a gesture object, and is handled in the same way as in "
      (:CL "find-keystroke-item")
      ". This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR)
      "Unlike " (:CL "find-keystroke-item") ", this follows the sub-menu chains that can be created with "
      (:CL "add-menu-item-to-command-table")
      ". If the keystroke accelerator cannot be found in the command table or any of the command tables from which it inherits, "
      (:CL "lookup-keystroke-item") " will return " (:CL "nil") ". " (:GROUP (:FONT :FACE :I) "command-table") " is a "
      (:TERM "command table designator") "." (:PAR) (:GROUP (:FONT :FACE :I) "test")
      " is the test used to compare the supplied gesture to the gesture name in the command table. The supplied gesture will generally be an event object, so the default for "
      (:GROUP (:FONT :FACE :I) "test") " is " (:CL "event-matches-gesture-name-p") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "lookup-keystroke-command-item")) :PARAMS
       ((:I "gesture command-table " (:GROUP (:FONT :FACE :TT) "&key ") "test numeric-arg")) :KIND ("Function"))
      (:PAR) "Given a keyboard gesture " (:GROUP (:FONT :FACE :I) "gesture")
      " and a command table, returns the command associated with the keystroke, or "
      (:GROUP (:FONT :FACE :I) "gesture") " if no command is found. Note that " (:GROUP (:FONT :FACE :I) "gesture")
      " may be either a keyboard gesture name of a gesture object, and is handled in the same way as in "
      (:CL "find-keystroke-item")
      ". This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR)
      "This is like " (:CL "find-keystroke-item")
      ", except that only keystrokes that map to an enabled application command will be matched. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "test")
      " is the test used to compare the supplied gesture to the gesture name in the command table. The supplied gesture will generally be an event object, so the default for "
      (:GROUP (:FONT :FACE :I) "test") " is " (:CL "event-matches-gesture-name-p") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "numeric-arg")
      " (which defaults to 1) is substituted into the resulting command for any occurrence of "
      (:CL "*numeric-argument-marker*")
      " in the command. This is intended to allow programmers to define keystroke accelerators that take simple numeric arguments, which will be passed on by the input editor."
      (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL) "Do the above three functions need to have their hands on the port? If "
       (:CL "event-matches-gesture-name-p")
       " needs the port, then the answer is yes. Otherwise, if gesture names are \"global\" across all ports, then these don't need the port. --- SWM")
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "substitute-numeric-argument-marker")) :PARAMS ((:I "command numeric-arg")) :KIND
       ("Function"))
      (:PAR) "Given a command object " (:GROUP (:FONT :FACE :I) "command") ", this substitutes the value of "
      (:GROUP (:FONT :FACE :I) "numeric-arg") " for all occurrences of the value of " (:CL "*numeric-argument-marker*")
      " in the command, and returns a command object with those substitutions." (:PAR) " "))
    (:SECTION :TITLE ("27.5 " "Presentation Translator Utilities") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "These are some utilities for maintain presentation translators in command tables. Presentation translators are discussed in more detail in Chapter "
     (:REF :NAME "presentation-types") "." (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "add-presentation-translator-to-command-table")) :PARAMS
       ((:I "command-table translator-name  " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Adds the translator named by " (:GROUP (:FONT :FACE :I) "translator-name") " to "
      (:GROUP (:FONT :FACE :I) "command-table") ". The translator must have been previously defined with "
      (:CL "define-presentation-translator") " or " (:CL "define-presentation-to-command-translator") ". "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "translator-name") " is already present in " (:GROUP (:FONT :FACE :I) "command-table")
      " and " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", then the " (:CL "command-already-present")
      " error will be signalled. When the translator is already present and " (:GROUP (:FONT :FACE :I) "errorp") " is "
      (:TERM "false") ", the old translator will first be removed." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "remove-presentation-translator-from-command-table")) :PARAMS
       ((:I "command-table translator-name  " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR) "Removes the translator named by " (:GROUP (:FONT :FACE :I) "translator-name") " from "
      (:GROUP (:FONT :FACE :I) "command-table") ". " (:GROUP (:FONT :FACE :I) "command-table") " is a "
      (:TERM "command table designator") "." (:PAR) "If the translator is not present in the command table and "
      (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true") ", then the " (:CL "command-not-present")
      " error will be signalled." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "map-over-command-table-translators")) :PARAMS
       ((:I "function command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(inherited t)")) :KIND ("Function"))
      (:PAR) "Applies " (:GROUP (:FONT :FACE :I) "function") " to all of the translators accessible in "
      (:GROUP (:FONT :FACE :I) "command-table") ". " (:GROUP (:FONT :FACE :I) "function")
      " must be a function of one argument, the translator; it has dynamic extent. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR) "If "
      (:GROUP (:FONT :FACE :I) "inherited") " is " (:TERM "false") ", this applies "
      (:GROUP (:FONT :FACE :I) "function") " only to those translators present in "
      (:GROUP (:FONT :FACE :I) "command-table") ", that is, it does not map over any inherited command tables. If "
      (:GROUP (:FONT :FACE :I) "inherited") " is " (:TERM "true")
      ", then the inherited command tables are traversed in the same order as for "
      (:CL "do-command-table-inheritance") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "find-presentation-translator")) :PARAMS
       ((:I "translator-name command-table " (:GROUP (:FONT :FACE :TT) "&key ") "(errorp t)")) :KIND ("Function"))
      (:PAR)
      "Given a translator name and a command table, returns two values, the presentation translator and the command table in which it was found. If the translator is not present in "
      (:GROUP (:FONT :FACE :I) "command-table") " and " (:GROUP (:FONT :FACE :I) "errorp") " is " (:TERM "true")
      ", then the " (:CL "command-not-accessible") " error will be signalled. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR) " "))
    (:SECTION :TITLE ("27.6 " "The Command Processor") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "Once a set of commands has been defined, CLIM provides a variety of means to read a command. These are all mediated by the Command Processor."
     (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "read-command")) :PARAMS
       ((:I "command-table  " (:GROUP (:FONT :FACE :TT) "&key ")
         "(stream *standard-input*)  command-parser command-unparser partial-command-parser  use-keystrokes"))
       :KIND ("Function"))
      (:PAR) (:CL "read-command") " is the standard interface used to read a command line. "
      (:GROUP (:FONT :FACE :I) "stream") " is an extended input stream, and " (:GROUP (:FONT :FACE :I) "command-table")
      " is a " (:TERM "command table designator") "." (:PAR) (:GROUP (:FONT :FACE :I) "command-parser")
      " must be a function of two arguments, a command table and a stream. It reads a command from the user and returns a command object, or "
      (:CL "nil") " if an empty command line was read. The default value for "
      (:GROUP (:FONT :FACE :I) "command-parser") " is the value of " (:CL "*command-parser*") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "command-unparser")
      " must be a function of three arguments, a command table, a stream, and a command to \"unparse\". It prints a textual description of the command its supplied arguments onto the stream. The default value for "
      (:GROUP (:FONT :FACE :I) "command-unparser") " is the value of " (:CL "*command-unparser*") "." (:PAR)
      (:GROUP (:FONT :FACE :I) "partial-command-parser")
      " must be a function of four arguments, a command table, a stream, a partial command, and a start position. The partial command is a command object with the value of "
      (:CL "*unsupplied-argument-marker*")
      " in place of any argument that needs to be filled in. The function reads the remaining, unsupplied arguments in any way it sees fit (for example, via an "
      (:CL "accepting-values")
      " dialog), and returns a command object. The start position is the original input-editor scan position of the stream, when the stream is an interactive stream. The default value for "
      (:GROUP (:FONT :FACE :I) "partial-command-parser") " is the value of " (:CL "*partial-command-parser*") "."
      (:PAR) (:GROUP (:FONT :FACE :I) "command-parser") ", " (:GROUP (:FONT :FACE :I) "command-unparser") ", and "
      (:GROUP (:FONT :FACE :I) "partial-command-parser") " have dynamic extent." (:PAR) "When "
      (:GROUP (:FONT :FACE :I) "use-keystrokes") " is " (:TERM "true")
      ", the command reader will also process keystroke accelerators. (Implementations will typically use "
      (:CL "with-command-table-keystrokes") " and " (:CL "read-command-using-keystrokes")
      " to implement the case when " (:GROUP (:FONT :FACE :I) "use-keystrokes") " is " (:TERM "true") ".)" (:PAR)
      "Input editing, while conceptually an independent facility, fits into the command processor via its use of "
      (:CL "accept") ". That is, " (:CL "read-command") " must be implemented by calling " (:CL "accept")
      " to read command objects, and " (:CL "accept") " itself makes use of the input editing facilities." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-command-table-keystrokes")) :PARAMS
       ((:I "(keystroke-var command-table) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:PAR) "Binds " (:GROUP (:FONT :FACE :I) "keystroke-var")
      " to a sequence that contains all of the keystroke accelerators in " (:GROUP (:FONT :FACE :I) "command-table")
      "'s menu, and then executes " (:GROUP (:FONT :FACE :I) "body") " in that context. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") ". "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "read-command-using-keystrokes")) :PARAMS
       ((:I "command-table keystrokes  " (:GROUP (:FONT :FACE :TT) "&key ")
         "(stream *standard-input*)  command-parser command-unparser  partial-command-parser"))
       :KIND ("Function"))
      (:PAR)
      "Reads a command from the user via command lines, the pointer, or a single keystroke, and returns either a command object, or a keyboard gesture object if the user typed a keystroke that is in "
      (:GROUP (:FONT :FACE :I) "keystrokes") " but does not have a command associated with it in "
      (:GROUP (:FONT :FACE :I) "command-table") "." (:PAR) (:GROUP (:FONT :FACE :I) "keystrokes")
      " is a sequence of keyboard gesture names that are the keystroke accelerators." (:PAR)
      (:GROUP (:FONT :FACE :I) "command-table") ", " (:GROUP (:FONT :FACE :I) "stream") ", "
      (:GROUP (:FONT :FACE :I) "command-parser") ", " (:GROUP (:FONT :FACE :I) "command-unparser") ", and "
      (:GROUP (:FONT :FACE :I) "partial-command-parser") " are as for " (:CL "read-command") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-line-command-parser")) :PARAMS ((:I "command-table stream")) :KIND ("Function"))
      (:PAR)
      "The default command-line parser. It reads a command name and the command's arguments as a command line from "
      (:GROUP (:FONT :FACE :I) "stream") " (with completion as much as is possible), and returns a command object. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator")
      " that specifies the command table to use; the commands are read via the textual command-line name." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-line-command-unparser")) :PARAMS ((:I "command-table stream command")) :KIND
       ("Function"))
      (:PAR) "The default command-line unparser. It prints the command " (:GROUP (:FONT :FACE :I) "command")
      " as a command name and its arguments as a command line on " (:GROUP (:FONT :FACE :I) "stream") ". "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator")
      " that specifies the command table to use; the commands are displayed using the textual command-line name."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-line-read-remaining-arguments-for-partial-command")) :PARAMS ((:I)) :KIND
       ("Function"))
      (:GROUP "command-table stream partial-command start-position") (:PAR)
      "The default partial command-line parser. If the remaining arguments are at the end of the command line, it reads them as a command line, otherwise it constructs a dialog using "
      (:CL "accepting-values") " and reads the remaining arguments from the dialog. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "menu-command-parser")) :PARAMS ((:I "command-table stream")) :KIND ("Function"))
      (:PAR)
      "The default menu-driven command parser. It uses only pointer clicks to construct a command. It relies on presentations of all arguments being visible. "
      (:GROUP (:FONT :FACE :I) "command-table") " and " (:GROUP (:FONT :FACE :I) "stream") " are as for "
      (:CL "command-line-parser") "." (:PAR)
      "There is no menu-driven command unparser, since it makes no sense to unparse a completely menu-driven command."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "menu-read-remaining-arguments-for-partial-command")) :PARAMS ((:I)) :KIND ("Function"))
      (:GROUP "command-table stream partial-command start-position") (:PAR)
      "The default menu-driven partial command parser. It uses only pointer clicks to fill in the command. Again, it relies on presentations of all arguments being visible. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "*command-parser*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "Contains the currently active command parsing function. The default value is the function "
      (:CL "command-line-command-parser") ", which is the default command-line parser." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*command-unparser*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "Contains the currently active command unparsing function. The default value is the function "
      (:CL "command-line-command-unparser") ", which is the default command-line unparser." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*partial-command-parser*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "Contains the currently active partial command parsing function. The default value is the function "
      (:CL "command-line-read-remaining-arguments-for-partial-command") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*unsupplied-argument-marker*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "The value of " (:CL "*unsupplied-argument-marker*")
      " is an object that can be uniquely identified as standing for an unsupplied argument in a command object."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*numeric-argument-marker*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "The value of " (:CL "*numeric-argument-marker*")
      " is an object that can be uniquely identified as standing for a numeric argument in a command object." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*command-name-delimiters*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "This is a list of the characters that separate the command name from the command arguments in a command line. The standard set of command name delimiters must include "
      (:CODE "#\\Space") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*command-argument-delimiters*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "This is a list of the characters that separate the command arguments from each other in a command line. The standard set of command argument delimiters must include "
      (:CODE "#\\Space") "." (:PAR) " ")
     (:SECTION :TITLE ("27.6.1 " "Command Presentation Types") :KIND :SUBSECTION :NAME (1 6 4 10) (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "command")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&key ") "command-table")) :KIND
        ("Presentation Type"))
       (:PAR) "The presentation type used to represent a command and its arguments; the command must be accessible in "
       (:GROUP (:FONT :FACE :I) "command-table") " and enabled in " (:CL "*application-frame*") ". "
       (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") ". If "
       (:GROUP (:FONT :FACE :I) "command-table")
       " is not supplied, it defaults to the command table for the current application frame, "
       (:CL "(frame-command-table *application-frame*)") "." (:PAR) "The object returned by the " (:CL "accept")
       " presentation method for " (:CL "command")
       " must be a command object, that is, a cons of the command name and the list of the command's arguments." (:PAR)
       "The " (:CL "accept") " presentation method for the " (:CL "command")
       " type must call the command parser stored in " (:CL "*command-parser*")
       " to read the command. The parser will recursively call " (:CL "accept") " to read a " (:CL "command-name")
       " and all of the command's arguments. The parsers themselves must be implemented by accepting objects whose presentation type is "
       (:CL "command") "." (:PAR) "If the command parser returns a partial command, the " (:CL "accept")
       " presentation method for the " (:CL "command") " type must call the partial command prser stored in "
       (:CL "*partial-command-parser*") "." (:PAR) "The " (:CL "present") " presentation method for the "
       (:CL "command") " type must call the command unparser stored in " (:CL "*command-unparser*") "." (:PAR)
       "If a presentation history is maintained for the " (:CL "command")
       " presentation type, it should be maintained separately for each instance of an application frame." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "command-name")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&key ") "command-table")) :KIND
        ("Presentation Type"))
       (:PAR)
       "The presentation type used to represent the name of a command that is both accessible in the command table "
       (:GROUP (:FONT :FACE :I) "command-table") " and enabled in " (:CL "*application-frame*") ". "
       (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") ". If "
       (:GROUP (:FONT :FACE :I) "command-table")
       " is not supplied, it defaults to the command table for the current application frame, "
       (:CL "(frame-command-table *application-frame*)") "." (:PAR) "The textual representation of a "
       (:CL "command-name")
       " object is the command-line name of the command, while the internal representation is the command name."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "command-or-form")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&key ") "command-table"))
        :KIND ("Presentation Type"))
       (:PAR)
       "The presentation type used to represent an object that is either a Lisp form, or a command and its arguments. The command must be accessible in "
       (:GROUP (:FONT :FACE :I) "command-table") " and enabled in " (:CL "*application-frame*") ". "
       (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") ". If "
       (:GROUP (:FONT :FACE :I) "command-table")
       " is not supplied, it defaults to the command table for the current application frame, "
       (:CL "(frame-command-table *application-frame*)") "." (:PAR) "The " (:CL "accept")
       " presentation method for this type reads a Lisp form, except that if the first character in the user's input is one of the characters in "
       (:CL "*command-dispatchers*") " it will read a command. The two returned values from the " (:CL "accept")
       " presentation method will be the command or form object and a presentation type specifier that is either "
       (:CL "command") " or " (:CL "form") "." (:PAR) "If a presentation history is maintained for the "
       (:CL "command-or-form")
       " presentation type, it should be maintained separately for each instance of an application frame." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "*command-dispatchers*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
       "This is a list of the characters that indicates that CLIM reads a command when it is accepting a "
       (:CL "command-or-form") ". The standard set of command argument delimiters must include the colon character, "
       (:CODE "#\\:") "." (:PAR)))))
   " "
   (:SECTION :TITLE ("28 " "Application Frames") :KIND :CHAPTER :NAME (4 10) " " (:LABEL :NAME "application-frames")
    (:PAR)
    (:SECTION :TITLE ("28.1 " "Overview of Application Frames") :KIND :SECTION :NAME (6 4 10) (:PAR)
     (:CONCEPT "Application frames") " (or simply, " (:CONCEPT "frames")
     ") are the central abstraction defined by CLIM for presenting an application's user interface. Many of the other features and facilities provided by CLIM (for example, the generic command loop, gadgets, look and feel independence) can be conveniently accessed through the frame facility. Frames can be displayed as either top-level windows or regions embedded within the space of the user interfaces of other applications. In addition to controlling the screen real estate managed by an application, a frame keeps track of the Lisp state variables that contain the state of the application."
     (:PAR) "The visual aspect of an application frame is established by defining a hierarchy of " (:CONCEPT "panes")
     ". CLIM panes are interactive objects that are analogous to the windows, gadgets, or widgets of other toolkits. Application builders can compose their application's user interface from a library of standard panes or by defining and using their own pane types. Application frames can use a number of different types of panes including "
     (:CONCEPT "layout panes") " for spatially organizing panes, " (:CONCEPT "user panes")
     " for presenting application specific information, and " (:CONCEPT "gadget panes")
     " for displaying data and obtaining user input. Panes are describe in greater detail in Chapter "
     (:REF :NAME "panes") " and Chapter " (:REF :NAME "gadgets") "." (:PAR)
     "Frames are managed by special applications called " (:CONCEPT "frame managers")
     ". Frame managers control the realization of the look and feel of a frame. The frame manager interprets the specification of the application frame in the context of the available window system facilities, taking into account preferences expressed by the user. In addition, the frame manager takes care of attaching the pane hierarchy of an application frame to an appropriate place in a window hierarchy. The most common type of frame manager is one that allows the user to manipulate the frames of other applications. This type of application is typically called a desktop manager, or in X Windows terminology, a window manager. In many cases, the window manager will be a non-Lisp application. In these cases, the frame manager will act as a mediator between the Lisp application and the host desktop manager."
     (:PAR)
     "Some applications may act as frame managers that allow the frames of other applications to be displayed with their own frames. For example, a text editor might allow figures generated by a graphic editor to be edited in place by managing the graphics editor's frame within its own frame."
     (:PAR)
     "Application frames provide support for a standard interaction processing loop, like the Lisp \"read-eval-print\" loop, called a "
     (:CONCEPT "command loop")
     ". The application programmer has to write only the code that implements the frame-specific commands and output display functions. A key aspect of the command loop is the separation of the specification of the frame's commands from the specification of the end-user interaction style."
     (:PAR)
     "The standard interaction loop consists of reading an input \"sentence\" (the command and all of its operands), executing the command, and updating the displayed information as appropriate. CLIM implementations are free to run the display update part of the loop at a lower priority than command execution, for example, some implementations may choose not to update the display if there is typed-ahead input. Note that by default command execution and display will not occur simultaneously, so user-defined functions need not have to cope with multiprocessing. Of course, the programmer can use multiple processes, but CLIM neither directly supports nor precludes doing so."
     (:PAR)
     "To write an application that uses the standard interaction loop provided by CLIM, an application programmer does the following:"
     (:PAR)
     (:UL
      (:LI "Defines the presentation types that correspond to the user interface entities of the application." (:PAR))
      (:LI
       "Defines the commands that correspond to the visible operations of the application, specifying the presentation types of the operands involved in each command."
       (:PAR))
      (:LI "Defines the set of frames and panes needed to support the application." (:PAR))
      (:LI
       "Defines the output display functions associated with each of the panes (possibly using other facilities such as the incremental redisplay). "))
     (:PAR)
     "Taking as an example a simple ECAD program, the programmer would first define the appropriate presentation types, such as wires, input and output signals, gates, resistors, and so forth. He would then define the program's commands in terms of these types. For example, the \"Connect\" command might take two operands, one of type \"component\" and the other of type \"wire\". The programmer may wish to specify the interaction style for invoking each command, for example, direct manipulation via translators, or selection of commands from menus. After defining an application frame that includes a CLIM stream pane, the programmer then writes the frame-specific display routine that displays the circuit layout. Now the application is ready to go. The end-user selects a command (via a menu or command-line, or whatever), the top-level loop takes care of collecting the operands for that command (via a variety of user gestures), and then the application invokes the command. The command may have a side-effect on the frame's \"database\" of information, which can in turn affect the output displayed by the redisplay phase."
     (:PAR)
     "Note that this definition of the standard interaction loop does not constrain the interaction style to be a command-line interface. The input sentence may be entered via single keystrokes, pointer input, menu selection, dialogs, or by typing full command lines."
     (:PAR) " ")
    (:SECTION :TITLE ("28.2 " "Defining and Creating Application Frames") :KIND :SECTION :NAME (6 4 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "application-frame")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to an application frame. If you want to create a new class that behaves like an application frame, it should be a subclass of "
      (:CL "application-frame") ". All instantiable subclasses of " (:CL "application-frame")
      " must obey the application frame protocol. " (:PAR) "All application frame classes are mutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "application-frame-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an " (:TERM "application frame")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":name")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":pretty-name")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":command-table")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":disabled-commands")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":panes")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":menu-bar")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":calling-frame")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":state")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":properties")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "application-frame")
      " must handle these initargs, which are used to specify, respectively, the name, pretty name, command table, initial set of disabled commands, the panes, the menu bar, calling frame, state, and initial properties for the frame."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-application-frame")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable standard class that implements application frames. By default, most application frame classes will inherit from this class, unless a non-"
      (:CL "nil") " value for " (:GROUP (:FONT :FACE :I) "superclasses") " is supplied to "
      (:CL "define-application-frame") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "define-application-frame")) :PARAMS
       ((:I "name superclasses slots " (:GROUP (:FONT :FACE :TT) "&rest ") "options")) :KIND ("Macro"))
      (:PAR) "Defines a frame and CLOS class named by the symbol " (:GROUP (:FONT :FACE :I) "name")
      " that inherits from " (:GROUP (:FONT :FACE :I) "superclasses") " and has state variables specified by "
      (:GROUP (:FONT :FACE :I) "slots") ". " (:GROUP (:FONT :FACE :I) "superclasses")
      " is a list of superclasses that the new class will inherit from (as in " (:CL "defclass") "). When "
      (:GROUP (:FONT :FACE :I) "superclasses") " is " (:CL "nil") ", it behaves as though a superclass of "
      (:CL "standard-application-frame") " was supplied. " (:GROUP (:FONT :FACE :I) "slots")
      " is a list of additional slot specifiers, whose syntax is the same as the slot specifiers in " (:CL "defclass")
      ". Each instance of the frame will have slots as specified by these slot specifiers. These slots will typically hold any per-instance frame state."
      (:PAR) (:GROUP (:FONT :FACE :I) "options") " is a list of " (:CL "defclass")
      "-style options, and can include the usual " (:CL "defclass") " options, plus any of the following:" (:PAR)
      (:UL
       (:LI (:CL ":pane") " " (:GROUP (:FONT :FACE :I) "form") ", where " (:GROUP (:FONT :FACE :I) "form")
        " specifies the single pane in the application. The default is " (:CL "nil")
        ", meaning that there is no single pane. This is the simplest way to define a pane hierarchy. The "
        (:CL ":pane") " option is mutually exclusive with the " (:CL ":panes") " options. See Section "
        (:REF :NAME "frame-panes") " for a complete description of the " (:CL ":pane") " option." (:PAR))
       (:LI (:CL ":panes") " " (:GROUP (:FONT :FACE :I) "form") ", where " (:GROUP (:FONT :FACE :I) "form")
        " is an alist that specifies names and panes of the application. The default is " (:CL "nil")
        ", meaning that there are no named panes. The " (:CL ":panes") " and " (:CL ":pane")
        " options are mutually exclusive. See Section " (:REF :NAME "frame-panes")
        " for a complete description of the " (:CL ":panes") " option." (:PAR))
       (:LI (:CL ":layouts") " " (:GROUP (:FONT :FACE :I) "form") ", where " (:GROUP (:FONT :FACE :I) "form")
        " specifies the layout. The default layout is to lay out all of the named panes in horizontal strips. See Section "
        (:REF :NAME "frame-panes") " for a complete description of the " (:CL ":layouts") " option." (:PAR))
       (:LI (:CL ":command-table") " " (:GROUP (:FONT :FACE :I) "name-and-options") ", where "
        (:GROUP (:FONT :FACE :I) "name-and-options")
        " is a list consisting of the name of the application frame's command table followed by some keyword-value pairs. The keywords can be "
        (:CL ":inherit-from") " or " (:CL ":menu") " (which are as in " (:CL "define-command-table")
        "). The default is to create a command table with the same name as the application frame." (:PAR))
       (:LI (:CL ":command-definer") " " (:GROUP (:FONT :FACE :I) "value") ", where " (:GROUP (:FONT :FACE :I) "value")
        " either " (:CL "nil") ", " (:CL "t") ", or another symbol. When it is " (:CL "nil")
        ", no command-defining macro is defined. When it is " (:CL "t")
        ", a command-defining macro is defined, whose name is of the form "
        (:CL "define-" (:GROUP (:FONT :FACE :I) "name") "-command")
        ". When it is another symbol, the symbol names the command-defining macro. The default is " (:CL "t") "."
        (:PAR))
       (:LI (:CL ":menu-bar") " " (:GROUP (:FONT :FACE :I) "form")
        " is used to specify what commands will appear in a \"menu bar\". It typically specifies the top-level commands of the application. "
        (:GROUP (:FONT :FACE :I) "form") " is either " (:CL "nil") ", meaning there is no menu bar; " (:CL "t")
        ", meaning that the menu from frame's command table (from the " (:CL ":command-table")
        " option) should be used; a symbol that names a command table, meaning that that command table's menu should be used; or a list, which is interpreted the same way the "
        (:CL ":menu") " option to " (:CL "define-command-table") " is interpreted. The default is " (:CL "t") "."
        (:PAR))
       (:LI (:CL ":disabled-commands") " " (:GROUP (:FONT :FACE :I) "commands") ", where "
        (:GROUP (:FONT :FACE :I) "commands")
        " is a list of command names that are initially disabled in the application frame. The set of enabled and disabled commands can be modified via "
        (:CL "(setf command-enabled)") "." (:PAR))
       (:LI (:CL ":top-level") " " (:GROUP (:FONT :FACE :I) "form") ", where " (:GROUP (:FONT :FACE :I) "form")
        " is a list whose first element is the name of a function to be called to execute the top-level loop. The function must take at least one argument, the frame. The rest of the list consists of additional arguments to be passed to the function. The default function is "
        (:CL "default-frame-top-level") "." (:PAR))
       (:LI (:CL ":icon") " " (:GROUP (:FONT :FACE :I) "pixmap")
        " specifies a pixmap to be displayed by the host's window manager when the frame is iconified." (:PAR))
       (:LI (:CL ":geometry") " " (:GROUP (:FONT :FACE :I) "plist") ", where " (:GROUP (:FONT :FACE :I) "plist")
        " is a property list containing the default values for the " (:CL ":left") ", " (:CL ":top") ", "
        (:CL ":right") ", " (:CL ":bottom") ", " (:CL ":width") ", and " (:CL ":height") " options to "
        (:CL "make-application-frame") ". "))
      (:PAR) "The " (:GROUP (:FONT :FACE :I) "name") ", " (:GROUP (:FONT :FACE :I) "superclasses") ", and "
      (:GROUP (:FONT :FACE :I) "slots")
      " arguments are not evaluated. The values of each of the options are evaluated." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-application-frame")) :PARAMS
       ((:I "frame-name " (:GROUP (:FONT :FACE :TT) "&rest ") "options  " (:GROUP (:FONT :FACE :TT) "&key ")
         "pretty-name  frame-manager enable state  left top right bottom width height  save-under frame-class  "
         (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
       :KIND ("Function"))
      (:PAR) "Makes an instance of the application frame of type " (:GROUP (:FONT :FACE :I) "frame-class") ". If "
      (:GROUP (:FONT :FACE :I) "frame-class") " is not supplied, it defaults to "
      (:GROUP (:FONT :FACE :I) "frame-name") "." (:PAR) "The size options " (:GROUP (:FONT :FACE :I) "left") ", "
      (:GROUP (:FONT :FACE :I) "top") ", " (:GROUP (:FONT :FACE :I) "right") ", " (:GROUP (:FONT :FACE :I) "bottom")
      ", " (:GROUP (:FONT :FACE :I) "width") ", and " (:GROUP (:FONT :FACE :I) "height")
      " can be used to specify the initial size of the frame. If they are unsupplied and " (:CL ":geometry")
      " was supplied to " (:CL "define-application-frame")
      ", then these arguments default from the specified geometry." (:PAR) (:GROUP (:FONT :FACE :I) "options")
      " are passed as additional arguments to " (:CL "make-instance") ", after the "
      (:GROUP (:FONT :FACE :I) "pretty-name") ", " (:GROUP (:FONT :FACE :I) "frame-manager") ", "
      (:GROUP (:FONT :FACE :I) "enable") ", " (:GROUP (:FONT :FACE :I) "state") ", "
      (:GROUP (:FONT :FACE :I) "save-under") ", " (:GROUP (:FONT :FACE :I) "frame-class")
      ", and size options have been removed." (:PAR) "If " (:GROUP (:FONT :FACE :I) "save-under") " is " (:TERM "true")
      ", then the sheets used to implement the user interface of the frame will have the \"save under\" property, if the host window system supports it."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "frame-manager")
      " is provided, then the frame is adopted by the specified frame manager. If the frame is adopted and either of "
      (:GROUP (:FONT :FACE :I) "enable") " or " (:GROUP (:FONT :FACE :I) "state")
      " are provided, the frame is pushed into the given state." (:PAR) "Once a frame has been create, "
      (:CL "run-frame-top-level") " can be called to make the frame visible and run its top-level function." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*application-frame*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "The current application frame. The global value is CLIM's default application, which serves only as a repository for whatever internal state is needed by CLIM to operate properly. This variable is typically used in the bodies of command to gain access to the state variables of the application frame, usually in conjunction with "
      (:CL "with-slots") " or " (:CL "slot-value") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-application-frame")) :PARAMS
       ((:I "(frame) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
      (:PAR) "This macro provides lexical access to the \"current\" frame for use with commands and the " (:CL ":pane")
      ", " (:CL ":panes") ", and " (:CL ":layouts") " options. " (:GROUP (:FONT :FACE :I) "frame")
      " is bound to the current frame within the context of one of those options." (:PAR)
      (:GROUP (:FONT :FACE :I) "frame") " is a symbol; it is not evaluated. " (:GROUP (:FONT :FACE :I) "body")
      " may have zero or more declarations as its first forms." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "map-over-frames")) :PARAMS
       ((:I "function " (:GROUP (:FONT :FACE :TT) "&key ") "port frame-manager")) :KIND ("Function"))
      (:PAR) "Applies the function " (:GROUP (:FONT :FACE :I) "function")
      " to all of the application frames that \"match\" " (:GROUP (:FONT :FACE :I) "port") " and "
      (:GROUP (:FONT :FACE :I) "frame-manager") ". If neither " (:GROUP (:FONT :FACE :I) "port") " nor "
      (:GROUP (:FONT :FACE :I) "frame-manager") " is supplied, all frames are considered to match. If "
      (:GROUP (:FONT :FACE :I) "frame-manager")
      " is supplied, only those frames that use that frame manager match. If " (:GROUP (:FONT :FACE :I) "port")
      " is supplied, only those frames that use that port match." (:PAR) (:GROUP (:FONT :FACE :I) "function")
      " is a function of one argument, the frame. It has dynamic extent." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "destroy-frame")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Destroys the application frame " (:GROUP (:FONT :FACE :I) "frame") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "raise-frame")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Raises the application frame " (:GROUP (:FONT :FACE :I) "frame")
      " to be on top of all of the other host windows by invoking " (:CL "raise-sheet")
      " on the frame's top-level sheet." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "bury-frame")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Buries the application frame " (:GROUP (:FONT :FACE :I) "frame")
      " to be underneath all of the other host windows by invoking " (:CL "bury-sheet")
      " on the frame's top-level sheet." (:PAR) " ")
     (:SECTION :TITLE ("28.2.1 " "Specifying the Panes of a Frame" (:LABEL :NAME "frame-panes")) :KIND :SUBSECTION
      :NAME (1 6 4 10) (:PAR)
      "The panes of a frame can be specified in one of two different ways. If the frame has a single layout and no need of named panes, then the "
      (:CL ":pane") " option can be used. Otherwise if named panes or multiple layouts are required, the "
      (:CL ":panes") " and " (:CL ":layouts") " options can be used. Note that the " (:CL ":pane")
      " option is mutually exclusive with " (:CL ":panes") " and " (:CL ":layouts")
      ". It is meaningful to define frames that have no panes at all; the frame will simply serve as a repository for state and commands."
      (:PAR) "Panes and gadgets are discussed in detail in Chapter " (:REF :NAME "panes") " and Chapter "
      (:REF :NAME "gadgets") "." (:PAR) "The value of the " (:CL ":pane")
      " option is a form that is used to create a single (albeit arbitrarily complex) pane. For example:" (:PAR)
      (:PRE "
(vertically ()
  (tabling ()
    ((horizontally ()
       (make-pane 'toggle-button)
       (make-pane 'toggle-button)
       (make-pane 'toggle-button))
     (make-pane 'text-field))
    ((make-pane 'push-button :label \"a button\")
     (make-pane 'slider)))
  (scrolling ()
    (make-pane 'application-pane
               :display-function 'a-display-function))
  (scrolling ()
    (make-pane 'interactor-pane)))
")
      (:PAR) "If the " (:CL ":pane") " option is not used, a set of named panes can be specified with the "
      (:CL ":panes") " option. Optionally, " (:CL ":layouts")
      " can also be used to describe different layouts of the set of panes." (:PAR) "The value of the " (:CL ":panes")
      " option is a list, each entry of which is of the form " (:GROUP (:FONT :FACE :I) "(name . body)") ". "
      (:GROUP (:FONT :FACE :I) "name") " is a symbol that names the pane, and " (:GROUP (:FONT :FACE :I) "body")
      " specifies how to create the pane. " (:GROUP (:FONT :FACE :I) "body")
      " is either a list containing a single element that is itself a list, or a list consisting of a symbol followed by zero or more keyword-value pairs. In the first case, the "
      (:GROUP (:FONT :FACE :I) "body") " is a form exactly like the form used in the " (:CL ":pane")
      " option. In the second case, " (:GROUP (:FONT :FACE :I) "body") " is a " (:CONCEPT "pane abbreviation")
      " where the initial symbol names the type of pane, and the keyword-value pairs are pane options. For gadgets, the pane type is the class name of the abstract gadget (for example, "
      (:CL "slider") " or " (:CL "push-button") "). For CLIM stream panes, the following abbreviations are defined:"
      (:PAR)
      (:UL (:LI (:CL ":interactor") "---a pane of type " (:CL "interactor-pane") "." (:PAR))
       (:LI (:CL ":application") "---a pane of type " (:CL "application-pane") "." (:PAR))
       (:LI (:CL ":command-menu") "---a pane of type " (:CL "command-menu-pane") "." (:PAR))
       (:LI (:CL ":pointer-documentation")
        "---a pane suitable for displaying pointer documentation, if the host window system does not provide this."
        (:PAR))
       (:LI (:CL ":title")
        "---a pane suitable for displaying the title of the application, if the host window system does not provide this."
        (:PAR))
       (:LI (:CL ":accept-values") "---a pane that can hold a \"modeless\" " (:CL "accepting-values") " dialog. "))
      (:PAR) "See Chapter " (:REF :NAME "panes") " and Chapter " (:REF :NAME "gadgets")
      " for more information on the individual pane and gadget classes, and the options they support." (:PAR)
      "An example of the use of " (:CL ":panes") " is:" (:PAR)
      (:PRE "
(:panes
  (buttons (horizontally ()
             (make-pane 'push-button :label \"Press me\")
             (make-pane 'push-button :label \"Squeeze me\")))
  (toggle toggle-button 
          :label \"Toggle me\")
  (interactor :interactor
              :width 300 :height 300)
  (application :application
               :display-function 'another-display-function
               :incremental-redisplay t))
")
      (:PAR) "The value of the " (:CL ":layouts") " option is a list, each entry of which is of the form "
      (:GROUP (:FONT :FACE :I) "(name layout)") ". " (:GROUP (:FONT :FACE :I) "name")
      " is a symbol that names the layout, and " (:GROUP (:FONT :FACE :I) "layout") " specifies the layout. "
      (:GROUP (:FONT :FACE :I) "layout") " is a form like the form used in the " (:CL ":pane")
      " option, with the extension to the syntax such that the name of a named pane can be used wherever a pane may appear. (This will typically be implemented by using "
      (:CL "symbol-macrolet") " for each of the named panes.) For example, assuming a frame that uses the "
      (:CL ":panes") " example above, the following layouts could be specified:" (:PAR)
      (:PRE "
(:layouts
  (default 
    (vertically ()
      button toggle 
      (scrolling () application)
      interactor))
  (alternate
    (vertically ()
      (scrolling () application)
      (scrolling () interactor)
      (horizontally ()
        button toggle))))
")
      (:PAR) "The syntax for " (:CL ":layouts") " can be concisely expressed as:" (:PAR)
      (:DL (:DT) (:DD (:CL ":layouts (" (:GROUP (:FONT :FACE :I) "layout-name layout-panes") ")") (:PAR)) (:DT)
       (:DD (:GROUP (:FONT :FACE :I) "layout-name") " is a symbol." (:PAR)) (:DT)
       (:DD (:GROUP (:FONT :FACE :I) "layout-panes") " is " (:GROUP (:FONT :FACE :I) "layout-panes1") " or "
        (:CL "(" (:GROUP (:FONT :FACE :I) "size-spec layout-panes1") ")") "." (:PAR))
       (:DT)
       (:DD (:GROUP (:FONT :FACE :I) "layout-panes1") " is a " (:GROUP (:FONT :FACE :I) "pane-name") ", or a "
        (:GROUP (:FONT :FACE :I) "layout-macro-form") ", or " (:GROUP (:FONT :FACE :I) "layout-code") "." (:PAR))
       (:DT)
       (:DD (:GROUP (:FONT :FACE :I) "layout-code")
        " is lisp code that generates a pane, which may include the name of a named pane." (:PAR))
       (:DT)
       (:DD (:GROUP (:FONT :FACE :I) "size-spec") " is a rational number less than 1, or " (:CL ":fill") ", or "
        (:CL ":compute") "." (:PAR))
       (:DT)
       (:DD (:GROUP (:FONT :FACE :I) "layout-macro-form") " is "
        (:CL "("
             (:GROUP (:FONT :FACE :I) "layout-macro-name")
             " ("
             (:GROUP (:FONT :FACE :I) "options")
             ") . "
             (:GROUP (:FONT :FACE :I) "body")
             ")")
        "." (:PAR))
       (:DT)
       (:DD (:GROUP (:FONT :FACE :I) "layout-macro-name") " is one of the layout macros, such as " (:CL "outlining")
        ", " (:CL "spacing") ", " (:CL "labelling") ", " (:CL "vertically") ", " (:CL "horizontally") ", or "
        (:CL "tabling") ". "))
      (:PAR) " "))
    (:SECTION :TITLE ("28.3 " "Application Frame Functions") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "The generic functions described in this section are the functions that can be used to read or modify the attributes of a frame. All classes that inherit from "
     (:CL "application-frame") " must inherit or implement methods for all of these functions." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-name")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the name of the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") ", which is a symbol." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-pretty-name")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the \"pretty name\" of the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      ", which is a string." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf frame-pretty-name)")) :PARAMS ((:I "name frame")) :KIND ("Generic Function"))
      (:PAR) "Sets the pretty name of the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") " to "
      (:GROUP (:FONT :FACE :I) "name")
      ", which must be a string. Changing the pretty name of a frame notifies its frame manager, which in turn may change some aspects of the appearance of the frame, such as its title bar."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-command-table")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the command table for the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf frame-command-table)")) :PARAMS ((:I "command-table frame")) :KIND
       ("Generic Function"))
      (:PAR) "Sets the command table for the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") " to "
      (:GROUP (:FONT :FACE :I) "command-table")
      ". Changing the frame's command table will redisplay the command menus (or menu bar) as needed. "
      (:GROUP (:FONT :FACE :I) "command-table") " is a " (:TERM "command table designator") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-standard-output")) :PARAMS ((:I "frame")) :KIND ("Generic Function"))
      (:PAR) "Returns the stream that will be used for " (:CL "*standard-output*") " for the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") ". The default method (on " (:CL "standard-application-frame")
      ") returns the first named pane of type " (:CL "application-pane")
      " that is visible in the current layout; if there is no such pane, it returns the first pane of type "
      (:CL "interactor-pane") " that is exposed in the current layout." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-standard-input")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the stream that will be used for " (:CL "*standard-input*") " for the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") ". The default method (on " (:CL "standard-application-frame")
      ") returns the first named pane of type " (:CL "interactor-pane")
      " that is visible in the current layout; if there is no such pane, the value returned by "
      (:GROUP "frame-standard-output") " is used." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-query-io")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the stream that will be used for " (:CL "*query-io*") " for the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") ". The default method (on " (:CL "standard-application-frame")
      ") returns the value returned by " (:CL "frame-standard-input") "; if that is " (:CL "nil")
      ", it returns the value returned by " (:CL "frame-standard-output") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-error-output")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the stream that will be used for " (:CL "*error-output*") " for the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") ". The default method (on " (:CL "standard-application-frame")
      ") returns the same value as " (:CL "frame-standard-output") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "*pointer-documentation-output*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
      "This will be bound either to " (:CL "nil") " or to a stream on which pointer documentation will be displayed."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "frame-pointer-documentation-output")) :PARAMS ((:I "frame")) :KIND ("Generic Function"))
      (:PAR) "Returns the stream that will be used for " (:CL "*pointer-documentation-output*") " for the "
      (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") ". The default method (on "
      (:CL "standard-application-frame") ") returns the first pane of type " (:CL "pointer-documentation-pane")
      ". If this returns " (:CL "nil") ", no pointer documentation will be generated for this frame." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-calling-frame")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the application frame that invoked the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") "."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-parent")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the object that acts as the parent for the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      ". This often, but not always, returns the same value as " (:CL "frame-manager") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-panes")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the pane that is the top-level pane in the current layout of the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") "'s named panes. This will typically be some sort of a layout pane." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-top-level-sheet")) :PARAMS ((:I "frame")) :KIND ("Generic Function"))
      (:PAR) "Returns the sheet that is the top-level sheet for the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") ". This is the sheet that has as its descendents all of the panes of "
      (:GROUP (:FONT :FACE :I) "frame") "." (:PAR) "The value returned by " (:CL "frame-panes")
      " will be a descendents of the value of " (:CL "frame-top-level-sheet") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-current-panes")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns a list of those named panes in the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      "'s current layout. If there are no named panes (for example, the " (:CL ":pane")
      " option was used), only the single, top level pane is returned. This function returns objects that reveal CLIM's internal state; do not modify those objects. "
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "get-frame-pane")) :PARAMS ((:I "frame pane-name")) :KIND ("Generic Function"))
      (:PAR) "Returns the named CLIM stream pane in the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      " whose name is " (:GROUP (:FONT :FACE :I) "pane-name") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "find-pane-named")) :PARAMS ((:I "frame pane-name")) :KIND ("Generic Function"))
      (:PAR) "Returns the pane in the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") " whose name is "
      (:GROUP (:FONT :FACE :I) "pane-name") ". This can return any type of pane, not just CLIM stream panes." (:PAR)
      " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-current-layout")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns the current layout for the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      ". The layout is named by a symbol." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf frame-current-layout)")) :PARAMS ((:I "layout frame")) :KIND ("Generic Function"))
      (:PAR) "Sets the layout of the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      " to be the new layout specified by " (:GROUP (:FONT :FACE :I) "new-layout") ". "
      (:GROUP (:FONT :FACE :I) "layout") " must be a symbol that names one of the possible layouts." (:PAR)
      "Changing the layout of the frame must recompute what panes are used for the bindings of the standard stream variables (such as "
      (:CL "*standard-input*")
      "). Some implementations of CLIM may cause the application to \"throw\" all the way back to "
      (:CL "run-frame-top-level")
      " in order to do this. After the new layout has been computed, the contents of each of the panes must be displayed to the degree necessary to ensure that all output is visible."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-all-layouts")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Returns a list of the names of all of the possible layouts for the frame." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "layout-frame")) :PARAMS
       ((:I "frame " (:GROUP (:FONT :FACE :TT) "&optional ") "width height")) :KIND ("Generic Function"))
      (:PAR) "Resizes the frame and lays out the current pane hierarchy using the layout specified by "
      (:CL "frame-current-layout")
      ", according to the layout protocol. The basics of the layout protocols are described in Section "
      (:REF :NAME "layout-protocol")
      ". This function is automatically invoked on a frame when it is adopted, after its pane hierarchy has been generated."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "width") " and " (:GROUP (:FONT :FACE :I) "height")
      " are provided, then this function resizes the frame to the specified size. It is an error to provide just "
      (:GROUP (:FONT :FACE :I) "width") "." (:PAR)
      "If no optional arguments are provided, this function resizes the frame to the preferred size of the top-level pane as determined by the space composition pass of the layout protocol."
      (:PAR)
      "In either case, after the frame is resized, the space allocation pass of the layout protocol is invoked on the top-level pane."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-exit")) :PARAMS ((:I)) :KIND ("Condition")) (:PAR)
      "The condition that is signalled when " (:CL "frame-exit") " is called. This condition will handle the "
      (:CL ":frame") " initarg, which is used to supply the frame that is being exited from." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-exit-frame")) :PARAMS ((:I "condition")) :KIND ("Generic Function")) (:PAR)
      "Returns the frame that is being exited from associated with the " (:CL "frame-exit") " condition." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-exit")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
      "Exits from the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") ". The default method (on "
      (:CL "standard-application-frame") ") signals a " (:CL "frame-exit") " condition, supplying "
      (:GROUP (:FONT :FACE :I) "frame") " as the " (:CL ":frame") " initarg." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "pane-needs-redisplay")) :PARAMS ((:I "pane")) :KIND ("Generic Function")) (:PAR)
      "Returns two values, the first indicating whether the " (:TERM "pane") " " (:GROUP (:FONT :FACE :I) "pane")
      " needs to be redisplayed, and the second indicating whether the pane needs to be cleared before being redisplayed. The first value is "
      (:TERM "true") " when the pane is to be redisplayed. The second value is " (:TERM "true")
      " when the pane is to be cleared." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf pane-needs-redisplay)")) :PARAMS ((:I "value pane")) :KIND ("Generic Function"))
      (:PAR) "Indicates that the " (:TERM "pane") " " (:GROUP (:FONT :FACE :I) "pane")
      " should (or should not) be redisplayed the next time the owning frame executes the redisplay part of its command loop."
      (:PAR) "When " (:GROUP (:FONT :FACE :I) "value") " is " (:CL "nil")
      ", the pane will not require redisplay. When " (:GROUP (:FONT :FACE :I) "value") " is " (:CL "t")
      ", the pane will be cleared and redisplayed exactly once. When " (:GROUP (:FONT :FACE :I) "value") " is "
      (:CL ":command-loop")
      ", the pane will be cleared and redisplayed in each successive pass through the command loop. When "
      (:GROUP (:FONT :FACE :I) "value") " is " (:CL ":no-clear")
      ", the pane will be redisplayed exactly once without clearing it." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "redisplay-frame-pane")) :PARAMS
       ((:I "frame pane " (:GROUP (:FONT :FACE :TT) "&key ") "force-p")) :KIND ("Generic Function"))
      (:PAR) "Causes the pane " (:GROUP (:FONT :FACE :I) "pane") " within the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") " to be redisplayed immediately. " (:GROUP (:FONT :FACE :I) "pane")
      " is either a pane or the name of a named pane. When the boolean " (:GROUP (:FONT :FACE :I) "force-p") " is "
      (:TERM "true") ", the maximum level of redisplay is forced (that is, the pane is displayed \"from scratch\")."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "redisplay-frame-panes")) :PARAMS
       ((:I "frame " (:GROUP (:FONT :FACE :TT) "&key ") "force-p")) :KIND ("Generic Function"))
      (:PAR) (:CL "redisplay-frame-panes") " causes all of the panes in the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") " to be redisplayed immediately by calling " (:CL "redisplay-frame-pane")
      " on each of the panes in " (:GROUP (:FONT :FACE :I) "frame")
      " that are visible in the current layout. When the boolean " (:GROUP (:FONT :FACE :I) "force-p") " is "
      (:TERM "true") ", the maximum level of redisplay is forced (that is, the pane is displayed \"from scratch\")."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "frame-replay")) :PARAMS
       ((:I "frame stream " (:GROUP (:FONT :FACE :TT) "&optional ") "region")) :KIND ("Generic Function"))
      (:PAR) "Replays the contents of " (:GROUP (:FONT :FACE :I) "stream") " in the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") " within the region specified by the region "
      (:GROUP (:FONT :FACE :I) "region") ", which defaults to viewport of " (:GROUP (:FONT :FACE :I) "stream") "."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "notify-user")) :PARAMS
       ((:I "frame message  " (:GROUP (:FONT :FACE :TT) "&key ")
         "associated-window title documentation  exit-boxes name style text-style"))
       :KIND ("Generic Function"))
      (:PAR) "Notifies the user of some event on behalf of the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      ". " (:GROUP (:FONT :FACE :I) "message")
      " is a message string. This function provides a look and feel independent way for applications to communicate messages to the user."
      (:PAR) (:GROUP (:FONT :FACE :I) "associated-window")
      " is the window with which the notification will be associated, as it is for " (:CL "menu-choose") ". "
      (:GROUP (:FONT :FACE :I) "title") " is a title string to include in the notification. "
      (:GROUP (:FONT :FACE :I) "text-style") " is the text style in which to display the notification. "
      (:GROUP (:FONT :FACE :I) "exit-boxes") " is as for " (:GROUP (:FONT :FACE :I) "accepting-values")
      "; it indicates what sort of exit boxes should appear in the notification. " (:GROUP (:FONT :FACE :I) "style")
      " is the style in which to display the notification, and is implementation-dependent." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-properties")) :PARAMS ((:I "frame property")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf frame-properties)")) :PARAMS ((:I "value frame property")) :KIND
       ("Generic Function"))
      (:PAR)
      "Frame properties can be used to associate frame specific data with frames without adding additional slots to the frame's class. CLIM may use frame properties internally to store information for its own purposes."
      (:PAR) " ")
     (:SECTION :TITLE ("28.3.1 " "Interface with Presentation Types") :KIND :SUBSECTION :NAME (1 6 4 10) (:PAR)
      "This section describes the functions that connect application frames to the presentation type system. All classes that inherit from "
      (:CL "application-frame") " must inherit or implement methods for all of these functions." (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-maintain-presentation-histories")) :PARAMS ((:I "frame")) :KIND
        ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
       " maintains histories for its presentations, otherwise returns " (:TERM "false") ". The default method (on "
       (:CL "standard-application-frame") ") returns " (:TERM "true")
       " if and only if the frame has at least one interactor pane." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-find-innermost-applicable-presentation")) :PARAMS
        ((:I "frame input-context stream x y " (:GROUP (:FONT :FACE :TT) "&key ") "event")) :KIND ("Generic Function"))
       (:PAR) "Locates and returns the innermost applicable presentation on the window "
       (:GROUP (:FONT :FACE :I) "stream") " whose sensitivity region contains the point " (:MATH "(x,y)")
       ", on behalf of the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") " in the input context "
       (:GROUP (:FONT :FACE :I) "input-context") ". " (:GROUP (:FONT :FACE :I) "event") " defaults to " (:CL "nil")
       ", and is as for " (:GROUP "find-innermost-applicable-presentation") (:PAR) "The default method (on "
       (:CL "standard-application-frame") ") will simply call " (:CL "find-innermost-applicable-presentation") "."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-input-context-button-press-handler")) :PARAMS
        ((:I "frame stream button-press-event")) :KIND ("Generic Function"))
       (:PAR) "This function is responsible for handling user pointer events on behalf of the " (:TERM "frame") " "
       (:GROUP (:FONT :FACE :I) "frame") " in the input context " (:CL "*input-context*") ". "
       (:GROUP (:FONT :FACE :I) "stream") " is the window on which " (:GROUP (:FONT :FACE :I) "button-press-event")
       " took place." (:PAR) "The default implementation (on " (:CL "standard-application-frame")
       ") unhighlights any highlighted presentations, finds the applicable presentation by calling "
       (:CL "frame-find-innermost-applicable-presentation-at-position") ", and then calls "
       (:CL "throw-highlighted-presentation")
       " to execute the translator on that presentation that corresponds to the user's gesture." (:PAR) "If "
       (:CL "frame-input-context-button-press-handler")
       " is called when the pointer is not over any applicable presentation, " (:CL "throw-highlighted-presentation")
       " must be called with a presentation of " (:CL "*null-presentation*") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-document-highlighted-presentation")) :PARAMS
        ((:I "frame presentation input-context window x y stream")) :KIND ("Generic Function"))
       (:PAR) "This function is responsible for producing pointer documentation on behalf of the " (:TERM "frame") " "
       (:GROUP (:FONT :FACE :I) "frame") " in the input context " (:GROUP (:FONT :FACE :I) "input-context")
       " on the window " (:GROUP (:FONT :FACE :I) "window") " at the point " (:MATH "(x,y)")
       ". The documentation is displayed on the " (:TERM "stream") " " (:GROUP (:FONT :FACE :I) "stream") "." (:PAR)
       "The default method (on " (:CL "standard-application-frame")
       ") should produce documentation that corresponds to calling " (:CL "document-presentation-translator")
       " on all of the applicable translators in the input context " (:GROUP (:FONT :FACE :I) "input-context") ". "
       (:GROUP (:FONT :FACE :I) "presentation") ", " (:GROUP (:FONT :FACE :I) "window") ", "
       (:GROUP (:FONT :FACE :I) "x") ", " (:GROUP (:FONT :FACE :I) "y") ", and " (:GROUP (:FONT :FACE :I) "stream")
       " are as for " (:CL "document-presentation-translator") "." (:PAR)
       "Typically pointer documentation will consist of a brief description of each translator that is applicable to the specified presentation in the specified input context given the current modifier state for the window. For example, the following documentation might be produced when the pointer is pointing to a Lisp expression when the input context is "
       (:CL "form") ":" (:PAR)
       (:PRE "
Left: '(1 2 3); Middle: (DESCRIBE '(1 2 3)); Right: Menu
")
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-drag-and-drop-feedback")) :PARAMS
        ((:I "frame presentation stream  initial-x initial-y new-x new-y state")) :KIND ("Generic Function"))
       (:PAR) "The default feedback function for translators defined by " (:CL "define-drag-and-drop-translator")
       ", which provides visual feedback during the dragging phase of such translators on behalf of the "
       (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") ". " (:GROUP (:FONT :FACE :I) "presentation")
       " is the presentation being dragged on the stream " (:GROUP (:FONT :FACE :I) "stream")
       ". The pointing device was initially at the position specified by " (:GROUP (:FONT :FACE :I) "initial-x")
       " and " (:GROUP (:FONT :FACE :I) "initial-y") ", and is at the position specified by "
       (:GROUP (:FONT :FACE :I) "new-x") " and " (:GROUP (:FONT :FACE :I) "new-y") " when "
       (:CL "frame-drag-and-drop-feedback")
       " is invoked. (Both positions are supplied for \"rubber-banding\", if that is the sort of desired feedback.) "
       (:GROUP (:FONT :FACE :I) "state") " will be either " (:CL ":highlight")
       ", meaning that the feedback should be drawn, or " (:CL ":unhighlight")
       ", meaning that the feedback should be erased." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-drag-and-drop-highlighting")) :PARAMS ((:I "frame presentation stream state"))
        :KIND ("Generic Function"))
       (:PAR) "The default highlighting function for translators defined by " (:CL "define-drag-and-drop-translator")
       ", which is invoked when a \"to object\" should be highlighted during the dragging phase of such translators on behalf of the "
       (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") ". " (:GROUP (:FONT :FACE :I) "presentation")
       " is the presentation over which the pointing device is located on the stream "
       (:GROUP (:FONT :FACE :I) "stream") ". " (:GROUP (:FONT :FACE :I) "state") " will be either " (:CL ":highlight")
       ", meaning that the highlighting for the presentation should be drawn, or " (:CL ":unhighlight")
       ", meaning that the highlighting should be erased." (:PAR) " ")))
    (:SECTION :TITLE ("28.4 " "The Generic Command Loop") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "The default application command loop provided by CLIM performs the following steps:" (:PAR)
     (:OL (:LI "Prompts the user for input." (:PAR))
      (:LI
       "Reads a command. Each application frame has a command table that contains those commands that the author of the application wishes to allow the user to invoke at a given time. Since commands may be read in any number of ways, the generic command loop enforces no particular interface style."
       (:PAR))
      (:LI
       "Executes the command. The definition of each command may refer to (and update) the state variables of the frame, to which "
       (:CL "*application-frame*") " will be bound." (:PAR))
      (:LI
       "Runs the display function for each pane in the frame as necessary. The display function may refer to the frame's state variables. Display functions are usually written by the application writer, although certain display functions are supplied by CLIM itself. Note that an application frame is free to have no panes. "))
     (:PAR) " " (:GROUP (:FONT :FACE :B) "Major issue: ") " "
     (:GROUP (:FONT :FACE :SL)
      "RWK has a reasonable proposal for breaking down command loops into their component pieces. It should be integrated here. --- SWM")
     (:PAR) "All classes that inherit from " (:CL "application-frame")
     " must inherit or implement methods for all of the following functions." (:PAR) " "
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "run-frame-top-level")) :PARAMS
       ((:I "frame " (:GROUP (:FONT :FACE :TT) "&key ") (:GROUP (:FONT :FACE :TT) "&allow-other-keys "))) :KIND
       ("Generic Function"))
      (:PAR) "Runs the top-level function for the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame")
      ". The default method on " (:CL "application-frame")
      " simply invokes the top-level function for the frame (which defaults to " (:CL "default-frame-top-level") ")."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "run-frame-top-level")) :PARAMS
       ((:I "(frame " (:CL "application-frame") ") " (:GROUP (:FONT :FACE :TT) "&key "))) :KIND (":Around Method"))
      (:PAR) "The " (:CL ":around") " method of " (:CL "run-frame-top-level") " on the " (:CL "application-frame")
      " class is responsible for establish the initial dynamic bindings for the application, including (but not limited to) binding "
      (:CL "*application-frame*") " to " (:GROUP (:FONT :FACE :I) "frame") ", binding " (:CL "*input-context*") " to "
      (:CL "nil") ", resetting the delimiter and activation gestures, and binding " (:CL "*input-wait-test*") ", "
      (:CL "*input-wait-handler*") ", and " (:CL "*pointer-button-press-handler*") " to " (:CL "nil") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "default-frame-top-level")) :PARAMS
       ((:I "frame " (:GROUP (:FONT :FACE :TT) "&key ")
         "command-parser command-unparser  partial-command-parser  prompt"))
       :KIND ("Generic Function"))
      (:PAR)
      "The default top-level function for application frames. This function implements a \"read-eval-print\" loop that displays a prompt, calls "
      (:CL "read-frame-command") ", then calls " (:CL "execute-frame-command")
      ", and finally redisplays all of the panes that need to be redisplayed." (:PAR) (:CL "default-frame-top-level")
      " will also establish a simple restart for " (:CL "abort")
      ", and bind the standard stream variables as follows. " (:CL "*standard-input*")
      " will be bound to the value returned by " (:CL "frame-standard-input") ". " (:CL "*standard-output*")
      " will be bound to the value returned by " (:CL "frame-standard-output") ". " (:CL "*query-io*")
      " will be bound to the value returned by " (:CL "frame-query-io") ". " (:CL "*error-output*")
      " will be bound to the value returned by " (:CL "frame-error-output") ". It is unspecified what "
      (:CL "*terminal-io*") ", " (:CL "*debug-io*") ", and " (:CL "*trace-output*") " will be bound to." (:PAR)
      (:GROUP (:FONT :FACE :I) "prompt") " is either a string to use as the prompt (defaulting to "
      (:CL "\"Command: \"") "), or a function of two arguments, a stream and the frame." (:PAR)
      (:GROUP (:FONT :FACE :I) "command-parser") ", " (:GROUP (:FONT :FACE :I) "command-unparser") ", and "
      (:GROUP (:FONT :FACE :I) "partial-command-parser") " are the same as for " (:CL "read-command") ". "
      (:GROUP (:FONT :FACE :I) "command-parser") " defaults to " (:CL "command-line-command-parser")
      " if there is an interactor, otherwise it defaults to " (:CL "menu-only-command-parser") ". "
      (:GROUP (:FONT :FACE :I) "command-unparser") " defaults to " (:CL "command-line-command-unparser") ". "
      (:GROUP (:FONT :FACE :I) "partial-command-parser") " defaults to "
      (:CL "command-line-read-remaining-arguments-for-partial-command")
      " if there is an interactor, otherwise it defaults to "
      (:CL "menu-only-read-remaining-arguments-for-partial-command") ". " (:CL "default-frame-top-level") " binds "
      (:CL "*command-parser*") ", " (:CL "*command-unparser*") ", and " (:CL "*partial-command-parser*")
      " to the values of " (:GROUP (:FONT :FACE :I) "command-parser") ", " (:GROUP (:FONT :FACE :I) "command-unparser")
      ", and " (:GROUP (:FONT :FACE :I) "partial-command-parser") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "read-frame-command")) :PARAMS
       ((:I "frame " (:GROUP (:FONT :FACE :TT) "&key ") "(stream " (:CL "*standard-input*") ")")) :KIND
       ("Generic Function"))
      (:PAR) "Reads a command from the stream " (:GROUP (:FONT :FACE :I) "stream") " on behalf of the " (:TERM "frame")
      " " (:GROUP (:FONT :FACE :I) "frame") ". The returned value is a command object." (:PAR)
      "The default method (on " (:CL "standard-application-frame") ") for " (:CL "read-frame-command") " simply calls "
      (:CL "read-command") ", supplying " (:GROUP (:FONT :FACE :I) "frame")
      "'s current command table as the command table." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "execute-frame-command")) :PARAMS ((:I "frame command")) :KIND ("Generic Function"))
      (:PAR) "Executes the command " (:GROUP (:FONT :FACE :I) "command") " on behalf of the " (:TERM "frame") " "
      (:GROUP (:FONT :FACE :I) "frame") ". " (:GROUP (:FONT :FACE :I) "command")
      " is a command object, that is, a cons of a command name and a list of the command's arguments." (:PAR)
      "The default method (on " (:CL "standard-application-frame") ") for " (:CL "execute-frame-command")
      " simply applies the " (:CL "command-name") " of " (:GROUP (:FONT :FACE :I) "command") " to "
      (:CL "command-arguments") " of " (:GROUP (:FONT :FACE :I) "command") "." (:PAR) "If process that "
      (:CL "execute-frame-command") " is invoked in is not the same process the one " (:GROUP (:FONT :FACE :I) "frame")
      " is running in, CLIM may need to make special provisions in order for the command to be correctly executed, since as queueing up a special \"command event\" in "
      (:GROUP (:FONT :FACE :I) "frame")
      "'s event queue. The exact details of how this should work is left unspecified." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "command-enabled")) :PARAMS ((:I "command-name frame")) :KIND ("Generic Function"))
      (:PAR) "Returns " (:TERM "true") " if the command named by " (:GROUP (:FONT :FACE :I) "command-name")
      " is presently enabled in the " (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") ", otherwise returns "
      (:TERM "false") ". If " (:GROUP (:FONT :FACE :I) "command-name")
      " is not accessible to the command table being used by " (:GROUP (:FONT :FACE :I) "frame") ", "
      (:CL "command-enabled") " returns " (:TERM "false") "." (:PAR)
      "Whether or not a particular command is currently enabled is stored independently for each instance of an application frame; this status can vary between frames that share a single command table."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf command-enabled)")) :PARAMS ((:I "enabled command-name frame")) :KIND
       ("Generic Function"))
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "enabled") " is " (:TERM "false")
      ", this disables the use of the command named by " (:GROUP (:FONT :FACE :I) "command-name") " while in the "
      (:TERM "frame") " " (:GROUP (:FONT :FACE :I) "frame") ". Otherwise if " (:GROUP (:FONT :FACE :I) "enabled")
      " is " (:TERM "true") ", the use of the command is enabled. After the command has been enabled (or disabled), "
      (:CL "note-command-enabled") " (or " (:CL "note-command-disabled")
      ") is invoked on the frame manager and the frame in order to update the appearance of the interface, for example, \"graying out\" a disabled command."
      (:PAR) "If " (:GROUP (:FONT :FACE :I) "command-name") " is not accessible to the command table being used by "
      (:GROUP (:FONT :FACE :I) "frame") ", using " (:CL "setf") " on " (:CL "command-enabled") " does nothing." (:PAR)
      " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "display-command-menu")) :PARAMS
       ((:I "frame stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "command-table initial-spacing row-wise  max-width max-height n-rows n-columns  (cell-align-x " (:CL ":left")
         ") (cell-align-y " (:CL ":top") ")"))
       :KIND ("Generic Function"))
      (:PAR) "Displays the menu associated with the specified command table on " (:GROUP (:FONT :FACE :I) "stream")
      " by calling " (:CL "display-command-table-menu") ". If " (:GROUP (:FONT :FACE :I) "command-table")
      " is not supplied, it defaults to " (:CL "(frame-command-table " (:GROUP (:FONT :FACE :I) "stream") ")")
      ". This function is generally used as the display function for panes that contain command menus." (:PAR)
      (:GROUP (:FONT :FACE :I) "initial-spacing") ", " (:GROUP (:FONT :FACE :I) "max-width") ", "
      (:GROUP (:FONT :FACE :I) "max-height") ", " (:GROUP (:FONT :FACE :I) "n-rows") ", "
      (:GROUP (:FONT :FACE :I) "n-columns") ", " (:GROUP (:FONT :FACE :I) "row-wise") ", "
      (:GROUP (:FONT :FACE :I) "cell-align-x") ", and " (:GROUP (:FONT :FACE :I) "cell-align-y") " are as for "
      (:CL "formatting-item-list") "." (:PAR) " "))
    (:SECTION :TITLE ("28.5 " "Frame Managers") :KIND :SECTION :NAME (6 4 10) (:PAR) "Frames may be "
     (:CONCEPT "adopted")
     " by a frame manager, which involves invoking a protocol for generating the pane hierarchy of the frame. This protocol provides for selecting pane types for abstract gadget panes based on the style requirements imposed by the frame manager. That is, the frame manager is responsible for the \"look and feel\" of a frame."
     (:PAR) "After a frame is adopted it can be in any of the three following states: " (:CONCEPT "enabled") ", "
     (:CONCEPT "disabled") ", or " (:CONCEPT "shrunk")
     ". An enabled frame is visible unless it is occluded by other frames or the user is browsing outside of the portion of the frame manager's space that the frame occupies. A shrunken frame provides a cue or handle for the frame, but generally will not show the entire contents of the frame. For example, the frame may be iconified or an item for the frame may be placed in a special suspended frame menu. A disabled frame is not visible, nor is there any user accessible handle for enabling the frame."
     (:PAR) "Frames may also be " (:CONCEPT "disowned")
     ", which involves releasing the frame's panes as well as all associated foreign resources." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-manager")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a frame manager. If you want to create a new class that behaves like a frame manager, it should be a subclass of "
      (:CL "frame-manager") ". All instantiable subclasses of " (:CL "frame-manager")
      " must obey the frame manager protocol. " (:PAR)
      "There are no advertised standard frame manager classes. Each port will implement one or more frame managers that correspond to the look and feel for the port."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "frame-mananger-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "frame manager")
      ", otherwise returns " (:TERM "false") "." (:PAR) " ")
     (:SECTION :TITLE ("28.5.1 " "Finding Frame Managers") :KIND :SUBSECTION :NAME (3 6 4 10) (:PAR)
      "Most frames need only deal directly with frame managers to the extent that they need to find a frame manager into which they can insert themselves. Since frames will usually be invoked by some user action that is handled by some frame manager, finding an appropriate frame manager is usually straightforward."
      (:PAR)
      "Some frames will support the embedding of other frames within themselves. Such frames would not only use frames but also act as frame managers, so that other frames could insert frames. In this case, the embedded frames are mostly unaware that they are nested within other frames, but only know that they are controlled by a particular frame manager."
      (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "How does one write a frame that supports an embedded frame, such as an editor frame within a documentation-writing frame? --- SWM")
      (:PAR) "The " (:CL "find-frame-manager")
      " function provides a flexible means for locating an frame manager to adopt an application's frames into. There are a variety of ways that the user or the application can influence where an application's frame is adopted."
      (:PAR) "An application can establish an application default frame manager using " (:CL "with-frame-manager")
      ". A frame's top-level loop automatically establishes the frame's frame manager." (:PAR)
      "The programmer or user can influence what frame manager is found by setting " (:CL "*default-frame-manager*")
      " or " (:CL "*default-server-path*") "." (:PAR)
      "Each frame manager is associated with one specific port. However, a single port may have multiple frame managers managing various frames associated with the port."
      (:PAR) " "
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "find-frame-manager")) :PARAMS
        ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "options " (:GROUP (:FONT :FACE :TT) "&key ") "port "
          (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
        :KIND ("Function"))
       (:PAR) "Finds an appropriate frame manager that conforms to the options, including the "
       (:GROUP (:FONT :FACE :I) "port")
       " argument. Furthermore, CLIM applications may set up dynamic contexts that affect what "
       (:CL "find-frame-manager") " will return." (:PAR) (:GROUP (:FONT :FACE :I) "port")
       " defaults to the value returned by " (:CL "find-port") " applied to the remaining options." (:PAR)
       "A frame manager is found using the following rules in the order listed:" (:PAR)
       (:OL
        (:LI "If a current frame manager has been established via an invocation of " (:CL "with-frame-manager")
         ", as is the case within a frame's top-level, and that frame manager conforms to the options, it is returned. The exact definition of \"conforming to the options\" varies from one port to another, but it may include such things as matching the console number, color or resolution properties, and so forth. If the options are empty, then any frame manager will conform."
         (:PAR))
        (:LI "If " (:CL "*default-frame-manager*")
         " is bound to a currently active frame manager and it conforms to the options, it is returned." (:PAR))
        (:LI "If " (:GROUP (:FONT :FACE :I) "port") " is " (:CL "nil")
         ", a port is found and an appropriate frame manager is constructed using " (:CL "*default-server-path*")
         ". "))
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "*default-frame-manager*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
       "This variable provides a convenient point for allowing a programmer or user to override what frame manager type would normally be selected. Most users will not set this variable since they can set "
       (:CL "*default-server-path*")
       " to indicate which host window system they want to use and are willing to use whatever frame manager is the default for the particular port. However, some users may want to use a frame manager that isn't the typical frame manager. For example, a user may want to use both an OpenLook frame manager and a Motif frame manager on a single port."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-frame-manager")) :PARAMS
        ((:I "(frame-manager) " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND ("Macro"))
       (:PAR) "Generates a dynamic context that causes all calls to " (:CL "find-frame-manager") " to return "
       (:GROUP (:FONT :FACE :I) "frame-manager") " if the " (:GROUP (:FONT :FACE :I) "where")
       " argument passed to it conforms to " (:GROUP (:FONT :FACE :I) "frame-manager") ". Nested calls to "
       (:CL "with-frame-manager") " will shadow outer contexts. " (:GROUP (:FONT :FACE :I) "body")
       " may have zero or more declarations as its first forms." (:PAR) " "))
     (:SECTION :TITLE ("28.5.2 " "Frame Manager Operations") :KIND :SUBSECTION :NAME (3 6 4 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "frame-manager")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
       "Returns the current frame manager of " (:GROUP (:FONT :FACE :I) "frame")
       " if it is adopted, otherwise returns " (:CL "nil") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf frame-manager)")) :PARAMS ((:I "frame-manager frame")) :KIND
        ("Generic Function"))
       (:PAR) "Changes the frame manager of " (:GROUP (:FONT :FACE :I) "frame") " to "
       (:GROUP (:FONT :FACE :I) "frame-manager")
       ". In effect, the frame is disowned from its old frame manager and is adopted into the new frame manager. Transferring a frame preserves its "
       (:CL "frame-state")
       ", for example, if the frame was previously enabled it will be enabled in the new frame manager." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-manager-frames")) :PARAMS ((:I "frame-manager")) :KIND ("Generic Function"))
       (:PAR) "Returns a list of all of the frames being managed by " (:GROUP (:FONT :FACE :I) "frame-manager")
       ". This function returns objects that reveal CLIM's internal state; do not modify those objects. " (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "adopt-frame")) :PARAMS ((:I "frame-manager frame")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "disown-frame")) :PARAMS ((:I "frame-manager frame")) :KIND ("Generic Function")) (:PAR)
       "These functions insert or remove a frame from a frame manager's control. These functions allow a frame manager to allocate and deallocate resources associated with a frame. For example, removing a frame from a frame manager that is talking to a remote server allows it to release all remote resources used by the frame."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "port")) :PARAMS ((:I "(frame " (:CL "standard-application-frame") ")")) :KIND
        ("Method"))
       (:PAR) "If " (:GROUP (:FONT :FACE :I) "frame")
       " has been adopted by a frame manager, this returns the port with which " (:GROUP (:FONT :FACE :I) "frame")
       " is associated. Otherwise it returns " (:CL "nil") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "port")) :PARAMS ((:I "(frame-manager " (:CL "standard-frame-manager") ")")) :KIND
        ("Method"))
       (:PAR) "Returns the port with which " (:GROUP (:FONT :FACE :I) "frame-manager") " is associated." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "frame-state")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
       "Returns one of " (:CL ":disowned") ", " (:CL ":enabled") ", " (:CL ":disabled") ", or " (:CL ":shrunk")
       ", indicating the current state of frame." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "enable-frame")) :PARAMS ((:I "frame")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "disable-frame")) :PARAMS ((:I "frame")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "shrink-frame")) :PARAMS ((:I "frame")) :KIND ("Generic Function")) (:PAR)
       "These functions force a frame into the enabled, disabled, or shrunken (iconified) states. A frame in the enabled state may be visible if it is not occluded or placed out of the user's focus of attention. A disabled frame is never visible. A shrunk frame is accessible to the user for re-enabling, but may be represented in some abbreviated form, such as an icon or a menu item."
       (:PAR)
       "These functions call the notification functions describe below to notify the frame manager that the state of the frame changed."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "note-frame-enabled")) :PARAMS ((:I "frame-manager frame")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-frame-disabled")) :PARAMS ((:I "frame-manager frame")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-frame-iconified")) :PARAMS ((:I "frame-manager frame")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-frame-deiconified")) :PARAMS ((:I "frame-manager frame")) :KIND
        ("Generic Function"))
       (:PAR) "Notifies the frame manager " (:GROUP (:FONT :FACE :I) "frame-manager") " that the frame "
       (:GROUP (:FONT :FACE :I) "frame")
       " has changed its state to the enabled, disabled, iconified, or deiconified state, respectively." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "note-command-enabled")) :PARAMS ((:I "frame-manager frame command-name")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "note-command-disabled")) :PARAMS ((:I "frame-manager frame command-name")) :KIND
        ("Generic Function"))
       (:PAR) "Notifies the frame manager " (:GROUP (:FONT :FACE :I) "frame-manager") " that the command named by "
       (:GROUP (:FONT :FACE :I) "command-name") " has been enabled or disabled (respectively) in the frame "
       (:GROUP (:FONT :FACE :I) "frame")
       ". The frame manager can update the appearance of the user interface as appropriate, for instance, by \"graying out\" a newly disabled command from a command menu or menu bar."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "frame-manager-notify-user")) :PARAMS
        ((:I "framem message-string  " (:GROUP (:FONT :FACE :TT) "&key ")
          "frame associated-window title documentation  exit-boxes name style text-style"))
        :KIND ("Generic Function"))
       (:PAR) "This is the generic function used by " (:CL "notify-user") ". The arguments are as for "
       (:CL "notify-user") ". The default method on " (:CL "standard-frame-manager")
       " will display a dialog or an alert box that contains the message and has exit boxes that allow the user to dismiss the notification."
       (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "generate-panes")) :PARAMS ((:I "frame-manager frame")) :KIND ("Generic Function"))
       (:PAR) "This function is invoked by a standard method of " (:CL "adopt-frame") ". "
       (:CL "define-application-frame") " automatically supplies a " (:CL "generate-panes") " method if either the "
       (:CL ":pane") " or " (:CL ":panes") " option is used in the " (:CL "define-application-frame") "." (:PAR)
       "It is the responsibility of this method to call " (:CL "setf") " on " (:CL "frame-panes")
       " on the frame in order to set the current" (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "find-pane-for-frame")) :PARAMS ((:I "frame-manager frame")) :KIND ("Generic Function"))
       (:PAR) "This function is invoked by a standard method of " (:CL "adopt-frame")
       ". It must return the root pane of the frame's layout. It is the responsibility of the frame implementor to provide a method that constructs the frame's top-level pane. "
       (:CL "define-application-frame") " automatically supplies a a method for this function if either the "
       (:CL ":pane") " or " (:CL ":panes") " option is used in the " (:CL "define-application-frame") "." (:PAR) " "))
     (:SECTION :TITLE ("28.5.3 " "Frame Manager Settings") :KIND :SUBSECTION :NAME (3 6 4 10) (:PAR)
      "CLIM provides frame manager settings in order to allow a frame to communicate information to its frame manager."
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf client-setting)")) :PARAMS ((:I "value frame setting")) :KIND
        ("Generic Function"))
       (:PAR) "Sets the setting " (:GROUP (:FONT :FACE :I) "setting") " to " (:GROUP (:FONT :FACE :I) "value")
       " for the frame " (:GROUP (:FONT :FACE :I) "frame") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "reset-frame")) :PARAMS
        ((:I "frame " (:GROUP (:FONT :FACE :TT) "&rest ") "client-settings")) :KIND ("Generic Function"))
       (:PAR) "Resets the settings of frame. " (:CL "reset-frame")
       " invokes a protocol that forces the frame manager to notice that the settings have changed, where the setf generic function just updates the frame data. For example, the width and height can be reset to force resizing of the window."
       (:PAR) "  ")))
    (:SECTION :TITLE ("28.6 " "Examples of Applications") :KIND :SECTION :NAME (6 4 10) (:PAR)
     "The following is an example that outlines a simple 4-by-4 sliding piece puzzle:" (:PAR)
     (:PRE "
(define-application-frame puzzle ()
    ((puzzle-array :initform (make-array '(4 4))))
  (:menu-bar t)
  (:panes
    (display
      (outlining ()
        (make-pane 'application-pane
                   :text-cursor nil
                   :width :compute
                   :height :compute
                   :incremental-redisplay T
                   :display-function 'draw-puzzle))))
  (:layouts
    (:default display)))

(defmethod run-frame-top-level :before ((puzzle puzzle))
  ;; Initialize the puzzle
  ...)

(define-presentation-type puzzle-cell ()
  :inherit-from '(integer 1 15))

(defmethod draw-puzzle ((puzzle puzzle) stream &key max-width max-height)
  (declare (ignore max-width max-height))
  ;; Draw the puzzle, presenting each cell as a PUZZLE-CELL
  ...)

(define-puzzle-command com-move-cell
    ((cell 'puzzle-cell :gesture :select))
  ;; Move the selected cell to the adjacent open cell,
  ;; if there is one
  ...)

(define-puzzle-command (com-scramble :menu t)
    ()
  ;; Scramble the pieces of the puzzle
  ...)

(define-puzzle-command (com-exit-puzzle :menu \"Exit\")
    ()
  (frame-exit *application-frame*))

(defun puzzle ()
  (let ((puzzle 
          (make-application-frame 'puzzle 
            :width 80 :height 80)))
    (run-frame-top-level puzzle)))
")
     (:PAR) "The following is an application frame with two layouts:" (:PAR)
     (:PRE "
(define-application-frame test-frame () ()
  (:panes
    (a (horizontally ()
         (make-pane 'push-button :label \"Press me\")
         (make-pane 'push-button :label \"Squeeze me\")))
    (b toggle-button)
    (c slider)
    (d text-field)
    (e :interactor-pane
       :width 300 :max-width +fill+
       :height 300 :max-height +fill+))
  (:layouts
    (default 
      (vertically ()
        a b c (scrolling () e)))
    (other
      (vertically ()
        a (scrolling () e) b d))))

(define-test-frame-command (com-switch :name t :menu t)
    ()
  (setf (frame-current-layout *application-frame*)
        (ecase (frame-current-layout *application-frame*)
          (default other)
          (other default))))

(let ((test-frame 
        (make-application-frame 'test-frame)))
  (run-frame-top-level test-frame))
")
     (:PAR)))
   " "
   (:SECTION :TITLE ("29 " "Panes") :KIND :CHAPTER :NAME (4 10) " " (:LABEL :NAME "panes") (:PAR)
    (:SECTION :TITLE ("29.1 " "Overview of Panes") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "CLIM panes are similar to the gadgets or widgets of other toolkits. They can be used by application programmers to compose the top-level user interface of their applications, as well as auxiliary components such as menus and dialogs. The application programmer provides an abstract specification of the pane hierarchy, which CLIM uses in conjunction with user preferences and other factors to select a specific \"look and feel\" for the application. In many environments a CLIM application can use the facilities of the host window system toolkit via a set of "
     (:CONCEPT "adaptive panes")
     ", allowing a portable CLIM application to take on the look and feel of a native application user interface."
     (:PAR)
     "Panes are rectangular objects that are implemented as special sheet classes. An application will typically construct a tree of panes that divide up the screen space allocated to the application frame. The various CLIM pane types can be characterized by whether they have children panes or not: panes that can have other panes as children are called "
     (:CONCEPT "composite panes") ", and those that don't are called " (:CONCEPT "leaf panes")
     ". Composite panes are used to provide a mechanism for spatially organizing (\"laying out\") other panes. Leaf panes implement gadgets that have some appearance and react to user input by invoking application code. Another kind of leaf pane provides an area of the application's screen real estate that can be used by the application to present application specific information. CLIM provides a number of these "
     (:CONCEPT "application pane")
     " types that allow the application to use CLIM's graphics and extended stream facilities." (:PAR)
     (:CONCEPT "Abstract panes")
     " are panes that are defined only in terms of their programmer interface, or behavior. The protocol for an abstract pane (that is, the specified set of initargs, accessors, and callbacks) is designed to specify the pane in terms of its overall purpose, rather then in terms of its specific appearance or particular interactive details. The purpose of this abstract definition is to allow multiple implementations of the abstract pane, each defining its own specific look and feel. CLIM can then select the appropriate pane implementation based on factors outside the control of the application, such as user preferences or the look and feel of the host operating environment. A subset of the abstract panes, the "
     (:TERM "adaptive panes") ", have been defined to integrate well across all CLIM operating platforms." (:PAR)
     "CLIM provides a general mechanism for automatically selecting the particular implementation of an abstract pane selected by an application based on the current frame manager. The application programmer can override the selection mechanism by using the name of a specific pane implementation in place of the abstract pane name when specifying the application frame's layout. By convention, the name of the basic, portable implementation of an abstract pane class can be determined by adding the suffix \""
     (:CL "-pane") "\" to the name of the abstract pane class." (:PAR) " ")
    (:SECTION :TITLE ("29.2 " "Basic Pane Construction") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "Applications typically define the hierarchy of panes used in their frames using the " (:CL ":pane") " or "
     (:CL ":panes") " options of " (:CL "define-application-frame")
     ". These options generate the body of methods on functions that are invoked when the frame is being adopted into a particular frame manager, so the frame manager can select the specific implementations of the abstract panes."
     (:PAR) "There are two basic interfaces to constructing a pane: " (:CL "make-pane")
     " of an abstract pane class name, or " (:CL "make-instance")
     " of a \"concrete\" pane class. The former approach is generally preferable, since it results in more portable code. However, in some cases the programmer may wish to instantiate panes of a specific class (such as an "
     (:CL "hbox-pane") " or a " (:CL "vbox-pane") "). In this case, using " (:CL "make-instance")
     " directly circumvents the abstract pane selection mechanism. However, the " (:CL "make-instance")
     " approach requires the application programmer to know the name of the specific pane implementation class that is desired, and so is inherently less portable. By convention, all of the concrete pane class names, including those of the implementations of abstract pane protocol specifications, end in \""
     (:CL "-pane") "\"." (:PAR) "Using " (:CL "make-pane") " instead of " (:CL "make-instance")
     " invokes the \"look and feel\" realization process to select and construct a pane. Normally this process is implemented by the frame manager, but it is possible for other \"realizers\" to implement this process. "
     (:CL "make-pane")
     " is typically invoked using an abstract pane class name, which by convention is a symbol in the CLIM package that doesn't include the \""
     (:CL "-pane")
     "\" suffix. (This naming convention distinguishes the names of the abstract pane protocols from the names of classes that implement them.) Programmers, however, are allowed to pass any pane class name to "
     (:CL "make-pane") ", in which case the frame manager will generally instantiate that specific class." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "pane")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a pane, a subclass of " (:CL "sheet")
      ". A pane is a special kind of sheet that implements the pane protocols, including the layout protocols. If you want to create a new class that behaves like a pane, it should be a subclass of "
      (:CL "pane") ". All instantiable subclasses of " (:CL "pane") " must obey the pane protocol. " (:PAR)
      "All of the subclasses of " (:CL "pane") " are mutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "panep")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "pane") ", otherwise returns "
      (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "basic-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The basic class on which all CLIM panes are built, a subclass of " (:CL "pane")
      ". This class is an abstract class, intended only to be subclassed, not instantiated. " (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-pane")) :PARAMS
       ((:I "abstract-class-name " (:GROUP (:FONT :FACE :TT) "&rest ") "initargs")) :KIND ("Function"))
      (:PAR) "Selects a class that implements the behavior of the abstract pane "
      (:GROUP (:FONT :FACE :I) "abstract-class-name") " and constructs a pane of that class. " (:CL "make-pane")
      " must be used either within the scope of a call to " (:CL "with-look-and-feel-realization") ", or within the "
      (:CL ":pane") " or " (:CL ":panes") " options of a " (:CL "define-application-frame")
      " (which implicitly invokes " (:CL "with-look-and-feel-realization") ")." (:PAR)
      "It is permitted for this function to have lexical scope, and be defined only within the body of "
      (:CL "with-look-and-feel-realization") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-pane-1")) :PARAMS
       ((:I "realizer frame abstract-class-name " (:GROUP (:FONT :FACE :TT) "&rest ") "initargs")) :KIND
       ("Generic Function"))
      (:PAR) "The generic function that is invoked by a call to " (:CL "make-pane")
      ". The object that realizes the pane, " (:GROUP (:FONT :FACE :I) "realizer") ", is established by "
      (:CL "with-look-and-feel-realization") ". Usually, " (:GROUP (:FONT :FACE :I) "realizer")
      " is a frame manager, but it could be another object that implements the pane realization protocol. "
      (:GROUP (:FONT :FACE :I) "frame") " is the frame for which the pane will be created, and "
      (:GROUP (:FONT :FACE :I) "abstract-class-name") " is the type of pane to create." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-look-and-feel-realization")) :PARAMS
       ((:I "(realizer frame) " (:GROUP (:FONT :FACE :TT) "&body ") "forms")) :KIND ("Macro"))
      (:PAR) "Establishes a dynamic context that installs " (:GROUP (:FONT :FACE :I) "realizer")
      " as the object responsible for realizing panes. All calls to " (:CL "make-pane") " within the context of "
      (:CL "with-look-and-feel-realization") " result in " (:CL "make-pane-1") " being invoked on "
      (:GROUP (:FONT :FACE :I) "realizer") ". This macro can be nested dynamically; inner uses shadow outer uses. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) "Typically "
      (:GROUP (:FONT :FACE :I) "realizer") " is a frame manager, but in some cases "
      (:GROUP (:FONT :FACE :I) "realizer")
      " may be some other object. For example, within the implementation of pane that is uses its own subpanes to achieve its functionality, this form might be used with "
      (:GROUP (:FONT :FACE :I) "realizer") " being the pane itself." (:PAR) " ")
     (:SECTION :TITLE ("29.2.1 " "Pane Initialization Options " (:LABEL :NAME "pane-init")) :KIND :SUBSECTION :NAME
      (2 5 4 10) (:PAR) "The following options must be accepted by all pane classes." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL ":foreground")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":background")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "These options specify the default foreground and background inks for a pane. These will normally default from window manager resources. If there are no such resources, the defaults are black and white, respectively."
       (:PAR)
       "Client code should be cautious about passing values for these two options, since the window manager's look and feel or the user's preferences should usually determine these values."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":text-style")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "This option specifies the default text style that should be used for any sort of pane that supports text output. Panes that do not support text output ignore this option."
       (:PAR)
       "Client code should be cautious about passing values for this option, since the window manager's look and feel or the user's preferences should usually determine this value."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":name")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "This option specifies the name of the pane. It defaults to " (:CL "nil") "." (:PAR) " "))
     (:SECTION :TITLE ("29.2.2 " "Pane Properties") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "pane-frame")) :PARAMS ((:I "pane")) :KIND ("Generic Function")) (:PAR)
       "Returns the frame that \"owns\" the pane. " (:CL "pane-frame")
       " can be invoked on any pane in a frame's pane hierarchy, but it can only be invoked on \"active\" panes, that is, those panes that are currently adopted into the frame's pane hierarchy."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "pane-name")) :PARAMS ((:I "pane")) :KIND ("Generic Function")) (:PAR)
       "Returns the name of the pane." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "pane-foreground")) :PARAMS ((:I "pane")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "pane-background")) :PARAMS ((:I "pane")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "pane-text-style")) :PARAMS ((:I "pane")) :KIND ("Generic Function")) (:PAR)
       "Return the default foreground and background inks and the default text style, respectively, for the pane "
       (:GROUP (:FONT :FACE :I) "pane") ". These will be used as the default value for " (:CL "medium-foreground")
       " and " (:CL "medium-background") " when a medium is grafted to the pane." (:PAR) " ")))
    (:SECTION :TITLE ("29.3 " "Composite and Layout Panes") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "This section describes the various composite and layout panes provided by CLIM, and the protocol that the layout panes obey."
     (:PAR)
     "The layout panes describe in this section are all composite panes that are responsible for positioning their children according to various layout rules. Layout panes can be selected in the same way as other panes using "
     (:CL "make-pane") " or " (:CL "make-instance")
     ". For convenience and readability of application pane layouts, many of these panes also provide a macro that expands into a "
     (:CL "make-pane") " form, passing a list of the panes created in the body of the macro as the " (:CL ":contents")
     " argument (described below). For example, you can express a layout of a vertical column of two label panes either as:"
     (:PAR)
     (:PRE "
(make-instance 'vbox-pane
  :contents (list (make-instance 'label-pane :text \"One\")
                  (make-instance 'label-pane :text \"Two\")))
")
     (:PAR) "or as:" (:PAR)
     (:PRE "
(vertically ()
  (make-instance 'label-pane :text \"One\")
  (make-instance 'label-pane :text \"Two\"))
")
     (:PAR) " "
     (:SECTION :TITLE ("29.3.1 " "Layout Pane Options") :KIND :SUBSECTION :NAME (4 5 4 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL ":contents")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "All of the layout pane classes accept the " (:CL ":contents")
       " options, which is used to specify the child panes to be laid out." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":width")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":max-width")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":min-width")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":height")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":max-height")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":min-height")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "These options control the space requirement paramaters for laying out the pane. The " (:CL ":width") " and "
       (:CL ":height") " options specify the preferred horizontal and vertical sizes. The " (:CL ":max-width") " and "
       (:CL ":max-height")
       " options specify the maximum amount of space that may be consumed by the pane, and give CLIM's pane layout engine permission to grow the pane beyond the preferred size. The "
       (:CL ":min-width") " and " (:CL ":min-height")
       " options specify the minimum amount of space that may be consumed by the pane, and give CLIM's pane layout engine permission to shrink the pane below the preferred size."
       (:PAR) "If either of the " (:CL ":max-width") " or " (:CL ":min-width")
       " options is not supplied, it defaults to the value of the " (:CL ":width") " option. If either of the "
       (:CL ":max-height") " or " (:CL ":min-height") " options is not supplied, it defaults to the value of the "
       (:CL ":height") " option." (:PAR) (:CL ":max-width") ", " (:CL ":min-width") ", " (:CL ":max-height") ", and "
       (:CL ":min-height") " can also be specified as a relative size by supplying a list of the form "
       (:CL "(" (:GROUP (:FONT :FACE :I) "number") " :relative)")
       ". In this case, the number indicates the number of device units that the pane is willing to stretch or shrink."
       (:PAR) "The values of these options are specified in the same way as the " (:CL ":x-spacing") " and "
       (:CL ":y-spacing") " options to " (:CL "formatting-table") ". (Note that " (:CL ":character") " and "
       (:CL ":line") " may only be used on those panes that display text, such as a " (:CL "clim-stream-pane") " or a "
       (:CL "label-pane") ".)" (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "+fill+")) :PARAMS ((:I)) :KIND ("Constant")) (:PAR)
       "This constant can be used as a value to any of the relative size options. It indicates that pane's willingness to adjust an arbitrary amount in the specified direction."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":align-x")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":align-y")) :PARAMS ((:I)) :KIND ("Option")) (:PAR) "The " (:CL ":align-x")
       " option is one of " (:CL ":right") ", " (:CL ":center") ", or " (:CL ":left") ". The " (:CL ":align-y")
       " option is one of " (:CL ":top") ", " (:CL ":center") ", or " (:CL ":bottom")
       ". These are used to specify how child panes are aligned within the parent pane. These have the same semantics as for "
       (:CL "formatting-cell") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":x-spacing")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":y-spacing")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":spacing")) :PARAMS ((:I)) :KIND ("Option")) (:PAR) "These spacing options apply to "
       (:CL "hbox-pane") ", " (:CL "vbox-pane") ", " (:CL "table-pane") ", and " (:CL "grid-pane")
       ", and indicate the amount of horizontal and vertical spacing (respectively) to leave between the items in boxes or rows and columns in table. The values of these options are specified in the same way as the "
       (:CL ":x-spacing") " and " (:CL ":y-spacing") " options to " (:CL "formatting-table") ". " (:CL ":spacing")
       " specifies both the " (:MATH "x") " and " (:MATH "y") " spacing simultaneously." (:PAR) " "))
     (:SECTION :TITLE ("29.3.2 " "Layout Pane Classes") :KIND :SUBSECTION :NAME (4 5 4 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "hbox-pane")) :PARAMS ((:I)) :KIND ("Layout Pane"))
       (:SIGNATURE :NAME ((:CL "horizontally")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options " (:GROUP (:FONT :FACE :TT) "&key ") "spacing "
          (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ") " (:GROUP (:FONT :FACE :TT) "&body ") "contents"))
        :KIND ("Macro"))
       (:PAR) "The " (:CL "hbox-pane")
       " class lays out all of its child panes horizontally, from left to right. The child panes are separated by the amount of space specified by "
       (:GROUP (:FONT :FACE :I) "spacing") "." (:PAR) "The " (:CL "horizontally")
       " macro serves as a convenient interface for creating an " (:CL "hbox-pane") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "contents") " is one or more forms that are the child panes. Each form in "
       (:GROUP (:FONT :FACE :I) "contents") " is of the form:" (:PAR)
       (:UL
        (:LI "A pane. The pane is inserted at this point and its space requirements are used to compute the size."
         (:PAR))
        (:LI "A number. The specified number of device units should be allocated at this point." (:PAR))
        (:LI "The symbol " (:CL "+fill+")
         ". This means that an arbitrary amount of space can be absorbed at this point in the layout." (:PAR))
        (:LI
         "A list whose first element is a number and whose second element evaluates to a pane. If the number is less than 1, then it means that that percentage of excess space or deficit should be allocated to the pane. If the number is greater than or equal to 1, then that many device units are allocated to the pane. For example:"
         (:PAR)
         (:PRE "
(horizontally ()
  (1/3 (make-pane 'label-button-pane))
  (2/3 (make-pane 'label-button-pane)))
")
         (:PAR)
         "would create a horizontal stack of two button panes. The first button takes one-third of the space, then second takes two-thirds of the space. "))
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "vbox-pane")) :PARAMS ((:I)) :KIND ("Layout Pane"))
       (:SIGNATURE :NAME ((:CL "vertically")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options " (:GROUP (:FONT :FACE :TT) "&key ") "spacing "
          (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ") " (:GROUP (:FONT :FACE :TT) "&body ") "contents"))
        :KIND ("Macro"))
       (:PAR) "The " (:CL "vbox-pane")
       " class lays out all of its child panes vertically, from top to bottom. The child panes are separated by the amount of space specified by "
       (:GROUP (:FONT :FACE :I) "spacing") "." (:PAR) "The " (:CL "vertically")
       " macro serves as a convenient interface for creating an " (:CL "vbox-pane") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "contents") " is as for " (:CL "horizontally") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "hrack-pane")) :PARAMS ((:I)) :KIND ("Layout Pane"))
       (:SIGNATURE :NAME ((:CL "vrack-pane")) :PARAMS ((:I)) :KIND ("Layout Pane")) (:PAR) "Similar to the "
       (:CL "hbox-pane") " and " (:CL "vbox-pane")
       " classes, except that these ensure that all children are the same size in the minor dimension. In other words, these panes are used to create stacks of same-sized items, such as menu items."
       (:PAR) "An " (:CL "hrack-pane") " is created when the " (:CL ":equalize-height") " option to "
       (:CL "horizontally") " is " (:TERM "true") ". A " (:CL "vrack-pane") " is created when the "
       (:CL ":equalize-width") " option to " (:CL "vertically") " is " (:TERM "true") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "table-pane")) :PARAMS ((:I)) :KIND ("Layout Pane"))
       (:SIGNATURE :NAME ((:CL "tabling")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options) " (:GROUP (:FONT :FACE :TT) "&body ") "contents")) :KIND
        ("Macro"))
       (:PAR)
       "This pane lays out its child panes in a two-dimensional table arrangement. Each of the table is specified by an extra level of list in "
       (:GROUP (:FONT :FACE :I) "contents") ". For example," (:PAR)
       (:PRE "
(tabling ()
  (list
    (make-pane 'label :text \"Red\")
    (make-pane 'label :text \"Green\")
    (make-pane 'label :text \"Blue\"))
  (list
    (make-pane 'label :text \"Intensity\")
    (make-pane 'label :text \"Hue\")
    (make-pane 'label :text \"Saturation\")))
")
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "grid-pane")) :PARAMS ((:I)) :KIND ("Layout Pane")) (:PAR) "A " (:CL "grid-pane")
       " is like a " (:CL "table-pane") ", except that each cell is the same size in each of the two dimensions."
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "spacing-pane")) :PARAMS ((:I)) :KIND ("Layout Pane"))
       (:SIGNATURE :NAME ((:CL "spacing")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options " (:GROUP (:FONT :FACE :TT) "&key ") "thickness "
          (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ") " (:GROUP (:FONT :FACE :TT) "&body ") "contents"))
        :KIND ("Macro"))
       (:PAR) "This pane reserves some margin space of thickness " (:GROUP (:FONT :FACE :I) "thickness")
       " around a single child pane. The space requirement keys that are passed in indicate the requirements for the surrounding space, not including the requirements of the child."
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "outlined-pane")) :PARAMS ((:I)) :KIND ("Layout Pane"))
       (:SIGNATURE :NAME ((:CL "outlining")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options " (:GROUP (:FONT :FACE :TT) "&key ") "thickness "
          (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ") " (:GROUP (:FONT :FACE :TT) "&body ") "contents"))
        :KIND ("Macro"))
       (:PAR) "This layout pane puts a outline of thickness " (:GROUP (:FONT :FACE :I) "thickness")
       " around its contents." (:PAR) "The " (:CL ":background")
       " option can be used to control the ink used to draw the background." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "restraining-pane")) :PARAMS ((:I)) :KIND ("Layout Pane"))
       (:SIGNATURE :NAME ((:CL "restraining")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options) " (:GROUP (:FONT :FACE :TT) "&body ") "contents")) :KIND
        ("Macro"))
       (:PAR)
       "Wraps the contents with a pane that prevents changes to the space requirements for contents from causing relayout of panes outside of the restraining context. In other words, it prevents the size constraints of the child from propagating up beyond this point."
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "bboard-pane")) :PARAMS ((:I)) :KIND ("Layout Pane")) (:PAR)
       "A pane that allows its children to be any size and lays them out wherever they want to be (for example, a desktop manager)."
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "label-pane")) :PARAMS ((:I)) :KIND ("Service Pane"))
       (:SIGNATURE :NAME ((:CL "labelling")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options " (:GROUP (:FONT :FACE :TT) "&key ")
          "label label-alignment " (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ")  "
          (:GROUP (:FONT :FACE :TT) "&body ") "contents"))
        :KIND ("Macro"))
       (:PAR) "Creates a pane that consists of the specified label " (:GROUP (:FONT :FACE :I) "label")
       ", which is a string. " (:GROUP (:FONT :FACE :I) "label-alignment") " may be either " (:CL ":bottom") " or "
       (:CL ":top")
       ", which specifies whether the label should appear at the top or the bottom of the labelled pane. The default for "
       (:GROUP (:FONT :FACE :I) "label-alignment") " is left unspecified." (:PAR) " "))
     (:SECTION :TITLE ("29.3.3 " "Scroller Pane Classes") :KIND :SUBSECTION :NAME (4 5 4 10) (:PAR)
      "CLIM defines the following additional pane classes, each having at least one implementation." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "scroller-pane")) :PARAMS ((:I)) :KIND ("Service Pane"))
       (:SIGNATURE :NAME ((:CL "scrolling")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options) " (:GROUP (:FONT :FACE :TT) "&body ") "contents")) :KIND
        ("Macro"))
       (:PAR) "Creates a composite pane that allows the single child specified by "
       (:GROUP (:FONT :FACE :I) "contents") " to be scrolled. " (:GROUP (:FONT :FACE :I) "options") " may include a "
       (:CL ":scroll-bar") " option. The value of this option may be " (:CL "t")
       " (the default), which indicates that both horizontal and vertical scroll bars should be created; "
       (:CL ":vertical") ", which indicates that only a vertical scroll bar should be created; or " (:CL ":horizontal")
       ", which indicates that only a horizontal scroll bar should be created." (:PAR) "The pane created by the "
       (:CL "scrolling") " will include a " (:CL "scroller-pane") " that has as children the scroll bars and a "
       (:CONCEPT "viewport")
       ". The viewport of a pane is the area of the window's drawing plane that is currently visible to the user. The viewport has as its child the specified contents."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "pane-viewport")) :PARAMS ((:I "pane")) :KIND ("Generic Function")) (:PAR)
       "If the pane " (:GROUP (:FONT :FACE :I) "pane")
       " is part of a scroller pane, this returns the viewport pane for " (:GROUP (:FONT :FACE :I) "pane")
       ". Otherwise it returns " (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "pane-viewport-region")) :PARAMS ((:I "pane")) :KIND ("Generic Function")) (:PAR)
       "If the pane " (:GROUP (:FONT :FACE :I) "pane")
       " is part of a scroller pane, this returns the region of the pane's viewport. Otherwise it returns " (:CL "nil")
       "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "pane-scroller")) :PARAMS ((:I "pane")) :KIND ("Generic Function")) (:PAR)
       "If the pane " (:GROUP (:FONT :FACE :I) "pane")
       " is part of a scroller pane, this returns the scroller pane itself. Otherwise it returns " (:CL "nil") "."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "scroll-extent")) :PARAMS ((:I "pane x y")) :KIND ("Generic Function")) (:PAR)
       "If the pane " (:GROUP (:FONT :FACE :I) "pane")
       " is part of a scroller pane, this scrolls the pane in its viewport so that the position " (:MATH "(x,y)")
       " of " (:GROUP (:FONT :FACE :I) "pane")
       " is at the upper-left corner of the viewport. Otherwise, it does nothing." (:PAR) (:GROUP (:FONT :FACE :I) "x")
       " and " (:GROUP (:FONT :FACE :I) "y") " are coordinates." (:PAR) " "))
     (:SECTION :TITLE ("29.3.4 " "The Layout Protocol" (:LABEL :NAME "layout-protocol")) :KIND :SUBSECTION :NAME
      (4 5 4 10) (:PAR) "The layout protocol is triggered by " (:CL "layout-frame")
      ", which is called when a frame is adopted by a frame manager." (:PAR)
      "CLIM uses a two pass algorithm to lay out a pane hierarchy. In the first pass (called called "
      (:CONCEPT "space composition")
      "), the top-level pane is asked how much space it requires. This may in turn lead to same the question being asked recursively of all the panes in the hierarchy, with the answers being composed to produce the top-level pane's answer. Each pane answers the query by returning a "
      (:CONCEPT "space requirement") " (or " (:CL "space-requirement")
      ") object, which specifies the pane's desired width and height as well as its willingness to shrink or grow along its width and height."
      (:PAR) "In the second pass (called " (:CONCEPT "space allocation")
      "), the frame manager attempts to obtain the required amount of space from the host window system. The top-level pane is allocated the space that is actually available. Each pane, in turn, allocates space recursively to each of its descendants in the hierarchy according to the pane's rules of composition."
      (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
      (:GROUP (:FONT :FACE :SL)
       "It isn't alway possible to allocate the required space. What is the protocol for handling these space allocation failures? Some kind of error should be signalled when the constraints can't be satisfied, which can be handled by the application. Otherwise the panes will fall where they may. The "
       (:CL "define-application-frame")
       " macro should provide an option that allows programmers to conveniently specify a condition handler. --- ILA")
      (:PAR)
      "For many types of panes, the application programmer can indicate the space requirements of the pane at creation time by using the space requirement options (described above), as well as by calling the "
      (:CL "change-space-requirements")
      " function (described below). For example, application panes are used to display application-specific information, so the application can determine how much space should normally be given to them."
      (:PAR)
      "Other pane types automatically calculate how much space they need based on the information they need to display. For example, label panes automatically calculate their space requirement based on the text they need to display."
      (:PAR)
      "A composite pane calculates its space requirement based on the requirements of its children and its own particular rule for arranging them. For example, a pane that arranges its children in a vertical stack would return as its desired height the sum of the heights of its children. Note however that a composite is not required by the layout protocol to respect the space requests of its children; in fact, composite panes aren't even required to ask their children."
      (:PAR)
      "Space requirements are expressed for each of the two dimensions as a preferred size, a mininum size below which the pane cannot be shrunk, and a maxium size above which the pane cannot be grown. (The minimum and maximum sizes can also be specified as relative amounts.) All sizes are specified as a real number indicating the number of device units (such as pixels)."
      (:PAR) " "
      (:DEFUN (:SIGNATURE :NAME ((:CL "space-requirement")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The protocol class of all space requirement objects. There are one or more subclasses of "
       (:CL "space-requirement")
       " with implementation-dependent names that implement space requirements. The exact names of these classes is explicitly unspecified. If you want to create a new class that behaves like a space requirement, it should be a subclass of "
       (:CL "space-requirement") ". All instantiable subclasses of " (:CL "space-requirement")
       " must obey the space requirement protocol. " (:PAR)
       "All of the instantiable space requirement classes provided by CLIM are immutable." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-space-requirement")) :PARAMS
        ((:I (:GROUP (:FONT :FACE :TT) "&key ") "(width " (:CL "0") ") (max-width " (:CL "0") ") (min-width " (:CL "0")
          ")  (height " (:CL "0") ") (max-height " (:CL "0") ") (min-height " (:CL "0") ")"))
        :KIND ("Function"))
       (:PAR) "Constructs a space requirement object with the given characteristics, " (:CL ":width") ", "
       (:CL ":height") ", and so on." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "space-requirement-width")) :PARAMS ((:I "space-req")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "space-requirement-min-width")) :PARAMS ((:I "space-req")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "space-requirement-max-width")) :PARAMS ((:I "space-req")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "space-requirement-height")) :PARAMS ((:I "space-req")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "space-requirement-min-height")) :PARAMS ((:I "space-req")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "space-requirement-max-height")) :PARAMS ((:I "space-req")) :KIND ("Generic Function"))
       (:PAR) "These functions read the components of the space requirement " (:GROUP (:FONT :FACE :I) "space-req") "."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "space-requirement-components")) :PARAMS ((:I "space-req")) :KIND ("Generic Function"))
       (:PAR) "Returns the components of the space requirement " (:GROUP (:FONT :FACE :I) "space-req")
       " as six values, the width, minimum width, maximum width, height, minimum height, and maximum height." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "space-requirement-combine")) :PARAMS ((:I "function sr1 sr2")) :KIND ("Function"))
       (:PAR) "Returns a new space requirement each of whose components is the result of applying the function "
       (:GROUP (:FONT :FACE :I) "function") " to each the components of the two space requirements "
       (:GROUP (:FONT :FACE :I) "sr1") " and " (:GROUP (:FONT :FACE :I) "sr2") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "function")
       " is a function of two arguments, both of which are real numbers. It has dynamic extent." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "space-requirement+")) :PARAMS ((:I "sr1 sr2")) :KIND ("Function")) (:PAR)
       "Returns a new space whose components are the sum of each of the components of " (:GROUP (:FONT :FACE :I) "sr1")
       " and " (:GROUP (:FONT :FACE :I) "sr2") ". This could be implemented as follows:" (:PAR)
       (:PRE "
(defun space-requirement+ (sr1 sr2)
  (space-requirement-combine #'+ sr1 sr2))
")
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "space-requirement+*")) :PARAMS
        ((:I "space-req " (:GROUP (:FONT :FACE :TT) "&key ")
          "width min-width max-width  height min-height max-height"))
        :KIND ("Function"))
       (:PAR) "Returns a new space requirement whose components are the sum of each of the components of "
       (:GROUP (:FONT :FACE :I) "space-req")
       " added to the appropriate keyword argument (for example, the width component of "
       (:GROUP (:FONT :FACE :I) "space-req") " is added to " (:GROUP (:FONT :FACE :I) "width") ")." (:PAR)
       "This is intended to be a more efficient, \"spread\" version of " (:CL "space-requirement+") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "compose-space")) :PARAMS
        ((:I "pane " (:GROUP (:FONT :FACE :TT) "&key ") "width height")) :KIND ("Generic Function"))
       (:PAR)
       "During the space composition pass, a composite pane will typically ask each of its children how much space it requires by calling "
       (:CL "compose-space") ". They answer by returning " (:CL "space-requirement")
       " objects. The composite will then form its own space requirement by composing the space requirements of its children according to its own rules for laying out its children."
       (:PAR) "The value returned by " (:CL "compose-space")
       " is a space requirement object that represents how much space the pane " (:GROUP (:FONT :FACE :I) "pane")
       " requires." (:PAR) (:GROUP (:FONT :FACE :I) "width") " and " (:GROUP (:FONT :FACE :I) "height")
       " are real numbers that the " (:CL "compose-space")
       " method for a pane may use as \"recommended\" values for the width and height of the pane. These are used to drive top-down layout."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "allocate-space")) :PARAMS ((:I "pane width height")) :KIND ("Generic Function"))
       (:PAR)
       "During the space allocation pass, a composite pane will arrange its children within the available space and allocate space to them according to their space requirements and its own composition rules by calling "
       (:CL "allocate-space") " on each of the child panes. " (:GROUP (:FONT :FACE :I) "width") " and "
       (:GROUP (:FONT :FACE :I) "height") " are the width and height of " (:GROUP (:FONT :FACE :I) "pane")
       " in device units." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "change-space-requirements")) :PARAMS
        ((:I "pane " (:GROUP (:FONT :FACE :TT) "&key ") "resize-frame " (:GROUP (:FONT :FACE :TT) "&rest ")
          "space-req-keys"))
        :KIND ("Generic Function"))
       (:PAR) "This function can be invoked to indicate that the space requirements for "
       (:GROUP (:FONT :FACE :I) "pane")
       " have changed. Any of the options that applied to the pane at creation time can be passed into this function as well."
       (:PAR) (:GROUP (:FONT :FACE :I) "resize-frame")
       " determines whether the frame should be resized to accommodate the new space requirement of the hierarchy. If "
       (:GROUP (:FONT :FACE :I) "resize-frame") " is " (:TERM "true") ", then " (:CL "layout-frame")
       " will be invoked on the frame. If " (:GROUP (:FONT :FACE :I) "resize-frame") " is " (:TERM "false")
       ", then the frame may or may not get resized depending on the pane hierarchy and the " (:CL ":resize-frame")
       " option that was supplied to " (:CL "define-application-frame") "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "note-space-requirements-changed")) :PARAMS ((:I "sheet pane")) :KIND
        ("Generic Function"))
       (:PAR) "This function is invoked whenever " (:GROUP (:FONT :FACE :I) "pane")
       "'s space requirements have changed. " (:GROUP (:FONT :FACE :I) "sheet") " must be the parent of "
       (:GROUP (:FONT :FACE :I) "pane") ". Invoking this function essentially means that "
       (:GROUP (:FONT :FACE :I) "compose-space") " will be reinvoked on " (:GROUP (:FONT :FACE :I) "pane")
       ", then it will reply with a space requirement that is not equal to the reply that was given on the last call to "
       (:GROUP (:FONT :FACE :I) "compose-space") "." (:PAR) "This function is automatically invoked by "
       (:CL "change-space-requirements") " in the cases that " (:CL "layout-frame") " isn't invoked. In the case that "
       (:CL "layout-frame") " is invoked, it isn't necessary to call " (:CL "note-space-requirements-changed")
       " since a complete re-layout of the frame will be executed." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "changing-space-requirements")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&key ") "resize-frame layout) " (:GROUP (:FONT :FACE :TT) "&body ")
          "body"))
        :KIND ("Macro"))
       (:PAR) "This macro supports batching the invocation of the layout protocol by calls to "
       (:CL "change-space-requirements") ". Within the body, all calls to " (:CL "change-space-requirements")
       " change the internal structures of the pane and are recorded. When the body is exited, the layout protocol is invoked appropriately. "
       (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR) " ")))
    (:SECTION :TITLE ("29.4 " "CLIM Stream Panes" (:LABEL :NAME "clim-panes")) :KIND :SECTION :NAME (5 4 10) (:PAR)
     "In addition to the various layout panes and gadgets, an application usually needs some space to display application-specific output and receive application-specific input from the user. For example, a paint program needs a \"canvas\" pane on which to display the picture and handle the \"mouse strokes\". An application frame can use the basic CLIM input and output services in an application-specific way through use of a "
     (:CONCEPT "CLIM stream pane") "." (:PAR)
     "This section describes the basic CLIM stream pane types. Programmers are free to customize pane behavior by defining subclasses of these pane classes writing methods to change the repaint or event-handling behavior."
     (:PAR) " "
     (:SECTION :TITLE ("29.4.1 " "CLIM Stream Pane Options" (:LABEL :NAME "clim-pane-options")) :KIND :SUBSECTION :NAME
      (5 5 4 10) (:PAR) "CLIM application frames accept the " (:CL ":foreground") ", " (:CL ":background") ", "
      (:CL ":text-style") ", and layout pane options. The space requirement options (" (:CL ":width") ", "
      (:CL ":height") ", and so forth) can also take a size specification of " (:CL ":compute")
      ", which causes CLIM to run the display function for the pane, and make the pane large enough to hold the output of the display function."
      (:PAR) "In addition to the above, CLIM stream panes accept the following options:" (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL ":display-function")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "This is used to specify a function to be called in order to display the contents of a CLIM stream pane. CLIM's default top level function, "
       (:CL "default-frame-top-level")
       ", function will invoke the pane's display function at the appropriate time (see the " (:CL ":display-time")
       " option). The value of this option is either the name of a function to invoke, or a cons whose car is the name of a function and whose cdr is additional arguments to the function. The function will be invoked on the frame, the pane, and the additional function arguments, if any. The default for this option is "
       (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":display-time")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "This is used to indicate to CLIM when the pane's display function should be run. If it is "
       (:CL ":command-loop")
       ", CLIM will clear the pane and run the display function after each time a frame command is executed. If it is "
       (:CL "t") ", the pane will be displayed once and not again until " (:CL "(setf pane-needs-redisplay)")
       " is called on the pane. If it is " (:CL "nil")
       ", CLIM will never run the display function until it is explicitly requested, either via "
       (:CL "pane-needs-redisplay") " or " (:CL "redisplay-frame-pane")
       ". The default for this option varies depending on the type of the pane." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":incremental-redisplay")) :PARAMS ((:I)) :KIND ("Option")) (:PAR) "When "
       (:TERM "true") ", the redisplay function will initially be executed inside of an invocation to "
       (:CL "updating-output") " and the resulting output record will be saved. Subsequent calls to "
       (:CL "redisplay-frame-pane") " will simply use " (:CL "redisplay")
       " to redisplay the pane. The default for this option is " (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":text-margin")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":vertical-spacing")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "These options specify the default text margin (that is, how much space is left around the inside edge of the pane) and vertical spacing (that is, how much space is between each text line) for the pane. The default for "
       (:CL ":text-margin") " is the width of the window, and the default for " (:CL ":vertical-spacing") " is 2."
       (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL ":end-of-line-action")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":end-of-page-action")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "These options specify the end-of-line and end-of-page actions to be used for the pane. The default for these options are "
       (:CL ":wrap") " and " (:CL ":scroll") ", respectively." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":output-record")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "This option names the output record class to be used for the output history of the pane. The default is "
       (:CL "standard-tree-output-history") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":draw")) :PARAMS ((:I)) :KIND ("Option"))
       (:SIGNATURE :NAME ((:CL ":record")) :PARAMS ((:I)) :KIND ("Option")) (:PAR)
       "These options specify whether the pane should initially allow drawing and output recording. The default for both options is "
       (:CL "t") "." (:PAR) " "))
     (:SECTION :TITLE ("29.4.2 " "CLIM Stream Pane Classes") :KIND :SUBSECTION :NAME (5 5 4 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "clim-stream-pane")) :PARAMS ((:I)) :KIND ("Service Pane")) (:PAR)
       "This class implements a pane that supports the CLIM graphics, extended input and output, and output recording protocols. Most CLIM stream panes will be subclasses of this class."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "interactor-pane")) :PARAMS ((:I)) :KIND ("Service Pane")) (:PAR)
       "The pane class that is used to implement \"interactor\" panes. The default method for "
       (:CL "frame-standard-input") " will return the first pane of this type." (:PAR) "For " (:CL "interactor-pane")
       ", the default for " (:CL ":display-time") " is " (:CL "nil") " and the default for " (:CL ":scroll-bars")
       " is " (:CL ":vertical") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "application-pane")) :PARAMS ((:I)) :KIND ("Service Pane")) (:PAR)
       "The pane class that is used to implement \"application\" panes. The default method for "
       (:CL "frame-standard-output") " will return the first pane of this type." (:PAR) "For " (:CL "application-pane")
       ", the default for " (:CL ":display-time") " is " (:CL ":command-loop") " and the default for "
       (:CL ":scroll-bars") " is " (:CL "t") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "command-menu-pane")) :PARAMS ((:I)) :KIND ("Service Pane")) (:PAR)
       "The pane class that is used to implement command menu panes that are not menu bars. The default display function for panes of this type is "
       (:CL "display-command-menu") "." (:PAR) "For " (:CL "command-menu-pane") ", the default for "
       (:CL ":display-time") " is " (:CL ":command-loop") ", the default for " (:CL ":incremental-redisplay") " is "
       (:CL "t") ", and the default for " (:CL ":scroll-bars") " is " (:CL "t") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "title-pane")) :PARAMS ((:I)) :KIND ("Service Pane")) (:PAR)
       "The pane class that is used to implement a title pane. The default display function for panes of this type is "
       (:CL "display-title") "." (:PAR) "For " (:CL "title-pane") ", the default for " (:CL ":display-time") " is "
       (:CL "t") " and the default for " (:CL ":scroll-bars") " is " (:CL "nil") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "pointer-documentation-pane")) :PARAMS ((:I)) :KIND ("Service Pane")) (:PAR)
       "The pane class that is used to implement the pointer documentation pane." (:PAR) "For "
       (:CL "pointer-documentation-pane") ", the default for " (:CL ":display-time") " is " (:CL "nil")
       " and the default for " (:CL ":scroll-bars") " is " (:CL "nil") "." (:PAR) " "))
     (:SECTION :TITLE ("29.4.3 " "Making CLIM Stream Panes") :KIND :SUBSECTION :NAME (5 5 4 10) (:PAR)
      "Most CLIM stream panes will contain more information than can be displayed in the allocated space, so scroll bars are nearly always desirable. CLIM therefore provides a convenient form for creating composite panes that include the CLIM stream pane, scroll bars, labels, and so forth."
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-clim-stream-pane")) :PARAMS
        ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "options  " (:GROUP (:FONT :FACE :TT) "&key ")
          "type label label-alignment scroll-bars borders  display-after-commands "
          (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
        :KIND ("Function"))
       (:PAR) "Creates a pane of type " (:GROUP (:FONT :FACE :I) "type") ", which defaults to "
       (:CL "clim-stream-pane") "." (:PAR) "If " (:GROUP (:FONT :FACE :I) "label")
       " is supplied, it is a string used to label the pane. " (:GROUP (:FONT :FACE :I) "label-alignment")
       " is as for the " (:CL "labelling") " macro." (:PAR) (:GROUP (:FONT :FACE :I) "scroll-bars") " may be "
       (:CL "t") " to indicate that both vertical and horizontal scroll bars should be included, " (:CL ":vertical")
       " (the default) to indicate that vertical scroll bars should be included, or " (:CL ":horizontal")
       " to indicate that horizontal scroll bars should be included." (:PAR) "If " (:GROUP (:FONT :FACE :I) "borders")
       " is " (:TERM "true") ", the default, a border is drawn around the pane." (:PAR)
       (:GROUP (:FONT :FACE :I) "display-after-commands") " is used to initialize the " (:CL ":display-time")
       " property of the pane. It may be " (:CL "t") " (for " (:CL ":display-time :command-loop") "), "
       (:CL ":no-clear") " (for " (:CL ":display-time :no-clear") "), or " (:CL "nil") " (for "
       (:CL ":display-time nil") ")." (:PAR) "The other options may include all of the valid CLIM stream pane options."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-clim-interactor-pane")) :PARAMS
        ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "options")) :KIND ("Function"))
       (:PAR) "Like " (:CL "make-clim-stream-pane") ", except that the type is forced to be " (:CL "interactor-pane")
       "." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "make-clim-application-pane")) :PARAMS
        ((:I (:GROUP (:FONT :FACE :TT) "&rest ") "options")) :KIND ("Function"))
       (:PAR) "Like " (:CL "make-clim-stream-pane") ", except that the type is forced to be " (:CL "application-pane")
       "." (:PAR) " "))
     (:SECTION :TITLE ("29.4.4 " "CLIM Stream Pane Functions") :KIND :SUBSECTION :NAME (5 5 4 10) (:PAR)
      "The following functions can be called on any pane that is a subclass of " (:CL "clim-stream-pane")
      ". (Such a pane is often simply referred to as a " (:CONCEPT "window")
      ".) These are provided purely as a convenience for programmers." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "window-clear")) :PARAMS ((:I "window")) :KIND ("Generic Function")) (:PAR)
       "Clears the entire drawing plane by filling it with the background design of the CLIM stream pane "
       (:GROUP (:FONT :FACE :I) "window") ". If " (:GROUP (:FONT :FACE :I) "window")
       " has an output history, that is cleared as well. The text cursor position of "
       (:GROUP (:FONT :FACE :I) "window") ", if there is one, is reset to the upper left corner." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "window-refresh")) :PARAMS ((:I "window")) :KIND ("Generic Function")) (:PAR)
       "Clears the visible part of the drawing plane of the CLIM stream pane " (:GROUP (:FONT :FACE :I) "window")
       ", and then if the window stream is an output recording stream, the output records in the visible part of the window are replayed."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "window-viewport")) :PARAMS ((:I "window")) :KIND ("Generic Function")) (:PAR)
       "Returns the viewport region of the CLIM stream pane " (:GROUP (:FONT :FACE :I) "window")
       ". If the window is not scrollable, and hence has no viewport, this will region " (:CL "sheet-region") " of "
       (:GROUP (:FONT :FACE :I) "window") "." (:PAR) "The returned region will generally be a "
       (:CL "standard-bounding-rectangle") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "window-erase-viewport")) :PARAMS ((:I "window")) :KIND ("Generic Function"))
       (:PAR) "Clears the visible part of the drawing plane of the CLIM stream pane "
       (:GROUP (:FONT :FACE :I) "window") " by filling it with the background design." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "window-viewport-position")) :PARAMS ((:I "window")) :KIND ("Generic Function"))
       (:PAR) "Returns two values, the " (:MATH "x") " and " (:MATH "y")
       " position of the top-left corner of the CLIM stream pane " (:GROUP (:FONT :FACE :I) "window")
       "'s viewport. If the window is not scrollable, this will return the two values 0 and 0." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "(setf* window-viewport-position)")) :PARAMS ((:I "x y window")) :KIND
        ("Generic Function"))
       (:PAR) "Sets the position of the CLIM stream pane " (:GROUP (:FONT :FACE :I) "window") "'s viewport to "
       (:GROUP (:FONT :FACE :I) "x") " and " (:GROUP (:FONT :FACE :I) "y")
       ". If the window is not scrollable, this will do nothing." (:PAR)
       "For CLIM implementations that do not support " (:CL "setf*") ", the \"setter\" function for this is "
       (:CL "window-set-viewport-position") "." (:PAR) " "))
     (:SECTION :TITLE ("29.4.5 " "Creating a Standalone CLIM Window") :KIND :SUBSECTION :NAME (5 5 4 10) (:PAR)
      "The following function can be used to create a standalone window that obeys CLIM's extended input and output stream and output recording protocols."
      (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "open-window-stream")) :PARAMS
        ((:I (:GROUP (:FONT :FACE :TT) "&key ")
          "port left top right bottom width height  foreground background text-style  (vertical-spacing " (:CL "2")
          ")  end-of-line-action end-of-page-action  output-record (draw " (:CL "t") ") (record " (:CL "t")
          ")  (initial-cursor-visibility " (:CL ":off") ")  text-margin save-under input-buffer  (scroll-bars "
          (:CL ":vertical") ") borders label"))
        :KIND ("Function"))
       (:PAR)
       "Creates and returns a sheet that can be used as a standalone window that obeys CLIM's extended input and output stream and output recording protocols."
       (:PAR) "The window will be created on the port " (:GROUP (:FONT :FACE :I) "port")
       " at the position specified by " (:GROUP (:FONT :FACE :I) "left") " and " (:GROUP (:FONT :FACE :I) "top")
       ", which default to 0. " (:GROUP (:FONT :FACE :I) "right") ", " (:GROUP (:FONT :FACE :I) "bottom") ", "
       (:GROUP (:FONT :FACE :I) "width") ", and " (:GROUP (:FONT :FACE :I) "height")
       " default in such a way that the default width will be 100 and the default height will be 100." (:PAR)
       (:GROUP (:FONT :FACE :I) "foreground") ", " (:GROUP (:FONT :FACE :I) "background") ", and "
       (:GROUP (:FONT :FACE :I) "text-style")
       " are used to specify the window's default foreground and background inks, and text style. "
       (:GROUP (:FONT :FACE :I) "vertical-spacing") ", " (:GROUP (:FONT :FACE :I) "text-margin") ", "
       (:GROUP (:FONT :FACE :I) "end-of-line-action") ", " (:GROUP (:FONT :FACE :I) "end-of-page-action") ", "
       (:GROUP (:FONT :FACE :I) "output-record") ", " (:GROUP (:FONT :FACE :I) "draw") ", and "
       (:GROUP (:FONT :FACE :I) "record") " are described in Section " (:REF :NAME "clim-pane-options") "." (:PAR)
       (:GROUP (:FONT :FACE :I) "scroll-bars")
       " specifies whether scroll bars should be included in the resulting window. It may be one of "
       (:GROUP (:FONT :FACE :I) "nil") ", " (:CL ":vertical") " (the default), " (:CL ":horizontal") ", or "
       (:CL ":both") "." (:PAR) (:GROUP (:FONT :FACE :I) "borders")
       " is a booleans that specifies whether or not the resulting window should have a border drawn around it. The default is "
       (:CL "t") ". " (:GROUP (:FONT :FACE :I) "label") " is either " (:CL "nil")
       " or a string to use as a label for the window." (:PAR) (:GROUP (:FONT :FACE :I) "initial-cursor-visibility")
       " is used to specify whether the window should have a text cursor. " (:CL ":off")
       " (the default) means to make the cursor visible if the window is waiting for input. " (:CL ":on")
       " means to make the cursor visible immediately. " (:CL "nil") " means the cursor will not be visible at all."
       (:PAR) "When " (:GROUP (:FONT :FACE :I) "save-under") " is " (:TERM "true")
       ", the result window will be given a \"bit save array\". The default is " (:CL "nil") "." (:PAR) "If "
       (:CL "input-buffer")
       " is supplied, it is an input buffer or event queue to use for the resulting window. Programmers will generally supply this when they want the new window to share its input buffer with an existing application. The default is to create a new input buffer."
       (:PAR) " ")))
    (:SECTION :TITLE ("29.5 " "Defining New Pane Types") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "This section describes how to define new pane classes. The first section shows a new kind of leaf pane (an odd kind of push-button). The second section shows a new composite pane that draws a dashed border around its contents."
     (:PAR)
     (:SECTION :TITLE ("29.5.1 " "Defining a New Leaf Pane") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      "To define a gadget pane implementation, first define the appearance and layout behavior of the gadget, then define the callbacks, then define the specific user interactions that trigger the callbacks."
      (:PAR)
      "For example, to define an odd new kind of button that displays itself as a circle, and activates whenever the mouse is moved over it, proceed as follows:"
      (:PAR)
      (:PRE "
;; A new kind of button.
(defclass sample-button-pane
          (action-gadget
           space-requirement-mixin
           leaf-pane)
    ())

;; An arbitrary size parameter.
(defparameter *sample-button-radius* 10)

;; Define the sheet's repaint method to draw the button.
(defmethod handle-repaint ((button sample-button-pane) region)
  (with-sheet-medium (medium button)
    (let ((radius *sample-button-radius*)
          (half (round  *sample-button-radius* 2)))
      ;; Larger circle with small one in the center
      (draw-circle* medium radius radius radius
                    :filled nil)
      (draw-circle* medium radius radius half
                    :filled t)))

;; Define the pane's compose-space method to always request the
;; fixed size of the pane.
(defmethod compose-space ((pane sample-button-pane) &key width height)
  (declare (ignore width height))
  (make-space-requirement :width  (* 2 *sample-button-radius*)
                          :height (* 2 *sample-button-radius*)))
")
      (:PAR)
      "The above code is enough to allow you to instantiate the button pane in an application frame. It will fit in with the space composition protocol of, for example, an "
      (:CL "hbox-pane") ". It will display itself as two nested circles." (:PAR)
      "The next step is to define the callbacks supported by this gadget, and the user interaction that triggers them."
      (:PAR)
      (:PRE "
;; This default method is defined so that the callback can be invoked
;; on an arbitrary client without error.
(defmethod activate-callback
           ((button sample-button-pane) client id)
  (declare (ignore client id value)))

;; This event processing method defines the rather odd interaction
;; style of this button, to wit, it triggers the activate callback
;; whenever the mouse moves into it.
(defmethod handle-event ((pane sample-button-pane) (event pointer-enter-event))
  (activate-callback pane (gadget-client pane) (gadget-id pane)))
")
      (:PAR) " ")
     (:SECTION :TITLE ("29.5.2 " "Defining a New Composite Pane") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      "To define a new layout pane implementation, the programmer must define how the much space the pane takes, where its children go, and what the pane looks like."
      (:PAR)
      "For example, to define a new kind of border pane that draws a dashed border around its child pane, proceed as follows:"
      (:PAR)
      (:PRE "
;; The new layout pane class.
(defclass dashed-border-pane (layout-pane)
    ((thickness :initform 1 :initarg :thickness))
  (:default-initargs :background +black+))

;; The specified contents are the sole child of the pane.
(defmethod initialize-instance :after ((pane dashed-border-pane) &key contents)
  (sheet-adopt-child pane contents))

;; The composite pane takes up all of the space of the child, plus
;; the space required for the border.
(defmethod compose-space ((pane dashed-border-pane) &key width height)
  (let ((thickness (slot-value pane 'thickness))
        (child (sheet-child pane)))
    (space-requirement+
      (compose-space child :width width :height height)
      (make-space-requirement 
        :width (* 2 thickness)
        :height (* 2 thickness)))))

;; The child pane is positioned just inside the borders.
(defmethod allocate-space ((pane dashed-border-pane) width height)
  (let ((thickness (slot-value pane 'thickness)))
    (move-and-resize-sheet
      (sheet-child pane)
      thickness thickness
      (- width (* 2 thickness)) (- height (* 2 thickness)))))
  
(defmethod handle-repaint ((pane dashed-border-pane) region)
  (declare (ignore region))                     ;not worth checking
  (with-sheet-medium (medium pane)
    (with-bounding-rectangle* (left top right bottom) (sheet-region pane)
      (let ((thickness (slot-value pane 'thickness)))
        (decf right (ceiling thickness 2))
        (decf bottom (ceiling thickness 2))
        (draw-rectangle* medium left top right bottom
                         :line-thickness thickness :filled nil
                         :ink (pane-background pane))))))

(defmacro dashed-border ((&rest options &key thickness &allow-other-keys)
                         &body contents)
  (declare (ignore thickness))
  `(make-pane 'dashed-border-pane
     :contents ,@contents
     ,@options))
")
      (:PAR))))
   (:SECTION :TITLE ("30 " "Gadgets") :KIND :CHAPTER :NAME (4 10) " " (:LABEL :NAME "gadgets") (:PAR)
    (:SECTION :TITLE ("30.1 " "Overview of Gadgets") :KIND :SECTION :NAME (5 4 10) (:PAR) (:CONCEPT "Gadgets")
     " are panes that implement such common toolkit components as push buttons or scroll bars. Each gadget class has a set of associated generic functions that serve the same role that callbacks serve in traditional toolkits. For example, a push button has an \"activate\" callback function that is invoked when its button is \"pressed\"; a scroll bar has a \"value changed\" callback that is invoked after its indicator has been moved."
     (:PAR)
     "The gadget definitions specified by CLIM are abstract, in that the gadget definition does not specify the exact user interface of the gadget, but only specifies the semantics that the gadget should provide. For instance, it is not defined whether the user clicks on a push button with the mouse or moves the mouse over the button and then presses some key on the keyboard to invoke the \"activate\" callback. Each toolkit implementations will specify the \"look and feel\" of their gadgets. Typically, the look and feel will be derived directly from the underlying toolkit."
     (:PAR)
     "Each of CLIM's abstract gadgets has at least one standard implementation that is written using the facilities provided solely by CLIM itself. The gadgets' appearances are achieved via calls to the CLIM graphics functions, and their interactive behavior is defined in terms of the CLIM input event processing mechanism. Since these gadget implementations are written entirely in terms of CLIM, they are portable across all supported CLIM host window systems. Furthermore, since the specific look and feel of each such gadget is \"fixed\" in CLIM Lisp code, the gadget implementation will look and behave the same in all environments."
     (:PAR) " ")
    (:SECTION :TITLE ("30.2 " "Abstract Gadgets") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "The push button and slider gadgets alluded to above are " (:CONCEPT "abstract gadgets")
     ". The callback interface to all of the various implementations of the gadget is defined by the abstract class. In the "
     (:CL ":panes") " clause of " (:CL "define-application-frame")
     ", the abbreviation for a gadget is the name of the abstract gadget class." (:PAR)
     "At pane creation time (that is, " (:CL "make-pane")
     "), the frame manager resolves the abstract class into a specific implementation class; the implementation classes specify the detailed look and feel of the gadget. Each frame manager will keep a mapping from abstract gadgets to an implementation class; if the frame manager does not implement its own gadget for the abstract gadget classes in the following sections, it should use the portable class provided by CLIM. Since every implementation of an abstract gadget class is a subclass of the abstract class, they all share the same programmer interface."
     (:PAR) " "
     (:SECTION :TITLE ("30.2.1 " "Using Gadgets") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR) "Every gadget has a "
      (:CONCEPT "client")
      " that is specified when the gadget is created. The client is notified via the callback mechanism when any important user interaction takes place. Typically, a gadget's client will be an application frame or a composite pane. Each callback generic function is invoked on the gadget, its client, the gadget id (described below), and other arguments that vary depending on the callback."
      (:PAR) "For example, the argument list for " (:CL "activate-callback") " looks like "
      (:GROUP (:FONT :FACE :I) "(gadget client gadget-id)")
      ". Assuming the programmer has defined an application frame called " (:CL "button-test")
      " that has a CLIM stream pane in the slot " (:CL "output-pane") ", he could write the following method:" (:PAR)
      (:PRE "
(defmethod activate-callback
           ((button push-button) (client button-test) gadget-id) 
  (with-slots (output-pane) client
    (format output-pane \"The button ~S was pressed, client ~S, id ~S.\"
       button client gadget-id)))
")
      (:PAR)
      "One problem with this example is that it differentiates on the class of the gadget, not on the particular gadget instance. That is, the same method will run for every push button that has the "
      (:CL "button-test") " frame as its client." (:PAR)
      "One way to distinguish between the various gadgets is via the " (:CONCEPT "gadget id")
      ", which is also specified when the gadget is created. The value of the gadget id is passed as the third argument to each callback generic function. In this case, if we have two buttons, we might install "
      (:CL "start") " and " (:CL "stop") " as the respective gadget ids and then use " (:CL "eql")
      " specializers on the gadget ids. We could then refine the above as:" (:PAR)
      (:PRE "
(defmethod activate-callback
           ((button push-button) (client button-test) (gadget-id (eql 'start)))
  (start-test client))

(defmethod activate-callback
           ((button push-button) (client button-test) (gadget-id (eql 'stop)))
  (stop-test client))

;; Create the start and stop push buttons
(make-pane 'push-button
  :label \"Start\"
  :client frame :id 'start)
(make-pane 'push-button
  :label \"Stop\"
  :client frame :id 'stop)
")
      (:PAR)
      "Another way to distinguish between gadgets is to explicitly specify what function should be called when the callback is invoked. This is specified when the gadget is created by supplying an appropriate initarg. The above example could then be written as follows:"
      (:PAR)
      (:PRE "
;; No callback methods needed, just create the push buttons
(make-pane 'push-button
  :label \"Start\"
  :client frame :id 'start
  :activate-callback
    #'(lambda (gadget)
        (start-test (gadget-client gadget))))
(make-pane 'push-button
  :label \"Stop\"
  :client frame :id 'stop
  :activate-callback
    #'(lambda (gadget)
        (stop-test (gadget-client gadget))))
")
      (:PAR) " ")
     (:SECTION :TITLE ("30.2.2 " "Implementing Gadgets") :KIND :SUBSECTION :NAME (2 5 4 10) (:PAR)
      "The following shows how a push button gadget might be implemented." (:PAR)
      (:PRE "
;; Here is a concrete implementation of a CLIM PUSH-BUTTON.
;; The \"null\" frame manager create a pane of type PUSH-BUTTON-PANE when
;; asked to create a PUSH-BUTTON.
(defclass push-button-pane
          (push-button
           leaf-pane
           space-requirement-mixin)
    ((show-as-default :initarg :show-as-default
                      :accessor push-button-show-as-default)
     (armed :initform nil)))

;; General highlight-by-inverting method.
(defmethod highlight-button ((pane push-button-pane) medium)
  (with-bounding-rectangle* (left top right bottom) (sheet-region pane)
    (draw-rectangle* medium left top right bottom
                     :ink +flipping-ink+ :filled t)
    (medium-force-output medium)))

;; Compute the amount of space required by a PUSH-BUTTON-PANE.
(defmethod compose-space ((pane push-button-pane) &key width height)
  (let ((x-margin 4)
        (y-margin 2))
  (multiple-value-bind (width height)
      (compute-gadget-label-size pane)
    (make-space-requirement :width  (+ width  (* x-margin 2))
                            :height (+ height (* y-margin 2))))

;; This gets invoked to draw the push button.
(defmethod handle-repaint ((pane push-button-pane) region)
  (declare (ignore region))
  (with-sheet-medium (medium pane)
    (let ((text (gadget-label pane))
          (text-style (slot-value pane 'text-style))
          (armed (slot-value pane 'armed))
          (region (sheet-region pane)))
      (multiple-value-call #'draw-rectangle*
        medium (bounding-rectangle* (sheet-region pane))
        :filled nil)
      (draw-text medium text (bounding-rectangle-center region)
                 :text-style text-style
                 :align-x ':center :align-y ':center)
      (when (eql armed ':button-press)
        (highlight-button pane medium)))))

(defmethod handle-event :around ((pane push-button-pane) (event pointer-event))
  (when (gadget-active-p pane)
    (call-next-method)))

;; When we enter the push button's region, arm it.  If there is a pointer
;; button down, make the button active as well.
(defmethod handle-event ((pane push-button-pane) (event pointer-enter-event))
  (with-slots (armed) pane
    (unless armed
      (cond ((let ((pointer (pointer-event-pointer event)))
               (and (pointer-button-state pointer)
                    (not (zerop (pointer-button-state pointer)))))
             (setf armed :active)
             (with-sheet-medium (medium pane)
               (highlight-button pane medium)))
            (t (setf armed t)))
      (armed-callback pane (gadget-client pane) (gadget-id pane)))))

;; When we leave the push button's region, disarm it.
(defmethod handle-event ((pane push-button-pane) (event pointer-exit-event))
  (with-slots (armed) pane
    (when armed
      (when (prog1 (eq armed :active) (setf armed nil))
        (with-sheet-medium (medium pane)
          (highlight-button pane medium)))
      (disarmed-callback pane (gadget-client pane) (gadget-id pane)))))

;; When the user presses a pointer button, ensure that the button
;; is armed, and highlight it. 
(defmethod handle-event ((pane push-button-pane) (event pointer-button-press-event))
  (with-slots (armed) pane
    (when armed
      (setf armed :active)
      (with-sheet-medium (medium pane)
        (highlight-button pane medium)))))

;; When the user releases the button and the button is still armed,
;; call the activate callback.
(defmethod handle-event ((pane push-button-pane) (event pointer-button-release-event))
  (with-slots (armed) pane
    (when (eq armed :active)
      (setf armed t)
      (with-sheet-medium (medium pane)
        (highlight-button pane medium))
      (activate-callback pane (gadget-client pane) (gadget-id pane)))))
")
      (:PAR) " "))
    (:SECTION :TITLE ("30.3 " "Basic Gadget Classes") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "The following are the basic gadget classes upon which all gadgets are built." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to a gadget, a subclass of " (:CL "pane")
      ". If you want to create a new class that behaves like a gadget, it should be a subclass of " (:CL "gadget")
      ". All instantiable subclasses of " (:CL "gadget") " must obey the gadget protocol. " (:PAR)
      "All of the subclasses of " (:CL "gadget") " are mutable." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadgetp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a " (:TERM "gadget")
      ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "basic-gadget")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The basic class on which all CLIM gadgets are built, a subclass of " (:CL "gadget")
      ". This class is an abstract class, intended only to be subclassed, not instantiated. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":id")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":client")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":armed-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":disarmed-callback")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "gadget")
      " must handle these four initargs, which are used to specify, respectively, the gadget id, client, armed callback, and disarmed callback of the gadget."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-id")) :PARAMS ((:I "gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf gadget-id)")) :PARAMS ((:I "id gadget")) :KIND ("Generic Function")) (:PAR)
      "Returns (or sets) the gadget id of the gadget " (:GROUP (:FONT :FACE :I) "gadget")
      ". The id is typically a simple Lisp object that uniquely identifies the gadgets." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-client")) :PARAMS ((:I "gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf gadget-client)")) :PARAMS ((:I "client gadget")) :KIND ("Generic Function"))
      (:PAR) "Returns the client of the gadget " (:GROUP (:FONT :FACE :I) "gadget")
      ". The client is often an application frame, but it could be another gadget (for example, in the case of a push button that is contained in a radio box, the client of the button could be the radio box)."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-armed-callback")) :PARAMS ((:I "gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "gadget-disarmed-callback")) :PARAMS ((:I "gadget")) :KIND ("Generic Function")) (:PAR)
      "Returns the functions that will be called when the armed or disarmed callback, respectively, are invoked. These functions will be invoked with a single argument, the gadget."
      (:PAR) "When these functions return " (:CL "nil")
      ", that indicates that there is no armed (or disarmed) callback for the gadget." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "armed-callback")) :PARAMS ((:I "gadget client gadget-id")) :KIND
       ("Callback Generic Function"))
      (:SIGNATURE :NAME ((:CL "disarmed-callback")) :PARAMS ((:I "gadget client gadget-id")) :KIND
       ("Callback Generic Function"))
      (:PAR) "These callbacks are invoked when the gadget " (:GROUP (:FONT :FACE :I) "gadget")
      " is, respectively, armed or disarmed." (:PAR)
      "The exact definition of arming and disarming varies from gadget to gadget, but typically a gadget becomes armed when the pointer is moved into its region, and disarmed when the pointer moves out of its region. A gadget will not call the activate or value-changed callback unless it is armed."
      (:PAR) "The default methods (on " (:CL "basic-gadget") ") call the function stored in "
      (:CL "gadget-armed-callback") " or " (:CL "gadget-disarmed-callback") " with one argument, the gadget." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "activate-gadget")) :PARAMS ((:I "gadget")) :KIND ("Generic Function")) (:PAR)
      "Causes the host gadget to become active, that is, available for input." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "deactivate-gadget")) :PARAMS ((:I "gadget")) :KIND ("Generic Function")) (:PAR)
      "Causes the host gadget to become inactive, that is, unavailable for input. In some environments this may cause the gadget to become grayed over; in others, no visual effect may be detected."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-active-p")) :PARAMS ((:I "gadget")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:CL "t") " if the gadget " (:GROUP (:FONT :FACE :I) "gadget")
      " is active (that is, has been activated with " (:CL "activate-gadget") "), otherwise returns " (:CL "nil") "."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "note-gadget-activated")) :PARAMS ((:I "client gadget")) :KIND ("Generic Function"))
      (:PAR)
      "This function is invoked after a gadget is made active. It is intended to allow the client of the gadget to notice when the gadget has been activated."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "note-gadget-deactivated")) :PARAMS ((:I "client gadget")) :KIND ("Generic Function"))
      (:PAR)
      "This function is invoked after a gadget is made inactive. It is intended to allow the client of the gadget to notice when the gadget has been activated. For instance, when the client is an application frame, the frame may invoke the frame manager to \"gray out\" deactivated gadgets."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "value-gadget")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The class used by gadgets that have a value; a subclass of " (:CL "basic-gadget")
      ". This class is an abstract class, intended only to be subclassed, not instantiated. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":value")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":value-changed-callback")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "value-gadget")
      " must handle these two initargs, which are used to specify, respectively, the initial value and the value changed callback of the gadget."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "value-gadget")) :KIND ("Generic Function")) (:PAR)
      "Returns the value of the gadget " (:GROUP (:FONT :FACE :I) "value-gadget")
      ". The interpretation of the value varies from gadget to gadget. For example, a scroll bar's value might be a number between 0 and 1, while a toggle button's value is either "
      (:CL "t") " or " (:CL "nil")
      ". (The documentation of each individual gadget below specifies how to interpret the value.)" (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "(setf gadget-value)")) :PARAMS
       ((:I "value value-gadget " (:GROUP (:FONT :FACE :TT) "&key ") "invoke-callback")) :KIND ("Generic Function"))
      (:PAR) "Sets the gadget's value to the specified value." (:PAR) "If " (:GROUP (:FONT :FACE :I) "invoke-callback")
      " is " (:TERM "true") ", the value changed callback for the gadget is invoked. The default is " (:TERM "false")
      ". The syntax for using " (:CL "(setf gadget-value)") " in conjunction with "
      (:GROUP (:FONT :FACE :I) "invoke-callback") " is:" (:PAR)
      (:PRE "
(setf (gadget-value gadget :invoke-callback t) new-value)
")
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "gadget-value-changed-callback")) :PARAMS ((:I "value-gadget")) :KIND
       ("Generic Function"))
      (:PAR)
      "Returns the function that will be called when the value changed callback is invoked. This function will be invoked with a two arguments, the gadget and the new value."
      (:PAR) "When this function returns " (:CL "nil")
      ", that indicates that there is no value changed callback for the gadget." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "value-changed-callback")) :PARAMS ((:I "value-gadget client gadget-id value")) :KIND
       ("Callback Generic Function"))
      (:PAR) "This callback is invoked when the value of a gadget is changed, either by the user or programatically."
      (:PAR) "The default method (on " (:CL "value-gadget") ") calls the function stored in "
      (:CL "gadget-value-changed-callback") " with two arguments, the gadget and the new value." (:PAR)
      "CLIM implementations must implement or inherit a method for " (:CL "value-changed-callback")
      " for every gadget that is a subclass of " (:CL "value-gadget") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "action-gadget")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The class used by gadgets that perform some kind of action, such as a push button; a subclass of "
      (:CL "basic-gadget") ". This class is an abstract class, intended only to be subclassed, not instantiated. "
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":activate-callback")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "All subclasses of " (:CL "action-gadget")
      " must handle this initarg, which is used to specify the activate callback of the gadget." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "gadget-activate-callback")) :PARAMS ((:I "action-gadget")) :KIND ("Generic Function"))
      (:PAR)
      "Returns the function that will be called when the gadget is activated. This function will be invoked with one argument, the gadget."
      (:PAR) "When this function returns " (:CL "nil")
      ", that indicates that there is no value activate callback for the gadget." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "activate-callback")) :PARAMS ((:I "action-gadget client gadget-id")) :KIND
       ("Callback Generic Function"))
      (:PAR) "This callback is invoked when the gadget is activated." (:PAR) "The default method (on "
      (:CL "action-gadget") ") calls the function stored in " (:CL "gadget-activate-callback")
      " with one argument, the gadget." (:PAR) "CLIM implementations must implement or inherit a method for "
      (:CL "activate-callback") " for every gadget that is a subclass of " (:CL "action-gadget") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "oriented-gadget-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The class that is mixed in to a gadget that has an orientation associated with it, for example, a slider. This class is not intended to be instantiated."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":orientation")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "oriented-gadget-mixin")
      " must handle this initarg, which is used to specify the orientation of the gadget." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "gadget-orientation")) :PARAMS ((:I "oriented-gadget")) :KIND ("Generic Function"))
      (:PAR) "Returns the orientation of the gadget " (:GROUP (:FONT :FACE :I) "oriented-gadget")
      ". Typically, this will be a keyword such as " (:CL ":horizontal") " or " (:CL ":vertical") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "labelled-gadget-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The class that is mixed in to a gadget that has a label, for example, a push button. This class is not intended to be instantiated."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":label")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":align-x")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":align-y")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "labelled-gadget-mixin") " must handle these initargs, which are used to specify the label, and its "
      (:MATH "x") " and " (:MATH "y")
      " alignment. Labelled gadgets will also have a text style for the label, but this is managed by the usual text style mechanism for panes."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-label")) :PARAMS ((:I "labelled-gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf gadget-label)")) :PARAMS ((:I "label labelled-gadget")) :KIND
       ("Generic Function"))
      (:PAR) "Returns (or sets) the label of the gadget " (:GROUP (:FONT :FACE :I) "labelled-gadget")
      ". The label must be a string. Changing the label of a gadget may result in invoking the layout protocol on the gadget and its ancestor sheets."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "gadget-label-align-x")) :PARAMS ((:I "labelled-gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf gadget-label-align-x)")) :PARAMS ((:I "alignment labelled-gadget")) :KIND
       ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "gadget-label-align-y")) :PARAMS ((:I "labelled-gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf gadget-label-align-y)")) :PARAMS ((:I "alignment labelled-gadget")) :KIND
       ("Generic Function"))
      (:PAR) "Returns (or sets) the alignment of the label of the gadget " (:GROUP (:FONT :FACE :I) "labelled-gadget")
      ". Changing the alignment a gadget may result in invoking the layout protocol on the gadget and its ancestor sheets."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "range-gadget-mixin")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The class that is mixed in to a gadget that has a range, for example, a slider. This class is not intended to be instantiated."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":min-value")) :PARAMS ((:I)) :KIND ("Initarg"))
      (:SIGNATURE :NAME ((:CL ":max-value")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "All subclasses of "
      (:CL "range-gadget-mixin")
      " must handle these two initargs, which are used to specify the minimum and maximum value of the gadget." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-min-value")) :PARAMS ((:I "range-gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf gadget-min-value)")) :PARAMS ((:I "min-value range-gadget")) :KIND
       ("Generic Function"))
      (:PAR) "Returns (or sets) the minimum value of the gadget " (:GROUP (:FONT :FACE :I) "range-gadget")
      ". It will be a real number." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-max-value")) :PARAMS ((:I "range-gadget")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "(setf gadget-max-value)")) :PARAMS ((:I "max-value range-gadget")) :KIND
       ("Generic Function"))
      (:PAR) "Returns (or sets) the maximum value of the gadget " (:GROUP (:FONT :FACE :I) "range-gadget")
      ". It will be a real number." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-range")) :PARAMS ((:I "range-gadget")) :KIND ("Generic Function")) (:PAR)
      "Returns the range of " (:GROUP (:FONT :FACE :I) "range-gadget")
      ", that is, the difference of the maximum value and the minimum value." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-range*")) :PARAMS ((:I "range-gadget")) :KIND ("Generic Function")) (:PAR)
      "Returns the minimum and maximum values of " (:GROUP (:FONT :FACE :I) "range-gadget") " as two values." (:PAR)
      " "))
    (:SECTION :TITLE ("30.4 " "Abstract Gadget Classes") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "CLIM supplies a set of abstract gadgets that have been designed to be compatible with with a variety of user interface toolkits, including Xt widget-based toolkits (such as Motif), OpenLook, and MacApp and MicroSoft Windows."
     (:PAR)
     "CLIM's \"concrete\" gadget classes will all be subclasses of these abstract gadget classes. Each concrete gadget maps to an implementation-specific object that is managed by the underlying toolkit. For example, while a CLIM program manipulates an object of class "
     (:CL "scroll-bar") ", the underlying implementation-specific object might be an Xt widget of type "
     (:CL "Xm_Scroll_Bar")
     ". As events are processed on the underlying object the corresponding generic operations are applied to the Lisp gadget."
     (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
     (:GROUP (:FONT :FACE :SL) "Do we want to define something like " (:CL "gadget-handle")
      " that is a documented way to get ahold of the underlying toolkit object? --- ILA")
     (:PAR)
     "Note that not all operations will necessarily be generated by particular toolkit implementations. For example, a user interface toolkit that is designed for a 3-button mouse may generate significantly more gadget events than one designed for a 1-button mouse."
     (:PAR) (:PAR) " "
     (:SECTION :TITLE ("30.4.1 " "The " (:GROUP (:FONT :FACE :TT) "push-button") " Gadget") :KIND :SUBSECTION :NAME
      (9 5 4 10) (:PAR) "The " (:CL "push-button") " gadget provides press-to-activate switch behavior." (:PAR)
      (:CL "arm-callback")
      " will be invoked when the push button becomes armed (such as when the pointer moves into it, or a pointer button is pressed over it). When the button is actually activated (by releasing the pointer button over it), "
      (:CL "activate-callback") " will be invoked. Finally, " (:CL "disarm-callback") " will be invoked after "
      (:CL "activate-callback") ", or when the pointer is moved outside of the button." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "push-button")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract push button. It is a subclass of " (:CL "action-gadget")
       " and " (:CL "labelled-gadget-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":show-as-default")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "This is used to initialize the \"show as default\" property for the gadget, described below." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "push-button-show-as-default")) :PARAMS ((:I "push-button")) :KIND ("Generic Function"))
       (:PAR) "Returns the \"show as default\" property for the push button gadget. When " (:TERM "true")
       ", the push button will be drawn with a heavy border, which indicates that this button is the \"default operation\"."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "push-button-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable push button; a subclass of " (:CL "push-button") "." (:PAR)
       " "))
     (:SECTION :TITLE ("30.4.2 " "The " (:GROUP (:FONT :FACE :TT) "toggle-button") " Gadget") :KIND :SUBSECTION :NAME
      (9 5 4 10) (:PAR) "The " (:CL "toggle-button")
      " gadget provides \"on/off\" switch behavior. This gadget typically appears as a box that is optionally highlighted with a check-mark. If the check-mark is present, the gadget's value is "
      (:CL "t") ", otherwise it is " (:CL "nil") "." (:PAR) (:CL "arm-callback")
      " will be invoked when the toggle button becomes armed (such as when the pointer moves into it, or a pointer button is pressed over it). When the toggle button is actually activated (by releasing the pointer button over it), "
      (:CL "value-changed-callback") " will be invoked. Finally, " (:CL "disarm-callback") " will be invoked after "
      (:CL "value-changed-callback") ", or when the pointer is moved outside of the toggle button." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "toggle-button")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract toggle button. It is a subclass of " (:CL "value-gadget")
       " and " (:CL "labelled-gadget-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":indicator-type")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "This is used to initialize the indicator type property for the gadget, described below." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "toggle-button-indicator-type")) :PARAMS ((:I "toggle-button")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the indicator type for the toggle button. This will be either " (:CL ":one-of") " or "
       (:CL ":some-of")
       ". The indicator type controls the appearance of the toggle button. For example, many toolkits present a one-of-many choice differently from a some-of-many choice."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "toggle-button") ")")) :KIND ("Method"))
       (:PAR) "Returns " (:TERM "true") " if the button is selected, otherwise returns " (:TERM "false") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "toggle-button-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable toggle button; a subclass of " (:CL "toggle-button") "."
       (:PAR) " "))
     (:SECTION :TITLE ("30.4.3 " "The " (:GROUP (:FONT :FACE :TT) "menu-button") " Gadget") :KIND :SUBSECTION :NAME
      (9 5 4 10) (:PAR) "The " (:CL "menu-button") " gadget provides similar behavior to the " (:CL "toggle-button")
      " gadget, except that it is intended for items in menus. The returned value is generally the item chosen from the menu."
      (:PAR) (:CL "arm-callback")
      " will be invoked when the menu button becomes armed (such as when the pointer moves into it, or a pointer button is pressed over it). When the menu button is actually activated (by releasing the pointer button over it), "
      (:CL "value-changed-callback") " will be invoked. Finally, " (:CL "disarm-callback") " will be invoked after "
      (:CL "value-changed-callback") ", or when the pointer is moved outside of the menu button." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "menu-button")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract menu button. It is a subclass of " (:CL "value-gadget")
       " and " (:CL "labelled-gadget-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "menu-button-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable menu button; a subclass of " (:CL "menu-button") "." (:PAR)
       " "))
     (:SECTION :TITLE ("30.4.4 " "The " (:GROUP (:FONT :FACE :TT) "scroll-bar") " Gadget") :KIND :SUBSECTION :NAME
      (9 5 4 10) (:PAR) "The " (:CL "scroll-bar") " gadget corresponds to a scroll bar." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "scroll-bar")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract scroll bar. This is a subclass of " (:CL "value-gadget")
       ", " (:CL "oriented-gadget-mixin") ", and " (:CL "range-gadget-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":drag-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":scroll-to-bottom-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":scroll-to-top-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":scroll-down-line-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":scroll-up-line-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":scroll-down-page-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":scroll-up-page-callback")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "Specifies the drag and other scrolling callbacks for the scroll bar." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "scroll-bar-drag-callback")) :PARAMS ((:I "scroll-bar")) :KIND ("Generic Function"))
       (:PAR)
       "Returns the function that will be called when the indicator of the scroll bar is dragged. This function will be invoked with a two arguments, the scroll bar and the new value."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "scroll-bar-scroll-to-bottom-callback")) :PARAMS ((:I "scroll-bar")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-bar-scroll-to-top-callback")) :PARAMS ((:I "scroll-bar")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-bar-scroll-down-line-callback")) :PARAMS ((:I "scroll-bar")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-bar-scroll-up-line-callback")) :PARAMS ((:I "scroll-bar")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-bar-scroll-down-page-callback")) :PARAMS ((:I "scroll-bar")) :KIND
        ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-bar-scroll-up-page-callback")) :PARAMS ((:I "scroll-bar")) :KIND
        ("Generic Function"))
       (:PAR)
       "Returns the functions that will be used as callbacks when various parts of the scroll bar are clicked on. These are all functions of a single argument, the scroll bar."
       (:PAR) "When any of these functions returns " (:CL "nil")
       ", that indicates that there is no callback of that type for the gadget." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "drag-callback")) :PARAMS ((:I "scroll-bar client gadget-id value")) :KIND
        ("Callback Generic Function"))
       (:PAR)
       "This callback is invoked when the value of the scroll bar is changed while the indicator is being dragged. This is implemented by calling the function stored in "
       (:CL "scroll-bar-drag-callback") " with two arguments, the scroll bar and the new value." (:PAR) "The "
       (:CL "value-changed-callback") " is invoked only after the indicator is released after dragging it." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "scroll-to-top-callback")) :PARAMS ((:I "scroll-bar client gadget-id")) :KIND
        ("Callback Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-to-bottom-callback")) :PARAMS ((:I "scroll-bar client gadget-id")) :KIND
        ("Callback Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-up-line-callback")) :PARAMS ((:I "scroll-bar client gadget-id")) :KIND
        ("Callback Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-up-page-callback")) :PARAMS ((:I "scroll-bar client gadget-id")) :KIND
        ("Callback Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-down-line-callback")) :PARAMS ((:I "scroll-bar client gadget-id")) :KIND
        ("Callback Generic Function"))
       (:SIGNATURE :NAME ((:CL "scroll-down-page-callback")) :PARAMS ((:I "scroll-bar client gadget-id")) :KIND
        ("Callback Generic Function"))
       (:PAR)
       "All of the callbacks above are invoked when appropriate parts of the scroll bar are clicked on. Note that each implementation may not have \"hot spots\" corresponding to each of these callbacks."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "scroll-bar") ")")) :KIND ("Method"))
       (:PAR) "Returns a real number within the specified range." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "scroll-bar-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable scroll bar; a subclass of " (:CL "scroll-bar") "." (:PAR)
       " "))
     (:SECTION :TITLE ("30.4.5 " "The " (:GROUP (:FONT :FACE :TT) "slider") " Gadget") :KIND :SUBSECTION :NAME
      (9 5 4 10) (:PAR) "The " (:CL "slider") " gadget corresponds to a slider." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "slider")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract slider. This is a subclass of " (:CL "value-gadget") ", "
       (:CL "oriented-gadget-mixin") ", " (:CL "range-gadget-mixin") ", and " (:CL "labelled-gadget-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":drag-callback")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":show-value-p")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":decimal-places")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "Specifies the drag callback for the slider, whether the slider should show its current value, and how many decimal places to the right of the decimal point should be displayed when the slider is showing its current value."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":min-label")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":max-label")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":range-label-text-style")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "Specifies a label to be used at the low end and high end of the sldier, and what the text style of those labels should be."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":number-of-tick-marks")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":number-of-quanta")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "Specifies the number of tick marks that should be drawn on the scroll bar, and the number of quanta in the scroll bar. If the scroll bar is quantized, the scroll bar will consist of discrete values rather than continuous values."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-show-value-p")) :PARAMS ((:I "slider")) :KIND ("Generic Function"))
       (:PAR) "Returns " (:TERM "true") " if the slider shows its value, otherwise returns " (:TERM "false") (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "slider-drag-callback")) :PARAMS ((:I "slider")) :KIND ("Generic Function"))
       (:PAR)
       "Returns the function that will be called when the indicator of the slider is dragged. This function will be invoked with a two arguments, the slider and the new value."
       (:PAR) "When this function returns " (:CL "nil")
       ", that indicates that there is no drag callback for the gadget." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "drag-callback")) :PARAMS ((:I "slider client gadget-id value")) :KIND
        ("Callback Generic Function"))
       (:PAR)
       "This callback is invoked when the value of the slider is changed while the indicator is being dragged. This is implemented by calling the function stored in "
       (:CL "slider-drag-callback") " with two arguments, the slider and the new value." (:PAR) "The "
       (:CL "value-changed-callback") " is invoked only after the indicator is released after dragging it." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "slider") ")")) :KIND ("Method"))
       (:PAR) "Returns a real number within the specified range." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "slider-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable slider; a subclass of " (:CL "slider") "." (:PAR) " "))
     (:SECTION :TITLE
      ("30.4.6 " "The " (:GROUP (:FONT :FACE :TT) "radio-box") " and " (:GROUP (:FONT :FACE :TT) "check-box")
       " Gadgets")
      :KIND :SUBSECTION :NAME (9 5 4 10) (:PAR)
      "Radio boxes and check boxes are special kinds of gadgets that constrain one or more toggle buttons. At any one time, only one of the buttons managed by the radio box, or zero or more of the buttons managed by a check box, may be \"on\". The contents of a radio box or a check box are its buttons, and as such a radio box or check bnox is responsible for laying out the buttons that it contains. A radio box or check box is a client of each of its buttons so that the value of the radio or check box can be properly computed."
      (:PAR)
      "As the current selection changes, the previously selected button and the newly selected button both have their "
      (:CL "value-changed-callback") " handlers invoked." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "radio-box")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract radio box, that is, a gadget that constrains a number of toggle buttons, only one of which may be selected at any one time. It is a subclass of "
       (:CL "value-gadget") " and " (:CL "oriented-gadget-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":current-selection")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "This is used to specify which button, if any, should be initially selected." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "radio-box-current-selection")) :PARAMS ((:I "radio-box")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf radio-box-current-selection)")) :PARAMS ((:I "button radio-box")) :KIND
        ("Generic Function"))
       (:PAR)
       "Returns (or sets) the current selection for the radio box. The current selection will be one of the toggle buttons in the box."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "radio-box-selections")) :PARAMS ((:I "radio-box")) :KIND ("Generic Function"))
       (:PAR)
       "Returns a sequence of all of the selections in the radio box. The elements of the sequence will be toggle buttons."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "radio-box") ")")) :KIND ("Method"))
       (:PAR) "Returns the selected button. This will return the same value as " (:CL "radio-box-current-selection")
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "radio-box-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable radio box; a subclass of " (:CL "radio-box") "." (:PAR) " ")
      (:DEFUN (:SIGNATURE :NAME ((:CL "check-box")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract check box, that is, a gadget that constrains a number of toggle buttons, zero or more of which may be selected at any one time. It is a subclass of "
       (:CL "value-gadget") " and " (:CL "oriented-gadget-mixin") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":current-selection")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "This is used to specify which buttons, if any, should be initially selected." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "check-box-current-selection")) :PARAMS ((:I "check-box")) :KIND ("Generic Function"))
       (:SIGNATURE :NAME ((:CL "(setf check-box-current-selection)")) :PARAMS ((:I "button check-box")) :KIND
        ("Generic Function"))
       (:PAR)
       "Returns (or sets) the current selection for the check box. The current selection will be a list of zero or more of the toggle buttons in the box."
       (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "check-box-selections")) :PARAMS ((:I "check-box")) :KIND ("Generic Function"))
       (:PAR)
       "Returns a sequence of all of the selections in the check box. The elements of the sequence will be toggle buttons."
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "check-box") ")")) :KIND ("Method"))
       (:PAR) "Returns the selected buttons as a list. This will return the same value as "
       (:CL "check-box-current-selection") (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "check-box-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable check box; a subclass of " (:CL "check-box") "." (:PAR) " ")
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "with-radio-box")) :PARAMS
        ((:I "(" (:GROUP (:FONT :FACE :TT) "&rest ") "options " (:GROUP (:FONT :FACE :TT) "&key ") "(type "
          (:CL ":one-of") ") " (:GROUP (:FONT :FACE :TT) "&allow-other-keys ") ") " (:GROUP (:FONT :FACE :TT) "&body ")
          "body"))
        :KIND ("Macro"))
       (:PAR) "Creates a radio box whose buttons are created by the forms in " (:GROUP (:FONT :FACE :I) "body")
       ". The macro " (:CL "radio-box-current-selection") " can be wrapped around one of forms in "
       (:GROUP (:FONT :FACE :I) "body") " in order to indicate that that button is the current selection." (:PAR) "If "
       (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":one-of") ", a " (:CL "radio-box") " will be created. If "
       (:GROUP (:FONT :FACE :I) "type") " is " (:CL ":some-of") ", a " (:CL "check-box") " will be created." (:PAR)
       "For example, the following creates a radio box with three buttons in it, the second of which is initially selected."
       (:PAR)
       (:PRE "
(with-radio-box ()
  (make-pane 'toggle-button :label \"Mono\")
  (radio-box-current-selection
    (make-pane 'toggle-button :label \"Stereo\"))
  (make-pane 'toggle-button :label \"Quad\"))
")
       (:PAR)
       "The following simpler form can also be used when the programmer does not need to control the appearance of each button closely."
       (:PAR)
       (:PRE "
(with-radio-box ()
  \"Mono\" \"Stereo\" \"Quad\")
")
       (:PAR) " "))
     (:SECTION :TITLE
      ("30.4.7 " "The " (:GROUP (:FONT :FACE :TT) "list-pane") " and " (:GROUP (:FONT :FACE :TT) "option-pane")
       " Gadgets")
      :KIND :SUBSECTION :NAME (9 5 4 10) (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "list-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract list pane, that is, a gadget whose semantics are similar to a radio box or check box, but whose visual appearance is a list of buttons. It is a subclass of "
       (:CL "value-gadget") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":mode")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "Either "
       (:CL ":nonexclusive") " or " (:CL ":exclusive") ". When it is " (:CL ":exclusive")
       ", the list pane acts like a radio box, that is, only a single item can be selected. Otherwise, the list pane acts like a check box, in that zero or more items can be selected. The default is "
       (:CL ":exclusive") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":items")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":name-key")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":value-key")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":test")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "The " (:CL ":items")
       " initarg specifies a sequence of items to use as the items of the list pane. The name of the item is extracted by the function that is the value of the "
       (:CL ":name-key") " initarg, which defaults to " (:CL "princ-to-string")
       ". The value of the item is extracted by the function that is the value of the " (:CL ":value-key")
       " initarg, which defaults to " (:CL "identity") ". The " (:CL ":test")
       " initarg specifies a function of two arguments that is used to compare items; it defaults to " (:CL "eql") "."
       (:PAR) "For example," (:PAR)
       (:PRE "
(make-pane 'list-pane
  :value '(\"Lisp\" \"C++\")
  :mode :nonexclusive
  :items '(\"Lisp\" \"Fortran\" \"C\" \"C++\" \"Cobol\" \"Ada\")
  :test 'string=)
")
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "list-pane") ")")) :KIND ("Method"))
       (:PAR) "Returns the single selected item when the mode is " (:CL ":exclusive")
       ", or a sequence of selected items when the mode is " (:CL ":nonexclusive") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "generic-list-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable list pane; a subclass of " (:CL "list-pane") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "option-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract option pane, that is, a gadget whose semantics are identical to a list pane, but whose visual appearance is a single push button which, when pressed, pops up a menu of selections.. It is a subclass of "
       (:CL "value-gadget") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":mode")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "Either "
       (:CL ":nonexclusive") " or " (:CL ":exclusive") ". When it is " (:CL ":exclusive")
       ", the option pane acts like a radio box, that is, only a single item can be selected. Otherwise, the option pane acts like a check box, in that zero or more items can be selected. The default is "
       (:CL ":exclusive") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":items")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":name-key")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":value-key")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":test")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR) "The " (:CL ":items")
       " initarg specifies a sequence of items to use as the items of the option pane. The name of the item is extracted by the function that is the value of the "
       (:CL ":name-key") " initarg, which defaults to " (:CL "princ-to-string")
       ". The value of the item is extracted by the function that is the value of the " (:CL ":value-key")
       " initarg, which defaults to " (:CL "identity") ". The " (:CL ":test")
       " initarg specifies a function of two arguments that is used to compare items; it defaults to " (:CL "eql") "."
       (:PAR) "For example," (:PAR)
       (:PRE "
(make-pane 'option-pane
  :value '(\"Lisp\" \"C++\")
  :mode :nonexclusive
  :items '(\"Lisp\" \"Fortran\" \"C\" \"C++\" \"Cobol\" \"Ada\")
  :test 'string=)
")
       (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "option-pane") ")")) :KIND ("Method"))
       (:PAR) "Returns the single selected item when the mode is " (:CL ":exclusive")
       ", or a sequence of selected items when the mode is " (:CL ":nonexclusive") "." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "generic-option-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable option pane; a subclass of " (:CL "option-pane") "." (:PAR)
       " "))
     (:SECTION :TITLE ("30.4.8 " "The " (:GROUP (:FONT :FACE :TT) "text-field") " Gadget") :KIND :SUBSECTION :NAME
      (9 5 4 10) (:PAR) "The " (:CL "text-field") " gadget corresponds to a small field containing text." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "text-field")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract text field. This is a subclass of " (:CL "value-gadget")
       " and " (:CL "action-gadget") "." (:PAR) "The value of a text field is the text string." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":editable-p")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "This is used to specify whether or not the text field may be edited." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "text-field") ")")) :KIND ("Method"))
       (:PAR) "Returns the resulting string." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "text-field-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable text field; a subclass of " (:CL "text-field") "." (:PAR)
       " "))
     (:SECTION :TITLE ("30.4.9 " "The " (:GROUP (:FONT :FACE :TT) "text-editor") " Gadget") :KIND :SUBSECTION :NAME
      (9 5 4 10) (:PAR) "The " (:CL "text-editor")
      " gadget corresponds to a large field containing multiple lines of text." (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "text-editor")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements an abstract large text field. This is a subclass of " (:CL "text-field")
       "." (:PAR) "The value of a text editor is the text string." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL ":ncolumns")) :PARAMS ((:I)) :KIND ("Initarg"))
       (:SIGNATURE :NAME ((:CL ":nlines")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
       "Specifies the width and height of the text editor in columns and number of lines." (:PAR))
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "gadget-value")) :PARAMS ((:I "(button " (:CL "text-editor") ")")) :KIND ("Method"))
       (:PAR) "Returns the resulting string." (:PAR))
      (:DEFUN (:SIGNATURE :NAME ((:CL "text-editor-pane")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
       "The instantiable class that implements a portable text editor; a subclass of " (:CL "text-editor") "." (:PAR)
       " ")))
    (:SECTION :TITLE ("30.5 " "Integrating Gadgets and Output Records") :KIND :SECTION :NAME (5 4 10) (:PAR)
     "In addition to gadget panes, CLIM allows gadgets to be used inside of CLIM stream panes. For instance, an "
     (:CL "accepting-values") " whose fields consist of gadgets may appear in an ordinary CLIM stream pane." (:PAR)
     "Note that many of the functions in the output record protocol must correctly manage the case where there are gadgets contained within output records. For example, "
     (:CL "(setf* output-record-position)")
     " may need to notify the host window system that the toolkit object representing the gadget has moved, "
     (:CL "window-clear") " needs to deactive any gadgets, and so forth." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "gadget-output-record")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "The instantiable class the represents an output record class that contains a gadget. This is a subclass of "
      (:CL "output-record") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-output-as-gadget")) :PARAMS
       ((:I "(stream " (:GROUP (:FONT :FACE :TT) "&rest ") "options) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Invokes " (:GROUP (:FONT :FACE :I) "body")
      " to create a gadget, and then creates a gadget output record that contains the gadget and install's it into the output history of the output recording stream "
      (:GROUP (:FONT :FACE :I) "stream") ". The returned value of " (:GROUP (:FONT :FACE :I) "body")
      " must be the gadget." (:PAR) "The options in " (:GROUP (:FONT :FACE :I) "options")
      " are passed as initargs to the call to " (:CL "invoke-with-new-output-record")
      " that is used to create the gadget output record." (:PAR) "The " (:GROUP (:FONT :FACE :I) "stream")
      " argument is not evaluated, and must be a symbol that is bound to an output recording stream. If "
      (:GROUP (:FONT :FACE :I) "stream") " is " (:CL "t") ", " (:CL "*standard-output*") " is used. "
      (:GROUP (:FONT :FACE :I) "body") " may have zero or more declarations as its first forms." (:PAR)
      "For example, the following could be used to create an output record containing a radio box that itself contains several toggle buttons:"
      (:PAR)
      (:PRE "
(with-output-as-gadget (stream)
  (let* ((radio-box
           (make-pane 'radio-box 
             :client stream :id 'radio-box)))
    (dolist (item sequence)
      (make-pane 'toggle-button 
        :label (princ-to-string (item-name item))
        :value (item-value item)
        :id item :parent radio-box))
    radio-box))
")
      (:PAR)
      "A more complex (and somewhat contrived) example of a push button that calls back into the presentation type system to execute a command might be as follows:"
      (:PAR)
      (:PRE "
(with-output-as-gadget (stream)
  (make-pane 'push-button
    :label \"Click here to exit\"
    :activate-callback
      #'(lambda (button)
          (declare (ignore button))
          (throw-highlighted-presentation
            (make-instance 'standard-presentation
              :object `(com-exit ,*application-frame*)
              :type 'command)
            *input-context*
            (make-instance 'pointer-button-press-event
              :sheet (sheet-parent button)
              :x 0 :y 0
              :modifiers 0
              :button +pointer-left-button+)))))
")
      (:PAR))))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part VIII: " "Appendices") :NAME (10) "  " " "
   (:SECTION :TITLE ("A " "Glossary") :KIND :CHAPTER :NAME (6 10) " " (:LABEL :NAME "glossary") (:PAR) (:PAR)
    (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
    (:GROUP (:FONT :FACE :SL)
     "Fill these in. What glossary entries would it be useful to borrow from the ANSI CL spec? --- SWM")
    (:PAR)
    (:DL (:DT "adaptive toolkit") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "adopted")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "sheet") ") Having a parent sheet." (:PAR))
     (:DT "affine transformation") (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "transformation") "." (:PAR))
     (:DT "ancestors")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The parent of a " (:TERM "sheet") " or an " (:TERM "output record")
      ", and all of its ancestors, recursively." (:PAR))
     (:DT "applicable")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "presentation translator") ") A "
      (:TERM "presentation translator") " is said to be " (:TERM "applicable") " when the pointer is pointing to a "
      (:TERM "presentation") " whose " (:TERM "presentation type") " matches the current " (:TERM "input context")
      ", and the other criteria for translator matching have been met." (:PAR))
     (:DT "application frame")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. A program that interacts directly with a " (:TERM "user")
      " to perform some specific task. 2. A Lisp object that holds the information associated with such a program, including the panes of the user interface and application state variables."
      (:PAR))
     (:DT "area")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "region") " that has dimensionality 2, that is, has area."
      (:PAR))
     (:DT "background")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The " (:TERM "design") " that is used when erasing, that is, drawing using "
      (:CL "+background-ink+") "." (:PAR))
     (:DT "bounded design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design")
      " that is transparent everywhere beyond a certain distance from a certain point. Drawing a bounded design has no effect on the drawing plane outside that distance."
      (:PAR))
     (:DT "bounded region")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "region")
      " that contains at least one point and for which there exists a number, " (:MATH "d")
      ", called the region's diameter, such that if " (:MATH "p" (:RM "1")) " and " (:MATH "p" (:RM "2"))
      " are points in the region, the distance between " (:MATH "p" (:RM "1")) " and " (:MATH "p" (:RM "2"))
      " is always less than or equal to " (:MATH "d") "." (:PAR))
     (:DT "bounding rectangle")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. The smallest " (:TERM "rectangle") " that surrounds a "
      (:TERM "bounded region")
      " and contains every point in the region, and may contain additional points as well. The sides of a bounding rectangle are parallel to the coordinate axes. 2. A Lisp object that represents a "
      (:TERM "bounding rectangle") "." (:PAR))
     (:DT "cache value")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " During " (:TERM "incremental redisplay") ", the " (:TERM "cache value")
      " is used to determine whether or not a piece of output has changed." (:PAR))
     (:DT "children")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " (of a " (:TERM "sheet") " or " (:TERM "output record")
      ") The direct descendants of a " (:TERM "sheet") " or an " (:TERM "output record") "." (:PAR))
     (:DT "color")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. An object representing the intuitive definition of a color, such as black or red. 2. A Lisp object that represents a "
      (:TERM "color") "." (:PAR))
     (:DT "colored design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design") " whose points have " (:TERM "color") "." (:PAR))
     (:DT "colorless design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design") " whose points have no " (:TERM "color")
      ". Drawing a colorless design uses the default color specified by the " (:TERM "medium") "'s foreground design."
      (:PAR))
     (:DT "command")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. The way CLIM represents a user interaction. 2. A Lisp object that represents a " (:TERM "command") "."
      (:PAR))
     (:DT "command name") (:DD (:GROUP (:FONT :FACE :I) "n.") " A symbol that names a command." (:PAR))
     (:DT "command table")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. A way of collecting and organizing a group of related commands, and defining the interaction styles that can be used to invoke those commands. 2. A Lisp object that represents a "
      (:TERM "command table") "." (:PAR))
     (:DT "command table designator")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " A Lisp object that is either a command table or a symbol that names a command table." (:PAR))
     (:DT "completion")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " A facility provided by CLIM for completing user input over a set of possibilities." (:PAR))
     (:DT "compositing")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " (of " (:TERM "designs") ") The creation of a " (:TERM "design")
      " whose appearance at each point is a composite of the appearances of two other designs at that point. There are three varieties of compositing: "
      (:TERM "composing over") ", " (:TERM "composing in") ", and " (:TERM "composing out") "." (:PAR))
     (:DT "composition")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " (of " (:TERM "transformations")
      ") The transformation from one coordinate system to another, then from the second to a third can be represented by a single transformation that is the "
      (:TERM "composition")
      " of the two component transformations. Transformations are closed under composition. Composition is not commutative. Any arbitrary transformation can be built up by composing a number of simpler transformations, but that composition is not unique."
      (:PAR))
     (:DT "context-dependent input") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR))
     (:DT "degrafted")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "sheet") ") Not " (:TERM "grafted") "." (:PAR))
     (:DT "descendants")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " All of the children of a " (:TERM "sheet") " or an " (:TERM "output record")
      ", and all of their descendents, recursively." (:PAR))
     (:DT "design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " An object that represents a way of arranging " (:TERM "colors") " and "
      (:TERM "opacities") " in the " (:TERM "drawing plane") ". A mapping from an " (:MATH "(x,y)")
      " pair into color and opacity values." (:PAR))
     (:DT "device transformation") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "disowned")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "sheet") ") Not " (:TERM "adopted") "." (:PAR))
     (:DT "disabled")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "sheet") ") Not " (:TERM "enabled") "." (:PAR))
     (:DT "dispatching") (:DD (:GROUP (:FONT :FACE :I) "n.") " (of " (:TERM "events") ") ---Fill this in---" (:PAR))
     (:DT "display medium") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "display server")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "displayed output record")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " An " (:TERM "output record")
      " that corresponds to a visible piece of output, such as text or graphics. The leaves of the output record tree."
      (:PAR))
     (:DT "distributing") (:DD (:GROUP (:FONT :FACE :I) "n.") " (of " (:TERM "events") ") ---Fill this in---" (:PAR))
     (:DT "drawing plane")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " An infinite two-dimensional plane on which graphical output occurs. A drawing plane contains an arrangement of colors and opacities that is modified by each graphical output operation."
      (:PAR))
     (:DT "enabled") (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "sheet") ") ---Fill this in---" (:PAR))
     (:DT "event")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. Some sort of significant event, such as a user gesture (such as moving the pointer, pressing a pointer button, or typing a keystroke) or a window configuration event (such as resizing a window). 2. A Lisp object that represents an "
      (:TERM "event") "." (:PAR))
     (:DT "extended input stream")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " A kind of sheet that supports CLIM's extended input stream protocol, such as supporting a pointing device."
      (:PAR))
     (:DT "extended output stream")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " A kind of sheet that supports CLIM's extended output stream protocol, such as supporting a variable line-height text rendering."
      (:PAR))
     (:DT "false")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. The boolean value false. 2. The Lisp object " (:CL "nil") "." (:PAR))
     (:DT "flipping ink")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. An " (:TERM "ink") " that interchanges occurrences of two "
      (:TERM "designs")
      ", such as might be done by \"XOR\" on a monochrome display. 2. A Lisp object that represents a "
      (:TERM "flipping ink") "." (:PAR))
     (:DT "foreground")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The " (:TERM "design") " that is used when drawing using "
      (:CL "+foreground-ink+") "." (:PAR))
     (:DT "formatted output")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. Output that obeys some high level constraints on its appearance, such as being arranged in a tabular format, or justified within some margins. 2. The CLIM facility that provides a programmer the tools to produce such output."
      (:PAR))
     (:DT "frame") (:DD (:GROUP (:FONT :FACE :I) "n.") " An " (:TERM "application frame") "." (:PAR))
     (:DT "frame manager")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " An object that controls the realization of the look and feel of an "
      (:TERM "application frame") "." (:PAR))
     (:DT "fully specified")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "text style") ") Having components none of which are "
      (:CL "nil") ", and not having a relative size (that is, neither " (:CL ":smaller") " nor " (:CL ":larger") ")."
      (:PAR))
     (:DT "gesture")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " Some sort of input action by a user, such as typing a character or clicking a pointer button." (:PAR))
     (:DT "gesture name")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A symbol that gives a name to a " (:TERM "gesture") ", for example, "
      (:CL ":select") " is commonly used to indicate a left pointer button click." (:PAR))
     (:DT "graft")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A kind of " (:TERM "mirrored sheet")
      " that represents a host window, typically a root window." (:PAR))
     (:DT "grafted")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "sheet") ") Having an ancestor sheet that is a "
      (:TERM "graft") "." (:PAR))
     (:DT "highlighting")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " Changing of some piece of output so that it stands out. CLIM often "
      (:TERM "highlights") " the " (:TERM "presentation") " under the " (:TERM "pointer") " to indicate that it is "
      (:TERM "sensitive") "." (:PAR))
     (:DT "immutable")
     (:DD (:GROUP (:FONT :FACE :I) "adj.")
      " 1. (of an object) Having components that cannot be modified once the object has been created. 2. (of a class) An "
      (:TERM "immutable class") " is a class all of whose objects are " (:TERM "immutable") "." (:PAR))
     (:DT "implementor") (:DD (:GROUP (:FONT :FACE :I) "n.") " A programmer who implements CLIM." (:PAR))
     (:DT "incremental redisplay")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. Redraw part of some output while leaving other output unchanged. 2. The CLIM facility that implements this behavior."
      (:PAR))
     (:DT "indirect ink")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " Drawing with an " (:TERM "indirect ink")
      " is the same as drawing with another " (:TERM "ink") " named directly." (:PAR))
     (:DT "ink")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " Any member of the class " (:CL "design") " supplied as the " (:CL ":ink")
      " argument to a CLIM drawing function." (:PAR))
     (:DT "input context")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. ---Fill this in---. 2. A Lisp object that represents an "
      (:TERM "input context") "." (:PAR))
     (:DT "input editor")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The CLIM facility that allows a " (:TERM "user")
      " to modify typed-in input." (:PAR))
     (:DT "input editing stream")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A CLIM stream that supports " (:TERM "input editing") "." (:PAR))
     (:DT "input stream designator")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A Lisp object that is either an input stream, or the symbol " (:CL "t")
      ", which is taken to mean " (:CL "*standard-input*") "." (:PAR))
     (:DT "interactive stream")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " A stream that supports both input from and output to the user in an interactive fashion." (:PAR))
     (:DT "line style")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. Advice to CLIM's rendering substrate on how to render a path, such as a line or an unfilled ellipse or polygon. 2. A Lisp object that represents a "
      (:TERM "line style") "." (:PAR))
     (:DT "medium")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. A destination for output, having a " (:TERM "drawing plane")
      ", two designs called the medium's " (:TERM "foreground") " and " (:TERM "background") ", a "
      (:TERM "transformation") ", a " (:TERM "clipping region") ", a " (:TERM "line style") ", and a "
      (:TERM "text style") ". 2. A Lisp object that represents a " (:TERM "medium") "." (:PAR))
     (:DT "mirror")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The host window system object associated with a " (:TERM "mirrored sheet")
      ", such as a window object on an X11 display server." (:PAR))
     (:DT "mirrored sheet")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A special class of " (:TERM "sheet")
      " that is attached directly to a window on a " (:TERM "display server") ". A " (:TERM "graft")
      " is one kind of a " (:TERM "mirrored sheet") "." (:PAR))
     (:DT "mutable")
     (:DD (:GROUP (:FONT :FACE :I) "adj.")
      " 1. (of an object) Having components that can be modified once the object has been created. 2. (of a class) An "
      (:TERM "mutable class") " is a class all of whose objects are " (:TERM "mutable") "." (:PAR))
     (:DT "non-uniform design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design") " that is not a " (:TERM "uniform design") "." (:PAR))
     (:DT "opacity")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. An object that controls how graphical output covers previous output, such as fully opaque to fully transparent, and levels of translucency between. 2. A Lisp object that represents an "
      (:TERM "opacity") "." (:PAR))
     (:DT "output history")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The highest level " (:TERM "output record") " for an "
      (:TERM "output recording stream") "." (:PAR))
     (:DT "output record")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. An object that remembers the output performed to a " (:TERM "stream")
      " or " (:TERM "medium") ". 2. A Lisp object that represents an " (:TERM "output record") "." (:PAR))
     (:DT "output recording")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The process of remembering the output performed to a " (:TERM "stream") "."
      (:PAR))
     (:DT "output recording stream")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A CLIM stream that supports " (:TERM "output recording") "." (:PAR))
     (:DT "output stream designator")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A Lisp object that is either an output stream, or the symbol " (:CL "t")
      ", which is taken to mean " (:CL "*standard-output*") "." (:PAR))
     (:DT "pane")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "sheet")
      " or window that appears as the child of some other window or " (:TERM "frame")
      ". A composite pane can hold other panes; a leaf pane cannot." (:PAR))
     (:DT "parent")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The direct ancestor of a " (:TERM "sheet") " or an " (:TERM "output record")
      "." (:PAR))
     (:DT "path")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "region") " that has dimensionality 1, that is, has length."
      (:PAR))
     (:DT "patterning")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The process of creating a bounded rectangular arrangement of "
      (:TERM "designs") ", like a checkerboard. A " (:TERM "pattern") " is a " (:TERM "design")
      " created by this process." (:PAR))
     (:DT "pixmap")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " An \"off-screen window\", that is, a sheet that can be used for graphical output, but is not visible on any display device."
      (:PAR))
     (:DT "point")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. A " (:TERM "region")
      " that has dimensionality 0, that is, has only a position. 2. A Lisp object that represents a " (:TERM "point")
      "." (:PAR))
     (:DT "pointer")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A physical device used for pointing, such as a mouse." (:PAR))
     (:DT "pointer documentation") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "port")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " An abstract connection to a " (:TERM "display server")
      " that is responsible for managing host display server resources and for processing input events received from the host display server."
      (:PAR))
     (:DT "position")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. A position on a plane, such as CLIM's abstract drawing plane. 2. A pair of real number values " (:MATH "x")
      " and " (:MATH "y") " that represent a " (:TERM "position") "." (:PAR))
     (:DT "presentation")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. An association between an object and a " (:TERM "presentation type")
      " with some output on a " (:TERM "output recording stream") ". 2. A Lisp object that represents a "
      (:TERM "presentation") "." (:PAR))
     (:DT "presentation tester")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A predicate that restricts the applicability of a "
      (:TERM "presentation translator") "." (:PAR))
     (:DT "presentation translator")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A mapping from an object of one " (:TERM "presentation type") ", an "
      (:TERM "input context") ", and a " (:TERM "gesture") " to an object of another presentation type." (:PAR))
     (:DT "presentation type")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. A description of a class of " (:TERM "presentations")
      ". 2. An extension to CLOS that implements this." (:PAR))
     (:DT "presentation type specifier")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A Lisp object used to specify a " (:TERM "presentation type") "." (:PAR))
     (:DT "programmer")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A person who writes application programs using CLIM." (:PAR))
     (:DT "protocol class")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " An \"abstract\" class having no methods or slots that is used to indicate that a class obeys a certain protocol. For example, all classes that inherit from the "
      (:CL "bounding-rectangle") " class obey the bounding rectangle protocol." (:PAR))
     (:DT "rectangle")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. A four-sided polygon whose sides are parallel to the coordinate axes. 2. A Lisp object that represents a "
      (:TERM "rectangle") "." (:PAR))
     (:DT "redisplay") (:DD (:GROUP (:FONT :FACE :I) "n.") " See " (:TERM "incremental redisplay") "." (:PAR))
     (:DT "region")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. A set of mathematical points in the plane; a mapping from an "
      (:MATH "(x,y)")
      " pair into either true or false (meaning member or not a member, respectively, of the region). In CLIM, all regions include their boundaries (that is, they are closed) and have infinite resolution. 2. A Lisp object that represents a "
      (:TERM "region") "." (:PAR))
     (:DT "region set")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. A \"compound\" " (:TERM "region")
      ", that is, a region consisting of several other regions related by one of the operations union, intersection, or difference. 2. A Lisp object that represents a "
      (:TERM "region set") "." (:PAR))
     (:DT "rendering")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " The process of drawing a shape (such as a line or a circle) on a display device. Rendering is an approximate process, since an abstract shape exists in a continuous coordinate system having infinite precision, whereas display devices must necessarily draw discrete points having some measurable size."
      (:PAR))
     (:DT "replaying")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The process of redrawing a set of " (:TERM "output records") "." (:PAR))
     (:DT "repainting") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "sensitive")
     (:DD (:GROUP (:FONT :FACE :I) "adj.") " (of a " (:TERM "presentation") ") A " (:TERM "presentation") " is "
      (:TERM "sensitive")
      " if some action will take place when the user clicks on it with the pointer, that is, there is at least one "
      (:TERM "presentation translator") " that is " (:TERM "applicable")
      ". In this case, the presentation will usually be " (:TERM "highlighted") "." (:PAR))
     (:DT "server path") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "sheet")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. ---Fill this in---. 2. A Lisp object that represents a " (:TERM "sheet")
      "." (:PAR))
     (:DT "sheet region") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR))
     (:DT "sheet transformation") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR))
     (:DT "solid design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design")
      " that is either completely opaque or completely transparent. A solid design can be opaque at some points and transparent at others."
      (:PAR))
     (:DT "stencil")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A kind of " (:TERM "pattern") " that contains only " (:TERM "opacities") "."
      (:PAR))
     (:DT "stencil opacity")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The " (:TERM "opacity") " at one point in a " (:TERM "design")
      " that would result from drawing the design onto a fictitious medium whose drawing plane is initially completely transparent black (opacity and all color components are zero), and whose foreground and background are both opaque black. The "
      (:TERM "stencil opacity") " of an " (:TERM "opacity") " is simply its value." (:PAR))
     (:DT "stream")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A kind of " (:TERM "sheet")
      " that implements the stream protocol (such as maintaining a " (:TERM "text cursor") ")." (:PAR))
     (:DT "text cursor") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "text style")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. A description of how textual output should appear, consisting of family, face code, and size. 2. A Lisp object that represents a "
      (:TERM "text style") "." (:PAR))
     (:DT "tiling")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " The process of repeating a rectangular portion of a " (:TERM "design")
      " throughout the drawing plane. A " (:TERM "tile") " is a " (:TERM "design") " created by this process." (:PAR))
     (:DT "transformation")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " 1. A mapping from one coordinate system onto another that preserves straight lines. General transformations include all the sorts of transformations that CLIM uses, namely, translations, scaling, rotations, and reflections. 2. A Lisp object that represents a "
      (:TERM "transformation") "." (:PAR))
     (:DT "translucent design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design") " that is not " (:TERM "solid")
      ", that is, has at least one point with an opacity that is intermediate between completely opaque and transparent."
      (:PAR))
     (:DT "true")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. The boolean value true; not " (:TERM "false")
      ". 2. Any Lisp object that is not " (:CL "nil") "." (:PAR))
     (:DT "unbounded design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design")
      " that has at least one point of non-zero opacity arbitrarily far from the origin. Drawing an unbounded design affects the entire drawing plane."
      (:PAR))
     (:DT "unbounded region")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "region")
      " that either contains no points or contains points arbitrarily far apart." (:PAR))
     (:DT "uniform design")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A " (:TERM "design")
      " that has the same color and opacity at every point in the drawing plane. Uniform designs are always unbounded, unless they are completely transparent."
      (:PAR))
     (:DT "unique id")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " During " (:TERM "incremental redisplay") ", the " (:TERM "unique id")
      " is an object used to uniquely identify a piece of output. The output named by the " (:TERM "unique id")
      " will often have a " (:TERM "cache value") " associated with it." (:PAR))
     (:DT "user")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " A person who uses an application program that was written using CLIM."
      (:PAR))
     (:DT "user transformation") (:DD (:GROUP (:FONT :FACE :I) "n.") " ---Fill this in---" (:PAR)) (:DT "view")
     (:DD (:GROUP (:FONT :FACE :I) "n.") " 1. ---Fill this in---. 2. A Lisp object that represents a " (:TERM "view")
      "." (:PAR))
     (:DT "viewport")
     (:DD (:GROUP (:FONT :FACE :I) "n.")
      " The portion of the drawing plane of a sheet's medium that is visible on a display device." (:PAR))
     (:DT "volatile")
     (:DD (:GROUP (:FONT :FACE :I) "adj.")
      " (of an immutable object) Having components that cannot be modified by the programmer at the protocol level, but which may be modified internally by CLIM. "
      (:TERM "Volatile") " objects reflect internal state of CLIM." (:PAR)))
    (:PAR))
   " "
   (:SECTION :TITLE ("B " "The CLIM-SYS Package") :KIND :CHAPTER :NAME (6 10) " " (:LABEL :NAME "clim-sys-package")
    (:PAR) "The " (:CL "clim-sys")
    " package where useful \"system-like\" functionality lives, including such things as resources and multi-processing primitives. It contains concepts that are not part of Common Lisp, but which are not conceptually the province of CLIM itself."
    (:PAR) "All of the symbols documented in this appendix must be accessible as external symbols in the "
    (:CL "clim-sys") " package." (:PAR) " "
    (:SECTION :TITLE ("B.1 " "Resources") :KIND :SECTION :NAME (4 6 10) (:PAR) "CLIM provides a facility called "
     (:CONCEPT "resources")
     " that provides for reusing objects. A resource describes how to construct an object, how to initialize and deinitialize it, and how an object should be selected from the resource of objects based on a set of parameters."
     (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "defresource")) :PARAMS
       ((:I "name parameters  " (:GROUP (:FONT :FACE :TT) "&key ")
         "constructor initializer deinitializer  matcher initial-copies"))
       :KIND ("Macro"))
      (:PAR) "Defines a resource named " (:GROUP (:FONT :FACE :I) "name") ", which must be a symbol. "
      (:GROUP (:FONT :FACE :I) "parameters")
      " is a lambda-list giving names and default values (for optional and keyword parameters) of parameters to an object of this type."
      (:PAR) (:GROUP (:FONT :FACE :I) "constructor")
      " is a form that is responsible for creating an object, and is called when someone tries to allocate an object from the resource and no suitable free objects exist. The constructor form can access the parameters as variables. This argument is required."
      (:PAR) (:GROUP (:FONT :FACE :I) "initializer")
      " is a form that is used to initialize an object gotten from the resource. It can access the parameters as variables, and also has access to a variable called "
      (:GROUP (:FONT :FACE :I) "name")
      ", which is the object to be initialized. The initializer is called both on newly created objects and objects that are being reused."
      (:PAR) (:GROUP (:FONT :FACE :I) "deinitializer")
      " is a form that is used to deinitialize an object when it is about to be returned to the resource. It can access the parameters as variables, and also has access to a variable called "
      (:GROUP (:FONT :FACE :I) "name")
      ", which is the object to be deinitialized. It is called whenever an object is deallocated back to the resource, but is not called by "
      (:CL "clear-resource") ". Deinitializers are typically used to clear references to other objects." (:PAR)
      (:GROUP (:FONT :FACE :I) "matcher")
      " is a form that ensures that an object in the resource \"matches\" the specified parameters, which it can access as variables. In addition, the matcher also has access to a variable called "
      (:GROUP (:FONT :FACE :I) "name")
      ", which is the object in the resource being matched against. If no matcher is supplied, the system remembers the values of the parameters (including optional ones that defaulted) that were used to construct the object, and assumes that it matches those particular values for all time. This comparison is done with "
      (:CL "equal") ". The matcher should return " (:TERM "true") " if there is a match, otherwise it should return "
      (:TERM "false") "." (:PAR) (:GROUP (:FONT :FACE :I) "initial-copies")
      " is used to specify the number of objects that should be initially put into the resource. It must be an integer or "
      (:CL "nil")
      " (the default), meaning that no initial copies should be made. If initial copies are made and there are parameters, all the parameters must be optional; in this case, the initial copies have the default values of the parameters."
      (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "using-resource")) :PARAMS
       ((:I "(variable name " (:GROUP (:FONT :FACE :TT) "&rest ") "parameters) " (:GROUP (:FONT :FACE :TT) "&body ")
         "body"))
       :KIND ("Macro"))
      (:PAR) "The forms in " (:GROUP (:FONT :FACE :I) "body") " are evaluated with "
      (:GROUP (:FONT :FACE :I) "variable") " bound to an object allocated from the resource named "
      (:GROUP (:FONT :FACE :I) "name") ", using the parameters given by " (:GROUP (:FONT :FACE :I) "parameters")
      ". The parameters (if any) are evaluated, but " (:GROUP (:FONT :FACE :I) "name") " is not." (:PAR)
      "After the body has been evaluated, " (:CL "using-resource") " returns the object in "
      (:GROUP (:FONT :FACE :I) "variable") " back to the resource. If some form in the body sets "
      (:GROUP (:FONT :FACE :I) "variable") " to " (:CL "nil")
      ", the object will not be returned to the resource. Otherwise, the body should not changes the value of "
      (:GROUP (:FONT :FACE :I) "variable") "." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "allocate-resource")) :PARAMS
       ((:I "name " (:GROUP (:FONT :FACE :TT) "&rest ") "parameters")) :KIND ("Function"))
      (:PAR) "Allocates an object from the resource named " (:GROUP (:FONT :FACE :I) "name")
      ", using the parameters given by " (:GROUP (:FONT :FACE :I) "parameters") ". " (:GROUP (:FONT :FACE :I) "name")
      " must be a symbol that names a resource. The returned value is the allocated object." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "deallocate-resource")) :PARAMS ((:I "name object")) :KIND ("Function")) (:PAR)
      "Returns the object " (:GROUP (:FONT :FACE :I) "object") " to the resource named "
      (:GROUP (:FONT :FACE :I) "name") ". " (:GROUP (:FONT :FACE :I) "name")
      " must be a symbol that names a resource. " (:GROUP (:FONT :FACE :I) "object")
      " must be an object that was originally allocated from the same resource." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "clear-resource")) :PARAMS ((:I "name")) :KIND ("Function")) (:PAR)
      "Clears the resource named " (:GROUP (:FONT :FACE :I) "name")
      ", that is, removes all of the resourced object from the resource. " (:GROUP (:FONT :FACE :I) "name")
      " must be a symbol that names a resource." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "map-resource")) :PARAMS ((:I "function name")) :KIND ("Function")) (:PAR)
      "Calls " (:GROUP (:FONT :FACE :I) "function") " once on each object in the resource named "
      (:GROUP (:FONT :FACE :I) "name") ". " (:GROUP (:FONT :FACE :I) "function")
      " is a function of three arguments, the object, a boolean value that is " (:TERM "true")
      " if the object is in use or " (:TERM "false") " if it is free, and " (:GROUP (:FONT :FACE :I) "name") ". "
      (:GROUP (:FONT :FACE :I) "function") " has dynamic extent." (:PAR) " "))
    (:SECTION :TITLE ("B.2 " "Multi-processing") :KIND :SECTION :NAME (4 6 10) (:PAR)
     "Most Lisp implementations provide some form of multi-processing. CLIM provides a set of functions that implement a uniform interface to the multi-processing functionality."
     (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "*multiprocessing-p*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR) "The value of "
      (:CL "*multiprocessing-p*") " is " (:CL "t")
      " if the current Lisp environment supports multi-processing, otherwise it is " (:CL "nil") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-process")) :PARAMS ((:I "function " (:GROUP (:FONT :FACE :TT) "&key ") "name"))
       :KIND ("Function"))
      (:PAR) "Creates a process named " (:GROUP (:FONT :FACE :I) "name")
      ". The new process will evaluate the function " (:GROUP (:FONT :FACE :I) "function")
      ". On systems that do not support multi-processing, " (:CL "make-process") " will signal an error." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "destroy-process")) :PARAMS ((:I "process")) :KIND ("Function")) (:PAR)
      "Terminates the process " (:GROUP (:FONT :FACE :I) "process") ". " (:GROUP (:FONT :FACE :I) "process")
      " is an object returned by " (:CL "make-process") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "current-process")) :PARAMS ((:I)) :KIND ("Function")) (:PAR)
      "Returns the currently running process, which will be the same kind of object as would be returned by "
      (:CL "make-process") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "all-processes")) :PARAMS ((:I)) :KIND ("Function")) (:PAR)
      "Returns a sequence of all of the processes." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "processp")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate")) (:PAR)
      "Returns " (:CL "t") " if " (:GROUP (:FONT :FACE :I) "object") " is a process, otherwise returns "
      (:GROUP (:FONT :FACE :I) "nil") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "process-name")) :PARAMS ((:I "process")) :KIND ("Function"))
      (:SIGNATURE :NAME ((:CL "process-state")) :PARAMS ((:I "process")) :KIND ("Function"))
      (:SIGNATURE :NAME ((:CL "process-whostate")) :PARAMS ((:I "process")) :KIND ("Function")) (:PAR)
      "These functions return, respectively, the name, state, and \"whostate\" of the process. These format of these quantities will vary depending on the platform."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "process-wait")) :PARAMS ((:I "reason predicate")) :KIND ("Function")) (:PAR)
      "Causes the current process to wait until " (:GROUP (:FONT :FACE :I) "predicate") " returns " (:TERM "true") ". "
      (:GROUP (:FONT :FACE :I) "reason")
      " is a \"reason\" for waiting, usually a string. On systems that do not support multi-processing, "
      (:CL "process-wait") " will loop until " (:GROUP (:FONT :FACE :I) "predicate") " returns " (:TERM "true") "."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "process-wait-with-timeout")) :PARAMS ((:I "reason timeout predicate")) :KIND
       ("Function"))
      (:PAR) "Causes the current process to wait until either " (:GROUP (:FONT :FACE :I) "predicate") " returns "
      (:TERM "true") ", or the number of seconds specified by " (:GROUP (:FONT :FACE :I) "timeout") " has elapsed. "
      (:GROUP (:FONT :FACE :I) "reason")
      " is a \"reason\" for waiting, usually a string. On systems that do not support multi-processing, "
      (:CL "process-wait-with-timeout") " will loop until " (:GROUP (:FONT :FACE :I) "predicate") " returns "
      (:TERM "true") " or the timeout has elapsed." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "process-yield")) :PARAMS ((:I)) :KIND ("Function")) (:PAR)
      "Allows other processes to run. On systems that do not support multi-processing, this does nothing." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "process-interrupt")) :PARAMS ((:I "process function")) :KIND ("Function")) (:PAR)
      "Interrupts the process " (:GROUP (:FONT :FACE :I) "process") " and causes it to evaluate the function "
      (:GROUP (:FONT :FACE :I) "function") ". On systems that do not support multi-processing, this is equivalent to "
      (:CL "funcall") "'ing " (:GROUP (:FONT :FACE :I) "function") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "disable-process")) :PARAMS ((:I "process")) :KIND ("Function")) (:PAR)
      "Disables the process " (:GROUP (:FONT :FACE :I) "process") " from becoming runnable until it is enabled again."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "enable-process")) :PARAMS ((:I "process")) :KIND ("Function")) (:PAR)
      "Allows the process " (:GROUP (:FONT :FACE :I) "process") " to become runnable again after it has been disabled."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "restart-process")) :PARAMS ((:I "process")) :KIND ("Function")) (:PAR)
      "Restarts the process " (:GROUP (:FONT :FACE :I) "process")
      " by \"unwinding\" it to its initial state, and reinvoking its top-level function." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "without-scheduling")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND
       ("Macro"))
      (:PAR) "Evaluates " (:GROUP (:FONT :FACE :I) "body")
      " in a context that is guaranteed to be free from interruption by other processes. On systems that do not support multi-processing, "
      (:CL "without-scheduling") " is equivalent to " (:CL "progn") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "atomic-incf")) :PARAMS ((:I "reference")) :KIND ("Function"))
      (:SIGNATURE :NAME ((:CL "atomic-decf")) :PARAMS ((:I "reference")) :KIND ("Function")) (:PAR)
      "Increments (or decrements) the fixnum value referred to by " (:GROUP (:FONT :FACE :I) "reference")
      " as a single, atomic operation." (:PAR) " "))
    (:SECTION :TITLE ("B.3 " "Locks") :KIND :SECTION :NAME (4 6 10) (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-lock")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "name")) :KIND
       ("Function"))
      (:PAR) "Creates a lock whose name is " (:GROUP (:FONT :FACE :I) "name")
      ". On systems that do not support locking, this will return a new list of one element, " (:CL "nil") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-lock-held")) :PARAMS
       ((:I "(place " (:GROUP (:FONT :FACE :TT) "&optional ") "state) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Evaluates " (:GROUP (:FONT :FACE :I) "body") " with the lock named by " (:GROUP (:FONT :FACE :I) "place")
      ". " (:GROUP (:FONT :FACE :I) "place") " is a reference to a lock created by " (:CL "make-lock") "." (:PAR)
      "On systems that do not support locking, " (:CL "with-lock-held") " is equivalent to " (:CL "progn") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-recursive-lock")) :PARAMS ((:I (:GROUP (:FONT :FACE :TT) "&optional ") "name"))
       :KIND ("Function"))
      (:PAR) "Creates a recursive lock whose name is " (:GROUP (:FONT :FACE :I) "name")
      ". On systems that do not support locking, this will return a new list of one element, " (:CL "nil")
      ". A recursive lock differs from an ordinary lock in that a process that already holds the recursive lock can call "
      (:CL "with-recursive-lock-held") " on the same lock without blocking." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-recursive-lock-held")) :PARAMS
       ((:I "(place " (:GROUP (:FONT :FACE :TT) "&optional ") "state) " (:GROUP (:FONT :FACE :TT) "&body ") "body"))
       :KIND ("Macro"))
      (:PAR) "Evaluates " (:GROUP (:FONT :FACE :I) "body") " with the recursive lock named by "
      (:GROUP (:FONT :FACE :I) "place") ". " (:GROUP (:FONT :FACE :I) "place")
      " is a reference to a recursive lock created by " (:CL "make-recursive-lock") "." (:PAR)
      "On systems that do not support locking, " (:CL "with-recursive-lock-held") " is equivalent to " (:CL "progn")
      "." (:PAR) " "))
    (:SECTION :TITLE ("B.4 " "Multiple Value " (:GROUP (:FONT :FACE :TT) "setf")) :KIND :SECTION :NAME (4 6 10) (:PAR)
     "CLIM provides a facility, sometimes referred to as " (:CL "setf*") ", that allows " (:CL "setf")
     " to be used on \"places\" that name multiple values. For example, " (:CL "output-record-position")
     " returns the position of an output record as two values that correspond to the " (:MATH "x") " and " (:MATH "y")
     " coordinates. In order to change the position of an output record, the programmer would like to invoke "
     (:CL "(setf output-record-position)") ". Normally however, " (:CL "setf")
     " only takes a single value with which to modify the specified place. The " (:CL "setf*")
     " facility provides a \"multiple value\" version of " (:CL "setf")
     " that allows an expression that returns multiple values to be used to update the specified place." (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "defgeneric*")) :PARAMS
       ((:I "name lambda-list " (:GROUP (:FONT :FACE :TT) "&body ") "options")) :KIND ("Macro"))
      (:PAR) "Defines a " (:CL "setf*") " generic function named " (:GROUP (:FONT :FACE :I) "name")
      ". The last argument in " (:GROUP (:FONT :FACE :I) "lambda-list")
      " is intended to be class specialized, just as is the case for normal " (:CL "setf") " generic functions. "
      (:GROUP (:FONT :FACE :I) "options") " is as for " (:CL "defgeneric") "." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "defmethod*")) :PARAMS
       ((:I "name {method-qualifier}* specialized-lambda-list " (:GROUP (:FONT :FACE :TT) "&body ") "body")) :KIND
       ("Macro"))
      (:PAR) "Defines a " (:CL "setf*") " method for the generic function " (:GROUP (:FONT :FACE :I) "name")
      ". The last argument in " (:GROUP (:FONT :FACE :I) "specialized-lambda-list")
      " is intended to be class specialized, just as is the case for normal " (:CL "setf") " methods. "
      (:GROUP (:FONT :FACE :I) "{method-qualifier}*") " amd " (:GROUP (:FONT :FACE :I) "body") " are as for "
      (:CL "defgeneric") "." (:PAR) " For example, " (:CL "output-record-position") " and its " (:CL "setf*")
      " method for a class called " (:CL "sample-output-record") " might be defined as follows:" (:PAR)
      (:PRE "
(defgeneric output-record-position (record)
  (declare (values x y)))
(defgeneric* (setf output-record-position) (x y record))

(defmethod output-record-position ((record sample-output-record))
  (with-slots (x y)
    (values x y)))

(defmethod* (setf output-record-position) (nx ny (record sample-output-record))
  (with-slots (x y)
    (setf x nx
          y ny)))
")
      (:PAR) "The position of such an output record could then be changed as follows:" (:PAR)
      (:PRE "
(setf (output-record-position record) (values nx ny))

(setf (output-record-position record1) (output-record-position record2))
")
      (:PAR))))
   " "
   (:SECTION :TITLE ("C " "Encapsulating Streams") :KIND :CHAPTER :NAME (6 10) " "
    (:LABEL :NAME "encapsulating-streams") (:PAR) "An " (:CONCEPT "encapsulating stream")
    " is a special kind of stream that \"closes over\" another stream, handling some of the usual stream protocol operations itself, and delegating the remaining operations to the \"encapsulated\" stream. Encapsulating streams may be used by some CLIM implementations in order to facilitate the implementation of features that require the dynamic modification of a stream's state and operations. For example, "
    (:CL "accepting-values") " dialogs can be implemented by using an encapsulating stream that tailors calls to "
    (:CL "accept") " and " (:CL "prompt-for-accept")
    " in such a way that the output is captured and formatted into a dialog that contains prompts and fields that can be clicked on and modified by the user. Input editing can also be implemented using an encapsulating stream that manages the interaction between "
    (:CL "read-gesture") " and the input editing commands and rescanning. The form " (:CL "filling-output")
    " can be implemented by having an encapsulating stream that buffers output and inserts line breaks appropriately."
    (:PAR)
    "CLIM implementations need not use encapsulating streams at all. If encapsulating streams are used, they must adhere to the following protocols. Encapsulating streams are not part of CLIM's API."
    (:PAR)
    (:SECTION :TITLE ("C.1 " "Encapsulating Stream Classes") :KIND :SECTION :NAME (1 6 10) (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "encapsulating-stream")) :PARAMS ((:I)) :KIND ("Protocol Class")) (:PAR)
      "The protocol class that corresponds to an encapsulating stream. If you want to create a new class that behaves like an encapsulating stream, it should be a subclass of "
      (:CL "encapsulating-stream") ". All instantiable subclasses of " (:CL "encapsulating-stream")
      " must obey the encapsulating stream protocol. Members of this class are mutable. " (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "encapsulating-stream-p")) :PARAMS ((:I "object")) :KIND ("Protocol Predicate"))
      (:PAR) "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is an "
      (:TERM "encapsulating stream") ", otherwise returns " (:TERM "false") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL ":stream")) :PARAMS ((:I)) :KIND ("Initarg")) (:PAR)
      "All encapsulating streams must handle the " (:CL ":stream")
      " initarg, which is used to specify the stream to be encapsulated." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "standard-encapsulating-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "This instantiable class provides a standard implementation of an encapsulating stream." (:PAR) " ")
     (:SECTION :TITLE ("C.1.1 " "Encapsulating Stream Protocol") :KIND :SUBSECTION :NAME (2 1 6 10) (:PAR) "The "
      (:CL "standard-encapsulating-stream") " class must provide \"trampoline\" methods for "
      (:GROUP (:FONT :FACE :SL) "all")
      " stream protocol operations. These \"trampolines\" will simply call the same generic function on the encapsulated stream. In particular, all of the generic functions in the following protocols must have trampolines."
      (:PAR)
      (:UL
       (:LI "The basic input and output stream protocols, as specified by the Gray stream proposal in Chapter "
        (:REF :NAME "gray-streams") "." (:PAR))
       (:LI "The sheet protocols, as specified in Chapters " (:REF :NAME "sheet-properties") " and "
        (:REF :NAME "sheet-protocols") "." (:PAR))
       (:LI "The medium protocol, as specified in Chapter " (:REF :NAME "drawing-options") "." (:PAR))
       (:LI "The text style binding forms, as specified in Chapter " (:REF :NAME "text-styles") "." (:PAR))
       (:LI "The drawing functions, as specified in Chapter " (:REF :NAME "graphics") "." (:PAR))
       (:LI "The extended output stream protocol, as specified in Chapter " (:REF :NAME "extended-output") "." (:PAR))
       (:LI "The output recording stream protocol, as specified in Chapter " (:REF :NAME "output-recording") "."
        (:PAR))
       (:LI "The incremental redisplay stream protocol, as specified in Chapter " (:REF :NAME "incremental-redisplay")
        "." (:PAR))
       (:LI "The extended input stream protocol, as specified in Chapter " (:REF :NAME "extended-input") "." (:PAR))
       (:LI "The stream generics for presentation types, as specified in Chapter " (:REF :NAME "presentation-types")
        ". "))
      (:PAR) "The following generic function must also be implemented for all encapsulating stream classes." (:PAR)
      (:DEFUN
       (:SIGNATURE :NAME ((:CL "encapsulating-stream-stream")) :PARAMS ((:I "encapsulating-stream")) :KIND
        ("Generic Function"))
       (:PAR) "Returns the stream encapsulated by the " (:TERM "encapsulating stream") " "
       (:GROUP (:FONT :FACE :I) "encapsulating-stream") "." (:PAR) " "))
     (:SECTION :TITLE ("C.1.2 " "The \"Delegation Problem\"") :KIND :SUBSECTION :NAME (2 1 6 10) (:PAR)
      "The suggested implementation of encapsulating streams has a potential problem that we label the \"delegation\" or \"multiple self\" problem. Here is an example of the problem."
      (:PAR) "Suppose we implement " (:CL "accepting-values") " by using an encapsulating stream class called "
      (:CL "accepting-values-stream")
      " that will be used to close over an ordinary extended input and output stream. Let us examine two generic functions, "
      (:CL "stream-accept") " and " (:CL "prompt-for-accept") ". The " (:CL "stream-accept")
      " method on an ordinary stream calls " (:CL "prompt-for-accept") ". Now suppose that "
      (:CL "accepting-values-stream") " specializes " (:CL "prompt-for-accept") ". If we now create a stream of type "
      (:CL "accepting-values-stream") " (which we will designate " (:MATH "A")
      ") which encapsulates an ordinary stream " (:MATH "S") ", and then call " (:CL "stream-accept") " on the stream "
      (:MATH "E") ", it will trampoline to " (:CL "stream-accept") " on the stream " (:MATH "S")
      ". The desired behavior is for " (:CL "stream-accept") " to call the " (:CL "prompt-for-accept")
      " method on the stream " (:MATH "E") ", but instead what happens is that the " (:CL "prompt-for-accept")
      " method on the stream " (:MATH "S") " is called." (:PAR)
      "In order to side-step this problem without attempting to solve a difficult general problem in object-oriented programming, CLIM implementations may introduce a special variable, "
      (:CL "*original-stream*")
      ", which is bound by trampoline functions to the original encapsulating stream. Therefore, the "
      (:CL "stream-accept") " on the ordinary stream " (:MATH "S") " will call " (:CL "prompt-for-accept")
      " on the value of " (:CL "(or *original-stream* " (:GROUP (:FONT :FACE :I) "stream") ")")
      ". This idiom only needs to be used in places where one stream protocol function calls a second stream protocol function that some encapsulating stream specializes."
      (:PAR)
      "This \"solution\" does not solve the more general problem of multiple levels of encapsulation, but the complete stream protocol provided by CLIM should allow implementors to avoid using nested encapsulating streams."
      (:PAR)
      (:DEFUN (:SIGNATURE :NAME ((:CL "*original-stream*")) :PARAMS ((:I)) :KIND ("Variable")) (:PAR)
       "This variable is bound by the trampoline methods on encapsulating streams to the encapsulating stream, before the operation is delegated to the underlying, encapsulated stream."
       (:PAR)))))
   " "
   (:SECTION :TITLE ("D " "Common Lisp Streams") :KIND :CHAPTER :NAME (6 10) " " (:LABEL :NAME "gray-streams") (:PAR)
    "CLIM performs all of its character-based input and output operations on objects called " (:CONCEPT "streams")
    ". Streams are divided into two layers, the " (:CONCEPT "basic stream protocol")
    ", which is character-based and compatible with existing Common Lisp programs, and the "
    (:CONCEPT "extended stream protocol")
    ", which introduces extended gestures such as pointer gestures and synchronous window-manager communication."
    (:PAR)
    "This appendix describes the basic stream-based input and output protocol used by CLIM. The protocol is taken from the "
    (:CL "STREAM-DEFINITION-BY-USER")
    " proposal to the X3J13 committee, made by David Gray of TI. This proposal was not accepted by the X3J13 committee as part of the ANSI Common Lisp language definition, but many Lisp implementations do support it. For those implementations that do not support it, it is implemented as part of CLIM."
    (:PAR) " "
    (:SECTION :TITLE ("D.1 " "Stream Classes") :KIND :SECTION :NAME (5 6 10) (:PAR)
     "The following classes must be used as superclasses of user-defined stream classes. They are not intended to be directly instantiated; they just provide places to hang default methods."
     (:PAR) " "
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "This class is the base class for all CLIM streams. It is a subclass of " (:CL "stream") " and of "
      (:CL "standard-object") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "streamp")) :PARAMS ((:I "object")) :KIND ("Generic Function")) (:PAR) "Returns "
      (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "object") " is a member of the class " (:CL "fundamental-stream")
      ". It may return " (:TERM "true") " for other objects that are not members of the " (:CL "fundamental-stream")
      " class, but claim to serve as streams. (It is not sufficient to implement " (:CL "streamp") " as "
      (:CL "(typep object 'fundamental-stream)")
      ", because implementations may have additional ways of defining streams.)" (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-input-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of " (:CL "fundamental-stream") " that implements input streams." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "input-stream-p")) :PARAMS ((:I "object")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:TERM "true") " when called on any object that is a member of the class "
      (:CL "fundamental-input-stream") ". It may return " (:TERM "true")
      " for other objects that are not members of the " (:CL "fundamental-input-stream")
      " class, but claim to serve as input streams." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-output-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of " (:CL "fundamental-stream") " that implements output streams." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "output-stream-p")) :PARAMS ((:I "object")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:TERM "true") " when called on any object that is a member of the class "
      (:CL "fundamental-output-stream") ". It may return " (:TERM "true")
      " for other objects that are not members of the " (:CL "fundamental-output-stream")
      " class, but claim to serve as output streams." (:PAR) "Bidirectional streams can be formed by including both "
      (:CL "fundamental-input-stream") " and " (:CL "fundamental-output-stream") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-character-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of " (:CL "fundamental-stream") ". It provides a method for " (:CL "stream-element-type")
      ", which returns " (:CL "character") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-binary-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of " (:CL "fundamental-stream")
      ". Any instantiable class that includes this needs to define a method for " (:CL "stream-element-type") "."
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-character-input-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of both " (:CL "fundamental-input-stream") " and " (:CL "fundamental-character-stream")
      ". It provides default methods for several generic functions used for character input." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-character-output-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of both " (:CL "fundamental-output-stream") " and " (:CL "fundamental-character-stream")
      ". It provides default methods for several generic functions used for character output." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-binary-input-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of both " (:CL "fundamental-input-stream") " and " (:CL "fundamental-binary-stream") "." (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "fundamental-binary-output-stream")) :PARAMS ((:I)) :KIND ("Class")) (:PAR)
      "A subclass of both " (:CL "fundamental-output-stream") " and " (:CL "fundamental-binary-stream") "." (:PAR)
      " "))
    (:SECTION :TITLE ("D.2 " "Basic Stream Functions") :KIND :SECTION :NAME (5 6 10) (:PAR)
     "These generic functions must be defined for all stream classes." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-element-type")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "This existing Common Lisp function is made generic, but otherwise behaves the same. Class "
      (:CL "fundamental-character-stream") " provides a default method that returns " (:CL "character") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "open-stream-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "This function is made generic. A default method is provided by class " (:CL "fundamental-stream")
      " that returns " (:TERM "true") " if " (:CL "close") " has not been called on the stream." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "close")) :PARAMS ((:I "stream " (:GROUP (:FONT :FACE :TT) "&key ") "abort")) :KIND
       ("Generic Function"))
      (:PAR) "The existing Common Lisp function " (:CL "close")
      " is redefined to be a generic function, but otherwise behaves the same. The default method provided by the class "
      (:CL "fundamental-stream") " sets a flag used by " (:CL "open-stream-p") ". The value returned by " (:CL "close")
      " will be as specified by the X3J13 issue " (:CL "closed-stream-operations") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-pathname")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:SIGNATURE :NAME ((:CL "stream-truename")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "These are used to implement " (:CL "pathname") " and " (:CL "truename")
      ". There is no default method since these are not valid for all streams." (:PAR) " "))
    (:SECTION :TITLE ("D.3 " "Character Input") :KIND :SECTION :NAME (5 6 10) (:PAR)
     "A character input stream can be created by defining a class that includes "
     (:CL "fundamental-character-input-stream") " and defining methods for the generic functions below." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-read-char")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Reads one character from " (:GROUP (:FONT :FACE :I) "stream")
      ", and returns either a character object or the symbol " (:CL ":eof")
      " if the stream is at end-of-file. There is no default method for this generic function, so every subclass of "
      (:CL "fundamental-character-input-stream") " must define a method." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-unread-char")) :PARAMS ((:I "stream character")) :KIND ("Generic Function"))
      (:PAR) "Undoes the last call to " (:CL "stream-read-char") ", as in " (:CL "unread-char") ", and returns "
      (:CL "nil") ". There is no default method for this, so every subclass of "
      (:CL "fundamental-character-input-stream") " must define a method." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-read-char-no-hang")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:PAR) "Returns either a character, or " (:CL "nil") " if no input is currently available, or " (:CL ":eof")
      " if end-of-file is reached. This is used to implement " (:CL "read-char-no-hang")
      ". The default method provided by " (:CL "fundamental-character-input-stream") " simply calls "
      (:CL "stream-read-char")
      "; this is sufficient for file streams, but interactive streams should define their own method." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-peek-char")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns either a character or " (:CL ":eof")
      " without removing the character from the stream's input buffer. This is used to implement " (:CL "peek-char")
      "; this corresponds to peek-type of " (:CL "nil") ". The default method calls " (:CL "stream-read-char") " and "
      (:CL "stream-unread-char.") (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-listen")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:TERM "true") " if there is any input pending on " (:GROUP (:FONT :FACE :I) "stream")
      ", otherwise it returns " (:TERM "false") ". This is used by " (:CL "listen") ". The default method uses "
      (:CL "stream-read-char-no-hang") " and " (:CL "stream-unread-char")
      ". Most streams should define their own method since it will usually be trivial and will generally be more efficient than the default method."
      (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-read-line")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns a string as the first value, and " (:CL "t")
      " as the second value if the string was terminated by end-of-file instead of the end of a line. This is used by "
      (:CL "read-line") ". The default method uses repeated calls to " (:CL "stream-read-char") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-clear-input")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Clears any buffered input associated with " (:GROUP (:FONT :FACE :I) "stream") ", and returns " (:TERM "false")
      ". This is used to implement " (:CL "clear-input") ". The default method does nothing." (:PAR) " "))
    (:SECTION :TITLE ("D.4 " "Character Output") :KIND :SECTION :NAME (5 6 10) (:PAR)
     "A character output stream can be created by defining a class that includes "
     (:CL "fundamental-character-output-stream") " and defining methods for the generic functions below." (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-write-char")) :PARAMS ((:I "stream character")) :KIND ("Generic Function"))
      (:PAR) "Writes " (:GROUP (:FONT :FACE :I) "character") " to " (:GROUP (:FONT :FACE :I) "stream") ", and returns "
      (:GROUP (:FONT :FACE :I) "character") " as its value. Every subclass of "
      (:CL "fundamental-character-output-stream") " must have a method defined for this function." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-line-column")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "This function returns the column number where the next character will be written on "
      (:GROUP (:FONT :FACE :I) "stream") ", or " (:CL "nil")
      " if that is not meaningful. The first column on a line is numbered 0. This function is used in the implementation of "
      (:CL "pprint") " and the " (:CL "format") " " (:CODE "~T")
      " directive. Every character output stream class must define a method for this, although it is permissible for it to always return "
      (:CL "nil") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-start-line-p")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns " (:TERM "true") " if " (:GROUP (:FONT :FACE :I) "stream")
      " is positioned at the beginning of a line, otherwise returns " (:TERM "false")
      ". It is permissible to always return " (:TERM "false") ". This is used in the implementation of "
      (:CL "fresh-line") "." (:PAR) "Note that while a value of 0 from " (:CL "stream-line-column")
      " also indicates the beginning of a line, there are cases where " (:CL "stream-start-line-p")
      " can be meaningfully implemented when " (:CL "stream-line-column")
      " cannot. For example, for a window using variable-width characters, the column number isn't very meaningful, but the beginning of the line does have a clear meaning. The default method for "
      (:CL "stream-start-line-p") " on class " (:CL "fundamental-character-output-stream") " uses "
      (:CL "stream-line-column") ", so if that is defined to return " (:CL "nil")
      ", then a method should be provided for either " (:CL "stream-start-line-p") " or " (:CL "stream-fresh-line") "."
      (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-write-string")) :PARAMS
       ((:I "stream string " (:GROUP (:FONT :FACE :TT) "&optional ") "(start " (:CL "0") ") end")) :KIND
       ("Generic Function"))
      (:PAR) "Writes the string " (:GROUP (:FONT :FACE :I) "string") " to " (:GROUP (:FONT :FACE :I) "stream") ". If "
      (:GROUP (:FONT :FACE :I) "start") " and " (:GROUP (:FONT :FACE :I) "end")
      " are supplied, they specify what part of " (:GROUP (:FONT :FACE :I) "string") " to output. "
      (:GROUP (:FONT :FACE :I) "string") " is returned as the value. This is used by " (:CL "write-string")
      ". The default method provided by " (:CL "fundamental-character-output-stream") " uses repeated calls to "
      (:CL "stream-write-char") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-terpri")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Writes an end of line character on " (:GROUP (:FONT :FACE :I) "stream") ", and returns " (:TERM "false")
      ". This is used by " (:CL "terpri") ". The default method does " (:CL "stream-write-char") " of "
      (:CODE "#\\Newline") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-fresh-line")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Writes an end of line character on " (:GROUP (:FONT :FACE :I) "stream")
      " only if the stream is not at the beginning of the line. This is used by " (:CL "fresh-line")
      ". The default method uses " (:CL "stream-start-line-p") " and " (:CL "stream-terpri") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-finish-output")) :PARAMS ((:I "stream")) :KIND ("Generic Function"))
      (:PAR) "Ensures that all the output sent to " (:GROUP (:FONT :FACE :I) "stream")
      " has reached its destination, and only then return " (:TERM "false") ". This is used by " (:CL "finish-output")
      ". The default method does nothing." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-force-output")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Like " (:CL "stream-finish-output") ", except that it may return " (:TERM "false")
      " without waiting for the output to complete. This is used by " (:CL "force-output")
      ". The default method does nothing." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-clear-output")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Aborts any outstanding output operation in progress, and returns " (:TERM "false") ". This is used by "
      (:CL "clear-output") ". The default method does nothing." (:PAR))
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "stream-advance-to-column")) :PARAMS ((:I "stream column")) :KIND ("Generic Function"))
      (:PAR) "Writes enough blank space on " (:GROUP (:FONT :FACE :I) "stream")
      " so that the next character will be written at the position specified by " (:GROUP (:FONT :FACE :I) "column")
      ". Returns " (:TERM "true") " if the operation is successful, or " (:CL "nil")
      " if it is not supported for this stream. This is intended for use by " (:CL "pprint") " and " (:CL "format") " "
      (:CODE "~T") ". The default method uses " (:CL "stream-line-column") " and repeated calls to "
      (:CL "stream-write-char") " with a " (:CODE "#\\Space") " character; it returns " (:CL "nil") " if "
      (:CL "stream-line-column") " returns " (:CL "nil") "." (:PAR) " "))
    (:SECTION :TITLE ("D.5 " "Binary Streams") :KIND :SECTION :NAME (5 6 10) (:PAR)
     "Binary streams can be created by defining a class that includes either " (:CL "fundamental-binary-input-stream")
     " or " (:CL "fundamental-binary-output-stream") " (or both) and defining a method for "
     (:CL "stream-element-type") " and for one or both of the following generic functions." (:PAR)
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-read-byte")) :PARAMS ((:I "stream")) :KIND ("Generic Function")) (:PAR)
      "Returns either an integer, or the symbol " (:CL ":eof") " if " (:GROUP (:FONT :FACE :I) "stream")
      " is at end-of-file. This is used by " (:CL "read-byte") "." (:PAR))
     (:DEFUN (:SIGNATURE :NAME ((:CL "stream-write-byte")) :PARAMS ((:I "stream integer")) :KIND ("Generic Function"))
      (:PAR) "Writes " (:GROUP (:FONT :FACE :I) "integer") " to " (:GROUP (:FONT :FACE :I) "stream") ", and returns "
      (:GROUP (:FONT :FACE :I) "integer") " as the result. This is used by " (:CL "write-byte") "." (:PAR))))
   " "
   (:SECTION :TITLE ("E " "Suggested Extensions to CLIM") :KIND :CHAPTER :NAME (6 10) " " (:LABEL :NAME "extensions")
    (:PAR)
    "This appendix describes some suggested extensions to CLIM. Conforming CLIM implementations need not implement any of these extensions. However, if a CLIM implementation chooses to implement any of this functionality, it is suggested that is conform to the suggested API."
    (:PAR) "All of the symbols documented in this appendix should be accessible as external symbols in the "
    (:CL "clim") " package." (:PAR) " "
    (:SECTION :TITLE ("E.1 " "Support for PostScript Output") :KIND :SECTION :NAME (2 6 10) (:PAR)
     "CLIM implementations may choose to implement a PostScript back-end. Such a back-end must include a medium that supports CLIM's medium protocol, and should support CLIM's output stream protocol as well."
     (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "with-output-to-postscript-stream")) :PARAMS
       ((:I "(stream-var file-stream  " (:GROUP (:FONT :FACE :TT) "&key ")
         "device-type multi-page scale-to-fit  orientation header-comments)  " (:GROUP (:FONT :FACE :TT) "&body ")
         "body"))
       :KIND ("Macro"))
      (:PAR) "Within " (:GROUP (:FONT :FACE :I) "body") ", " (:GROUP (:FONT :FACE :I) "stream-var")
      " is bound to a stream that produces PostScript code. This stream is suitable as a stream or medium argument to any CLIM output utility, such as "
      (:CL "draw-line*") " or " (:CL "write-string") ". A PostScript program describing the output to the "
      (:GROUP (:FONT :FACE :I) "stream-var") " stream will be written to " (:GROUP (:FONT :FACE :I) "file-stream") ". "
      (:GROUP (:FONT :FACE :I) "stream-var") " must be a symbol. " (:GROUP (:FONT :FACE :I) "file-stream")
      " is a stream." (:PAR) (:GROUP (:FONT :FACE :I) "device-type")
      " is a symbol that names some sort of PostScript display device. Its default value is unspecified, but must be a useful display device type for the CLIM implementation."
      (:PAR) (:GROUP (:FONT :FACE :I) "multi-page") " is a " (:TERM "boolean")
      " that specifies whether or not the output should be broken into multiple pages if it is larger than one page. How the output is broken into multiple pages, and how these multiple pages should be pieced together is unspecified. The default is "
      (:CL "nil") "." (:PAR) (:GROUP (:FONT :FACE :I) "scale-to-fit") " is a " (:TERM "boolean")
      " that specifies whether or not the output should be scaled to fit on a single page if it is larger than one page. The default is "
      (:CL "nil") ". It is an error if " (:GROUP (:FONT :FACE :I) "multi-page") " and " (:CL "scale-to-fit")
      " are both supplied as " (:TERM "true") "." (:PAR) (:GROUP (:FONT :FACE :I) "orientation") " may be one of "
      (:CL ":portrait") " (the default) or " (:CL ":landscape") ". It specifies how the output should be oriented."
      (:PAR) (:GROUP (:FONT :FACE :I) "header-comments")
      " allows the programmer to specify some PostScript header comment fields for the resulting PostScript output. The value of "
      (:GROUP (:FONT :FACE :I) "header-comments")
      " is a list consisting of alternating keyword and value pairs. These are the supported keywords:" (:PAR)
      (:UL (:LI (:CL ":title") "---specifies a title for the document, as it will appear in the \" ")
       (:LI (:CL ":for") "---specifies who the document is for. The associated value will appear in a \""))
      (:PAR) " ")
     (:DEFUN (:SIGNATURE :NAME ((:CL "new-page")) :PARAMS ((:I "stream")) :KIND ("Function")) (:PAR)
      "Give a PostScript stream " (:GROUP (:FONT :FACE :I) "stream") ", " (:CL "new-page")
      " sends all of the currently collected output to the related file stream (by emitting a PostScript "
      (:CL "showpage") " command), and resets the PostScript stream to have no output." (:PAR) " "))
    (:SECTION :TITLE ("E.2 " "Support for Reading Bitmap Files") :KIND :SECTION :NAME (2 6 10) (:PAR)
     "CLIM implementations may supply some functions that read standard bitmap and pixmaps files. The following is the suggested API for such functionality."
     (:PAR)
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "read-bitmap-file")) :PARAMS ((:I "type pathname " (:GROUP (:FONT :FACE :TT) "&key ")))
       :KIND ("Generic Function"))
      (:PAR) "Reads a bitmap file of type " (:GROUP (:FONT :FACE :I) "type") " from the file named by "
      (:GROUP (:FONT :FACE :I) "pathname") ". " (:GROUP (:FONT :FACE :I) "type")
      " is a symbol that indicates what type of bitmap file is to be read. " (:CL "read-bitmap-file") " can "
      (:CL "eql") "-specialize on " (:GROUP (:FONT :FACE :I) "type") "." (:PAR) (:CL "read-bitmap-file")
      " may take keyword arguments to provide further information to the method decoding the bitmap file." (:PAR)
      "For example, a CLIM implementation might support an " (:CL ":x11") " type. " (:CL "read-bitmap-file")
      " could take a " (:GROUP (:FONT :FACE :I) "format") " keyword argument, whose value can be either "
      (:CL ":bitmap") " or " (:CL ":pixmap") "." (:PAR) (:CL "read-bitmap-file")
      " will return two values. The first is a 2-dimensional array of \"pixel\" values. The second is a sequence of CLIM colors (or "
      (:CL "nil") " if the result is a monochrome image)." (:PAR) " ")
     (:DEFUN
      (:SIGNATURE :NAME ((:CL "make-pattern-from-bitmap-file")) :PARAMS
       ((:I "pathname " (:GROUP (:FONT :FACE :TT) "&key ") "type designs "
         (:GROUP (:FONT :FACE :TT) "&allow-other-keys ")))
       :KIND ("Function"))
      (:PAR) "Reads the contents of the bitmap file " (:GROUP (:FONT :FACE :I) "pathname") " and creates a CLIM "
      (:CL "pattern") " object that represents the file. " (:GROUP (:FONT :FACE :I) "type") " is as for "
      (:CL "read-bitmap-file") "." (:PAR) (:GROUP (:FONT :FACE :I) "designs")
      " is a sequence of CLIM designs (typically color objects) that will be used as the second argument in a call to "
      (:CL "make-pattern") ". " (:GROUP (:FONT :FACE :I) "designs")
      " must be supplied if no second value will be returned from " (:CL "read-bitmap-file") "." (:PAR)
      (:CL "make-pattern-from-bitmap-file") " will pass any additional keyword arguments along to "
      (:CL "read-bitmap-file") "." (:PAR))))
   " "
   (:SECTION :TITLE ("F " "Changes from CLIM 1.0") :KIND :CHAPTER :NAME (6 10) " " (:LABEL :NAME "changes") (:PAR)
    "This appendix lists the incompatible changes from CLIM 1.0 (and CLIM 0.9 for the API related to the windowing substrate and gadgets), and the rationale for those changes. They are listed on a chapter-by-chapter basis."
    (:PAR)
    "When the items say that a compatibility stub will be provided, this does not mean that this compatibility needs to be part of CLIM itself. It could be provided by a small compatibility package that defines stubs that translate from the old behavior to the new behavior at compile-time or run-time, or by some sort of conversion utility, or both. In the first case, compiler warnings should be generated to indicate that an obsolete form is being used."
    (:PAR) (:GROUP (:FONT :FACE :B) "Minor issue: ") " "
    (:GROUP (:FONT :FACE :SL)
     "There are still lots of things from the windowing part, and the frames, panes, and gadgets chapters that need to be included here. --- SWM")
    (:PAR)
    (:SECTION :TITLE ("Regions") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI (:CL "point-position*") " has been renamed to " (:CL "point-position")
       ", since the term \"position\" unambiguously refers to an " (:MATH "(x,y)")
       " coordinate pair. A compatibility function will be provided." (:PAR))
      (:LI (:CL "region-contains-point*-p") " has been renamed to " (:CL "region-contains-position-p")
       ", since the term \"position\" unambiguously refers to an " (:MATH "(x,y)")
       " coordinate pair. A compatibility function will be provided." (:PAR))
      (:LI "The use of " (:CL "region-set-function") " has been deprecated in favor of using the three classes "
       (:CL "standard-region-union") ", " (:CL "standard-region-intersection") ", and "
       (:CL "standard-region-difference") ", in keeping with the spirit of CLOS. " (:CL "region-set-function")
       " will be provided as a compatibility function. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Bounding Rectangles") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI (:CL "with-bounding-rectangle*") " used to have optional " (:GROUP (:FONT :FACE :I) "max-x") " and "
       (:GROUP (:FONT :FACE :I) "max-y") " arguments. They are now required." (:PAR))
      (:LI "The function " (:CL "bounding-rectangle-set-edges")
       " has been removed, since bounding rectangles have been made immutable. There is no replacement for it." (:PAR))
      (:LI (:CL "bounding-rectangle-position*") " has been renamed to " (:CL "bounding-rectangle-position")
       ", since the term \"position\" unambiguously refers to an " (:MATH "(x,y)")
       " coordinate pair. A compatibility function will be provided." (:PAR))
      (:LI "The functions " (:CL "bounding-rectangle-left") ", " (:CL "bounding-rectangle-top") ", "
       (:CL "bounding-rectangle-right") ", and " (:CL "bounding-rectangle-bottom") " have been replaced by "
       (:CL "bounding-rectangle-min-x") ", " (:CL "bounding-rectangle-min-y") ", " (:CL "bounding-rectangle-max-x")
       ", and " (:CL "bounding-rectangle-max-y")
       ". This is because left, top, right, and bottom are ill-specified. Compatibility functions will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Affine Transformations") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The function " (:CL "make-3-point-transformation") " has had its argument list changed from "
       (:GROUP (:FONT :FACE :I) "(point-1 point-1-image point-2 point-2-image point-3 point-3-image)") " to "
       (:GROUP (:FONT :FACE :I) "(point-1 point-2 point-3 point-1-image point-2-image point-3-image)")
       ". This was done because the original argument list did not group together inputs and output, which was confusing."
       (:PAR))
      (:LI "The function " (:CL "make-3-point-transformation*") " has had its argument list changed from "
       (:GROUP (:FONT :FACE :I) "(x1 y1 x1-image y1-image x2 y2 x2-image y2-image x3 y3 x3-image y3-image)") " to "
       (:GROUP (:FONT :FACE :I) "(x1 y1 x2 y2 x3 y3 x1-image y1-image x2-image y2-image x3-image y3-image)")
       ". This was done because the original argument list did not group together inputs and output, which was confusing."
       (:PAR))
      (:LI (:CL "compose-scaling-transformation") ", " (:CL "compose-translation-transformation") ", and "
       (:CL "compose-rotation-transformation") " have been replaced by the six functions "
       (:CL "compose-translation-with-transformation") ", " (:CL "compose-scaling-with-transformation") ", "
       (:CL "compose-rotation-with-transformation") ", " (:CL "compose-transformation-with-translation") ", "
       (:CL "compose-transformation-with-scaling") ", and " (:CL "compose-transformation-with-rotation")
       ". This was done because the six functions implement all of the optimized useful cases of composition of transformations, and new names are required for all six. Compatibility functions will be provided for the three CLIM 1.0 functions."
       (:PAR))
      (:LI (:CL "transform-point*") " and " (:CL "untransform-point*") " have been renamed to "
       (:CL "transform-position") " and " (:CL "untransform-position") ". Compatibility functions will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Properties of Sheets") :KIND :PARAGRAPH (:PAR) " ")
    (:SECTION :TITLE ("Sheet Protocols") :KIND :PARAGRAPH (:PAR) " ")
    (:SECTION :TITLE ("Ports, Grafts, and Mirrored Sheets") :KIND :PARAGRAPH (:PAR) " ")
    (:SECTION :TITLE ("Text Styles") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The macros " (:CL "with-text-style") ", " (:CL "with-text-family") ", " (:CL "with-text-face") ", and "
       (:CL "with-text-size") " have been changed to take the " (:GROUP (:FONT :FACE :I) "medium")
       " argument first and the text style (or family, face, or size) argument second. This was done in order to be consistent with all of the other macros that take a "
       (:GROUP (:FONT :FACE :I) "medium")
       " argument as the first argument. Compatibility code will be provided that attempts to detect the old syntax and massages it into the new syntax, although it will probably not be able to detect all cases."
       (:PAR))
      (:LI (:CL "add-text-style-mapping") " has been replaced by " (:CL "(setf text-style-mapping)")
       " to be consistent with Common Lisp conventions. A compatibility function will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Drawing in Color") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI (:CL "+foreground+") " and " (:CL "+background+") " have been renamed to " (:CL "+foreground-ink+") " and "
       (:CL "+background-ink+") ", for consistency with " (:CL "+flipping-ink+")
       ". Compatibility constants will be provided." (:PAR))
      (:LI (:CL "make-color-rgb") " and " (:CL "make-color-ihs") " have been renamed to " (:CL "make-rgb-color")
       " and " (:CL "make-ihs-color") ", by popular demand. Compatibility functions will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Extended Stream Output") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI (:CL "stream-cursor-position*") " and " (:CL "stream-increment-cursor-position*") " have been renamed to "
       (:CL "stream-cursor-position") " and " (:CL "stream-increment-cursor-position")
       ". Compatibility functions will be provided." (:PAR))
      (:LI "The function " (:CL "stream-set-cursor-position*") " has been replaced by "
       (:CL "(setf* stream-cursor-position)")
       " to be consistent with Common Lisp conventions. A compatibility function will be provided." (:PAR))
      (:LI "The function " (:CL "stream-vsp") " has been replace by " (:CL "stream-vertical-spacing")
       ". A compatibility function will be provided." (:PAR))
      (:LI "The macros " (:CL "with-end-of-line-action") " and " (:CL "with-end-of-page-action")
       " have been changed to take the " (:GROUP (:FONT :FACE :I) "stream")
       " argument first and the action argument second. This was done in order to be consistent with all of the other macros that take a "
       (:GROUP (:FONT :FACE :I) "stream")
       " argument as the first argument. Compatibility code will be provided that attempts to detect the old syntax and massages it into the new syntax, although it will probably not be able to detect all cases. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Output Recording") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The three protocol classes " (:CL "output-record") ", " (:CL "output-record-element") ", and "
       (:CL "displayed-output-record-element") " have been replaced by the two classes " (:CL "output-record") " and "
       (:CL "displayed-output-record") ". The predicates for the classes have been similarly changed." (:PAR))
      (:LI (:CL "output-record-position*") " has been renamed to " (:CL "output-record-position")
       ". A compatibility function will be provided." (:PAR))
      (:LI "The function " (:CL "output-record-set-position*") " has been replaced by "
       (:CL "(setf* output-record-position)")
       " to be consistent with Common Lisp conventions. A compatibility function will be provided." (:PAR))
      (:LI "The functions " (:CL "output-record-start-position*") ", " (:CL "output-record-set-start-position*") ", "
       (:CL "output-record-end-position*") ", " (:CL "output-record-set-end-position*") " have been replaced by "
       (:CL "output-record-start-cursor-position") ", " (:CL "(setf* output-record-start-cursor-position)") ", "
       (:CL "output-record-end-cursor-position") ", " (:CL "(setf* output-record-end-cursor-position)")
       " to better reflect their functionality. Compatibility functions will be provided." (:PAR))
      (:LI (:CL "replay-1") " has been renamed to " (:CL "replay-output-record") "." (:PAR))
      (:LI (:CL "output-record-elements") " and " (:CL "output-record-element-count") " have been renamed to "
       (:CL "output-record-children") " and " (:CL "output-record-count")
       ", since the term \"element\" is no longer used when referring to output records. Compatibility functions will be provided."
       (:PAR))
      (:LI (:CL "add-output-record-element") " and " (:CL "delete-output-record-element") " have been renamed to "
       (:CL "add-output-record") " and " (:CL "delete-output-record")
       ", and the argument order has been changed. Compatibility functions will be provided." (:PAR))
      (:LI (:CL "map-over-output-record-elements-containing-point*") " and "
       (:CL "map-over-output-record-elements-overlapping-region") " have been renamed to "
       (:CL "map-over-output-records-containing-position") " and " (:CL "map-over-output-records-overlapping-region")
       ". Compatibility functions will be provided." (:PAR))
      (:LI (:CL "linear-output-record") " and " (:CL "coordinate-sorted-set-output-record") " have been renamed to "
       (:CL "standard-sequence-output-record") " and " (:CL "standard-tree-output-record") "." (:PAR))
      (:LI (:CL "stream-draw-p") " and " (:CL "stream-record-p") " and their " (:CL "setf")
       " functions have been renamed to " (:CL "stream-drawing-p") " and " (:CL "stream-recording-p")
       " to better reflect their functionality. Compatibility functions will be provided." (:PAR))
      (:LI (:CL "output-recording-stream-output-record") ", "
       (:CL "output-recording-stream-current-output-record-stack") ", and "
       (:CL "output-recording-stream-text-output-record") " have been renamed to " (:CL "stream-output-history") ", "
       (:CL "stream-current-output-record") ", and " (:CL "stream-text-output-record")
       ". Compatibility functions will be provided." (:PAR))
      (:LI (:CL "add-output-record") " has been renamed to " (:CL "stream-add-output-record")
       ". Because of the change to " (:CL "add-output-record-element")
       " above, no compatibility function can be provided." (:PAR))
      (:LI (:CL "close-current-text-output-record") " has been renamed to " (:CL "stream-close-text-output-record")
       ". A compatibility function will be provided." (:PAR))
      (:LI (:CL "add-string-output-to-output-record") " and " (:CL "add-character-output-to-output-record")
       " have been renamed to " (:CL "stream-add-string-output") " and " (:CL "stream-add-character-output")
       ". Compatibility functions will be provided." (:PAR))
      (:LI (:CL "with-output-recording-options") " has had its " (:CL ":draw-p") " and " (:CL ":record-p")
       " keyword arguments changed to " (:CL ":draw") " and " (:CL ":record")
       " to conform to Common Lisp naming conventions. Compatibility code will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Table Formatting") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The " (:CL ":inter-column-spacing") ", " (:CL ":inter-row-spacing") ", and "
       (:CL ":multiple-columns-inter-column-spacing") " options to " (:CL "formatting-table") " have been renamed to "
       (:CL ":x-spacing") ", " (:CL ":y-spacing") ", and " (:CL ":multiple-columns-x-spacing")
       " in order to be consistent with the pane options. Compatibility options will be provided." (:PAR))
      (:LI "The " (:CL ":minimum-width") " and " (:CL ":minimum-height") " options to " (:CL "formatting-cell")
       " have been renamed to " (:CL ":min-width") " and " (:CL ":min-height")
       " in order to be consistent with the pane options. Compatibility options will be provided." (:PAR))
      (:LI "The " (:CL ":inter-column-spacing") " and " (:CL ":inter-row-spacing") " options to "
       (:CL "formatting-item-list") " and " (:CL "format-items") " have been renamed to " (:CL ":x-spacing") " and "
       (:CL ":y-spacing") " in order to be consistent with the pane options. Compatibility options will be provided."
       (:PAR))
      (:LI "The " (:CL ":no-initial-spacing") " option to " (:CL "formatting-item-list") " and " (:CL "format-items")
       " has been renamed to " (:CL ":initial-spacing")
       ", because inverted-sense flags are too hard to keep straight. The default for " (:CL ":no-initial-spacing")
       " was " (:TERM "true") ", therefore the default for " (:CL ":initial-spacing") " is " (:TERM "false")
       ". Compatibility options will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Graph Formatting") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The function " (:CL "format-graph-from-root") " has been renamed to " (:CL "format-graph-from-roots")
       ", since it now takes a sequence of root objects, rather than a single root object. The function "
       (:CL "format-graph-from-root") " will remain as a compatibility function that takes a single root object. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Incremental Redisplay") :KIND :PARAGRAPH (:PAR)
     (:UL (:LI (:CL "redisplay-1") " has been renamed to " (:CL "redisplay-output-record") ". ")) (:PAR) " ")
    (:SECTION :TITLE ("Extended Stream Input") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI (:CL "stream-pointer-position*") " has been renamed to " (:CL "stream-pointer-position")
       ". A compatibility function will be provided." (:PAR))
      (:LI "The function " (:CL "stream-set-pointer-position*") " has been replaced by "
       (:CL "(setf* stream-pointer-position)")
       " to be consistent with Common Lisp conventions. A compatibility function will be provided." (:PAR))
      (:LI "All of the clause arglists for " (:CL "tracking-pointer") " are specified with "
       (:GROUP (:FONT :FACE :TT) "&key")
       ", that is, they are named arguments rather than positional ones. This should not cause any problems, except for the one case that the "
       (:GROUP (:FONT :FACE :I) "character") " argument to the " (:CL ":keyboard") " clause has been renamed to "
       (:GROUP (:FONT :FACE :I) "gesture") "." (:PAR))
      (:LI "The function " (:CL "dragging-output-record") " has been renamed to " (:CL "drag-output-record")
       " to be consistent with our naming conventions. A compatibility function will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Presentation Types") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The argument list for " (:CL "with-output-as-presentation") " has been changed to make "
       (:GROUP (:FONT :FACE :I) "stream") ", " (:GROUP (:FONT :FACE :I) "object") ", and "
       (:GROUP (:FONT :FACE :I) "type")
       " be required arguments instead of keyword arguments. This is because it is always necessary to supply those arguments in order for "
       (:CL "with-output-as-presentation") " to work. Compatibility code will be provided to support the old syntax."
       (:PAR))
      (:LI "The " (:CL ":activation-characters") ", " (:CL ":additional-activation-characters") ", "
       (:CL ":blip-characters") ", and " (:CL ":additional-blip-characters") " keyword arguments to the "
       (:CL "accept") " functions have been renamed to " (:CL ":activation-gestures") ", "
       (:CL ":additional-activation-gestures") ", " (:CL ":delimiter-gestures") ", and "
       (:CL ":additional-delimiter-gestures")
       ". Compatibility code will be provided to support the old keyword arguments." (:PAR))
      (:LI
       "The arglists for presentation translators and their documentation and tester components have been changed to take a single positional "
       (:GROUP (:FONT :FACE :I) "object")
       " argument and a list of named (keyword) arguments. Except for translators that omit the "
       (:GROUP (:FONT :FACE :I) "object")
       " argument or have it in other than the initial position of the arglist, this will not pose a problem. This change can be detected."
       (:PAR))
      (:LI "The " (:GROUP (:FONT :FACE :I) "frame") " argument to " (:CL "find-presentation-translators")
       " has been changed to be a " (:GROUP (:FONT :FACE :I) "command-table")
       " argument. A check at run-time can detect when a frame is supplied to " (:CL "find-presentation-translators")
       " instead of a command table." (:PAR))
      (:LI "The " (:CL ":shift-mask") " keyword argument to " (:CL "test-presentation-translator") ", "
       (:CL "find-applicable-translators") ", " (:CL "presentation-matches-context-type") ", and "
       (:CL "find-innermost-applicable-presentation") " has been renamed to " (:CL ":modifier-state")
       " in order to be consistent with the device event terminology. Compatibility code will be provided to support the old keyword."
       (:PAR))
      (:LI (:CL "define-gesture-name")
       " is completely different from CLIM 1.1. There will be no compatibility code provided to support the old version of "
       (:CL "define-gesture-name") "." (:PAR))
      (:LI (:CL "dialog-view") " and " (:CL "+dialog-view+") " have been renamed to " (:CL "textual-dialog-view")
       " and " (:CL "+textual-dialog-view+") " in order to accurately reflect what they are. Likewise, "
       (:CL "menu-view") " and " (:CL "+menu-view+") " have been renamed to " (:CL "textual-menu-view") " and "
       (:CL "+textual-menu-view+") ". Compatibility classes and constants will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Input Editing and Completion Facilities") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI (:CL "*activation-characters*") ", " (:CL "*standard-activation-characters*") ", "
       (:CL "with-activation-characters") ", and " (:CL "activation-character-p") " have been renamed to "
       (:CL "*activation-gestures*") ", " (:CL "*standard-activation-gestures*") ", " (:CL "with-activation-gestures")
       ", and " (:CL "activation-gesture-p") ". Compatibility functions will remain for "
       (:CL "with-activation-characters") " and " (:CL "activation-character-p")
       ", but since the variables were not previously documented, no compatibility will be provided for them." (:PAR))
      (:LI (:CL "*blip-characters*") ", " (:CL "with-blip-characters") ", and " (:CL "blip-character-p")
       " have been renamed to " (:CL "*delimiter-gestures*") ", " (:CL "with-delimiter-gestures") ", and "
       (:CL "delimiter-gesture-p") ". Compatibility functions will remain for " (:CL "with-blip-characters") " and "
       (:CL "blip-character-p") ", but since " (:CL "*blip-characters*")
       " was not previously documented, no compatibility will be provided." (:PAR))
      (:LI (:CL "*abort-characters*") " has been renamed to " (:CL "*abort-gestures*") "." (:PAR))
      (:LI (:CL "*completion-characters*") ", " (:CL "*help-characters*") ", and " (:CL "*possibilities-characters*")
       " have been renamed to " (:CL "*completion-gestures*") ", " (:CL "*help-gestures*") ", and "
       (:CL "*possibilities-gestures*") "." (:PAR))
      (:LI
       "Input editing streams no longer use the interactive stream class. Instead, interactive streams are defined to be any stream that can potentially support input editing, and the class "
       (:CL "input-editing-stream") " now refers to input editor streams." (:PAR))
      (:LI (:CL "input-editor-buffer") ", " (:CL "input-position") ", " (:CL "insertion-pointer") ", and "
       (:CL "rescanning-p") " have been renamed to " (:CL "stream-input-buffer") ", " (:CL "stream-scan-pointer") ", "
       (:CL "stream-insertion-pointer") ", and " (:CL "stream-rescanning-p")
       ". Compatibility functions will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Menus") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The " (:CL ":inter-column-spacing") " and " (:CL ":inter-row-spacing") " options to " (:CL "menu-choose")
       " have been renamed to " (:CL ":x-spacing") " and " (:CL ":y-spacing")
       " in order to be consistent with the pane options. Compatibility options will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Command Processing") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The variable " (:CL "*unsupplied-argument*") " has been renamed to " (:CL "*unsupplied-argument-marker*")
       " in keeping with its functionality, and to match the new " (:CL "*numeric-argument-marker*") ". "
       (:CL "*unsupplied-argument*") " will be retained, but its use is deprecated." (:PAR))
      (:LI "The " (:CL ":inter-column-spacing") " and " (:CL ":inter-row-spacing") " options to "
       (:CL "display-command-table-menu") " have been renamed to " (:CL ":x-spacing") " and " (:CL ":y-spacing")
       " in order to be consistent with the pane options. Compatibility options will be provided." (:PAR))
      (:LI "The " (:CL ":test")
       " argument to the following functions has been removed, since the use of gesture names makes it unnecessary: "
       (:CL "add-command-to-command-table") ", " (:CL "(add-keystroke-to-command-table") ", and "
       (:CL "remove-keystroke-from-command-table") ". The " (:CL ":keystroke-test") " argument has been removed from "
       (:CL "read-command") " and " (:CL "read-command-using-keystrokes") " for the same reason. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Application Frames") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI "The " (:CL ":root") " argument has been removed from " (:CL "open-window-stream") " and "
       (:CL "make-application-frame") "." (:PAR))
      (:LI "The " (:CL ":layout") " option has been removed, and is replaced by the more general " (:CL ":layouts")
       " option. A compatibility hook will be provided that handles the old " (:CL ":layout") " option." (:PAR))
      (:LI "The function " (:CL "set-frame-layout") " has been replaced by " (:CL "(setf frame-current-layout)")
       " to be consistent with Common Lisp conventions. A compatibility function will be provided." (:PAR))
      (:LI "The function " (:CL "frame-top-level-window") " has been renamed to " (:CL "frame-top-level-sheet")
       ". A compatibility function will be provided." (:PAR))
      (:LI (:CL "command-enabled-p") ", " (:CL "enable-command") ", and " (:CL "disable-command")
       " have been replaced by " (:CL "command-enabled") " and " (:CL "(setf command-enabled)")
       ". Compatibility functions will be provided." (:PAR))
      (:LI (:CL "window-viewport-position*") " has been renamed to " (:CL "window-viewport-position")
       ". A compatibility function will be provided." (:PAR))
      (:LI (:CL "window-set-viewport-position*") " has been replaced by " (:GROUP "(setf* window-viewport-position)")
       ". A compatibility function will be provided. "))
     (:PAR) " ")
    (:SECTION :TITLE ("Panes") :KIND :PARAGRAPH (:PAR)
     (:UL
      (:LI (:CL "realize-pane") " and " (:CL "realize-pane-1") " have been renamed to " (:CL "make-pane") " and "
       (:CL "make-pane-1") ". A compatibility function will be provided for " (:CL "realize-pane") "." (:PAR))
      (:LI "The pane options " (:CL ":hs") ", " (:CL ":hs+") ", " (:CL ":hs-") ", " (:CL ":vs") ", " (:CL ":vs+")
       ", and " (:CL ":vs-") " have been replaced by the options " (:CL ":width") ", " (:CL ":max-width") ", "
       (:CL ":min-width") ", " (:CL ":height") ", " (:CL ":max-height") ", and " (:CL ":min-height")
       " to be more perspicuous, and to conform the the same options for the formatted output facilities. Compatibility options will be supplied."
       (:PAR))
      (:LI "The " (:CL ":nchars") " and " (:CL ":nlines")
       " pane options have been removed in favor of an extended syntax to the " (:CL ":width") " and " (:CL ":height")
       " options." (:PAR))
      (:LI "The pane layout options " (:CL ":halign") " and " (:CL ":valign") " have been renamed to " (:CL ":align-x")
       " and " (:CL ":align-y") " to conform with table formatting. Compatibility options will be supplied." (:PAR))
      (:LI "The pane layout options " (:CL ":hspace") " and " (:CL ":vspace") " have been renamed to "
       (:CL ":x-spacing") " and " (:CL ":y-spacing")
       " to conform with table formatting. Compatibility options will be supplied." (:PAR))
      (:LI "The term \"space req\" has been renamed to \"space requirement\". All of the functions with "
       (:CL "space-req") " in their names have been renamed to have " (:CL "space-requirement") " instead." (:PAR))
      (:LI (:CL "make-space-requirement") " no longer takes the " (:CL ":hs") " and " (:CL ":vs") " arguments, "
       (:GROUP (:FONT :FACE :I) "et al") ". It now takes " (:CL ":width") " and " (:CL ":height") ", "
       (:GROUP (:FONT :FACE :I) "et al") ". "))
     (:PAR)))
   (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part IX: " "Index") :NAME (10) " " (:PRINTINDEX) (:PAR))
  (:SECTION :KIND :PART :TITLE ("Part X: " "Annotation Playground") :NAME (10) (:PAR)
   (:SECTION :TITLE ("G " "Annotation Playground") :KIND :CHAPTER :NAME (1 10) (:PAR)
    "This section is to be replaced by a real \"About this Document\" section." (:PAR)
    "When you want to play with annotation support without actually affecting the specification itself, you may freely do so here."
    (:PAR) "If you have suggestions post then here." (:PAR))
   (:PAR))))