23 Presentation Types

CLIM provides a framework for defining the appearance and behavior of these user interface entities via the 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:

• Its displayed representation, textual or graphical

• Textual representation, for user input via the keyboard

• Pointer sensitivity, for user input via the pointer

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.

standard-presentation

[Class]

The instantiable output record class that represents presentations. present normally creates output records of this class. Members of this class are mutable.

:object

[Init arg]

:type

[Init arg]

:view

[Init arg]

:single-box

[Init arg]

:modifier

[Init arg]

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.

23.2.1 The Presentation Protocol

presentation-object

presentation

[Generic function]

Returns the object associated with the presentation presentation .

(setf presentation-object)

object presentation

[Generic function]

Changes the object associated with the presentation presentation to object .

presentation-type

presentation

[Generic function]

Returns the presentation type associated with the presentation presentation .

(setf presentation-type)

type presentation

[Generic function]

Changes the object associated with the presentation presentation to object .

presentation-single-box

presentation

[Generic function]

Returns the ``single box'' attribute of the presentation presentation , which controls how the presentation is highlighted and when it is sensitive. This will be one of four values:

• 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.

• 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.

• :position ---like t for determining whether the pointer is pointing at the presentation, but like nil for highlighting.

• :highlighting ---like nil for determining whether the pointer is pointing at the presentation, but like t for highlighting.

presentation-modifier

presentation

[Generic function]

Returns the ``modifier'' associated with the presentation 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 object after a user somehow ``edits'' the presentation.

23.3 Presentation Types

The parameters ``parameterize'' the type, just as in a Common Lisp type specifier. The function 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.

The options are alternating keywords and values that affect the use or appearance of the presentation, but not its semantic meaning. The 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 :description is accepted by all types; if it is a non-nil value, then the value must be a string that describes the type and overrides the description supplied by the type's definition.

Every presentation type is associated with a CLOS class. If name is a class object or the name of a class, and that class is not a built-in-class , that class is the associated class. Otherwise, define-presentation-type defines a class with metaclass presentation-type-class and superclasses determined by the presentation type definition. This class is not named name , since that could interfere with built-in Common Lisp types such as and , member , and integer . class-name of this class returns a list (presentation-type name ) . presentation-type-class is a subclass of standard-class .

Implementations are permitted to require programmers to evaluate the defclass form first in the case when the same name is used in both a defclass and a define-presentation-type .

Every CLOS class (except for built-in classes) is a presentation type, as is its name. If it has not been defined with define-presentation-type , it allows no parameters and no options.

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.

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.

23.3.1 Defining Presentation Types

options is a list of option specifiers. It defaults to nil . An option specifier is either a symbol or a list (symbol &optional default supplied-p presentation-type accept-options ), where symbol , default , and supplied-p are as in a normal lambda-list. If presentation-type and accept-options are present, they specify how to accept a new value for this option from the user. symbol can also be specified in the (keyword variable ) form allowed for Common Lisp lambda lists. symbol is a variable that is visible within inherit-from and within most of the methods created with define-presentation-method . The keyword corresponding to symbol can be used as an option in the third form of a presentation type specifier. An option specifier for the standard option :description is automatically added to options if an option with that keyword is not present, however it does not produce a visible variable binding.

Unsupplied optional or keyword parameters default to * (as in deftype ) if no default is specified in parameters . Unsupplied options default to nil if no default is specified in options .

inherit-from is a form that evaluates to a presentation type specifier for another type from which the new type inherits. inherit-from can access the parameter variables bound by the parameters lambda list and the option variables specified by options . If name is or names a CLOS class (other than a built-in-class ), then inherit-from must specify the class's direct superclasses (using and to specify multiple inheritance). It is useful to do this when you want to parameterize previously defined CLOS classes.

If inherit-from is unsupplied, it defaults as follows: If 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 and to specify multiple inheritance). Otherwise, the type named by name inherits from standard-object .

description is a string or nil . This should be the term for an instance for the type being defined. If it is nil or unsupplied, a description is automatically generated; it will be a ``prettied up'' version of the type name, for example, small-integer would become "small integer" . You can also write a describe-presentation-type presentation method. description is implemented by the default describe-presentation-type method, so description only works in presentation types where that default method is not shadowed.

history can be t (the default), which means this type has its own history of previous inputs, 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 presentation-type-history presentation method.

Every presentation type must define or inherit presentation methods for accept and 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 accept need not be defined.

If a presentation type has parameters , it must define presentation methods for presentation-typep and presentation-subtypep that handle the parameters, or inherit appropriate presentation methods. In many cases it should also define presentation methods for describe-presentation-type and presentation-type-specifier-p .

There are certain restrictions on the 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. and can be used for multiple inheritance, but or , not , and satisfies cannot be used.

None of the arguments, except inherit-from , is evaluated.

23.3.2 Presentation Type Abbreviations

name must be a symbol and must not be the name of a CLOS class.

The equivalent-type form might be evaluated at compile time if presentation type abbreviations are expanded by compiler optimizers. Unlike inherit-from , equivalent-type can perform arbitrary computations and is not called with dummy parameter and option values. The type specifier produced by evaluating equivalent-type can be a real presentation type or another abbreviation. If the type specifier doesn't include the standard option :description , the option is automatically copied from the abbreviation to its expansion.

Note that you cannot define any presentation methods on a presentation type abbreviation. If you need methods, use define-presentation-type instead.

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

(define-presentation-type-abbreviation octal-integer (&optional low high) 
    `((integer ,low ,high) :base 8 :description "octal integer"))

expand-presentation-type-abbreviation-1

type &optional env

[Function]

If the presentation type specifier type is a presentation type abbreviation, or is an and , or , sequence , or sequence-enumerated that contains a presentation type abbreviation, then this expands the type abbreviation once, and returns two values, the expansion and t . If type is not a presentation type abbreviation, then the values type and nil are returned.

env is a macro-expansion environment, as for macroexpand .

expand-presentation-type-abbreviation

type &optional env

[Function]

expand-presentation-type-abbreviation is like expand-presentation-type-abbreviation-1 , except that type is repeatedly expanded until all presentation type abbreviations have been removed.

23.3.3 Presentation Methods

(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))

define-presentation-generic-function

generic-function-name presentation-function-name lambda-list &rest options

[Macro]

Defines a generic function that will be used for presentation methods. generic-function-name is a symbol that names the generic function that will be used internally by CLIM for the individual methods, presentation-function-name is a symbol that names the function that programmers will call to invoke the method, and lambda-list and options are as for defgeneric .

There are some ``special'' arguments in lambda-list that are known about by the presentation type system. The first argument in lambda-list must be either type-key or type-class ; this argument is used by CLIM to implement method dispatching. The second argument may be parameters , meaning that, when the method is invoked, the type parameters will be passed to it. The third argument may be options , meaning that, when the method is invoked, the type options will be passed to it. Finally, an argument named type must be included in lambda-list ; when the method is called, type argument will be bound to the presentation type specifier.

For example, the accept presentation generic function might be defined as follows:

(define-presentation-generic-function present-method present
  (type-key parameters options object type stream view
   &key acceptably for-context-type))

define-presentation-method

name qualifiers* specialized-lambda-list &body body

[Macro]

Defines a presentation method for the function named name on the presentation type named in specialized-lambda-list . specialized-lambda-list is a CLOS specialized lambda list for the method, and its contents varies depending on what name is. qualifiers* is zero or more of the usual CLOS method qualifier symbols. define-presentation-method must support at least standard method combination (and therefore the :before , :after , and :around method qualifiers). Some CLIM implementations may support other method combination types, but this is not required.

body defines the body of the method. body may have zero or more declarations as its first forms.

All presentation methods have an argument named type that must be specialized with the name of a presentation type. The value of type is a presentation type specifier, which can be for a subtype that inherited the method.

All presentation methods except presentation-subtypep have lexical access to the parameters from the presentation type specifier. Presentation methods for the functions accept , present , describe-presentation-type , presentation-type-specifier-p , and accept-present-default also have lexical access to the options from the presentation type specifier.

define-default-presentation-method

name qualifiers* specialized-lambda-list &body body

[Macro]

Like 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.

funcall-presentation-generic-function

presentation-function-name &rest arguments

[Macro]

Calls the presentation generic function named by presentation-function-name on the arguments arguments . arguments must match the arguments specified by the define-presentation-generic-function that was used to define the presentation generic function, excluding the type-key , type-class , parameters , and options arguments, which are filled in by CLIM.

funcall-presentation-generic-function is analogous to funcall .

The presentation-function-name argument is not evaluated.

For example, to call the present presentation generic function, one might use the following:

(funcall-presentation-generic-function present
  object presentation-type stream view)

The presentation-function-name argument is not evaluated.

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.

For all of the presentation methods, the type will always be specialized. For those methods that take a view argument, implementors and programmers may specialize it as well. The other arguments are not typically specialized.

present

object type stream view &key acceptably for-context-type

[Presentation Method]

The present presentation method is responsible for displaying the representation of object having presentation type type for a particular view view . The method's caller takes care of creating the presentation, the method simply displays the content of the presentation.

The present method can specialize on the 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 present method for the textual-view view must be defined if the programmer wants to allow objects of that type to be displayed textually.

Implementation note: the actual argument list to the present method is
(type-key parameters options object type stream view &key acceptably for-context-type)
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 type .). parameters and 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 present .

Implementation note: the actual generic function of the present method is an internal generic function, not the function whose name is present . Similar internal generic functions are used for all presentation methods.

accept

type stream view &key default default-type

[Presentation Method]

The accept method is responsible for ``parsing'' the representation of the presentation type type for a particular view view . The 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.

The accept method can specialize on the view argument in order to define more than one input view for the data. The accept method for the textual-view view must be defined if the programmer wants to allow objects of that type to entered via the keyboard.

Note that accept presentation methods can call accept recursively. In this case, the programmer should be careful to specify nil for :prompt and :display-default unless recursive prompting is really desired.

Implementation note: the actual argument list to the accept method is
(type-key parameters options type stream view &key default default-type)

describe-presentation-type

type stream plural-count

[Presentation Method]

The describe-presentation-type method is responsible for textually describing the presentation type type . stream is a stream, and will not be nil as it can be for the describe-presentation-type function.

Implementation note: the actual argument list to the describe-presentation-type method is
(type-key parameters options type stream plural-count)

presentation-type-specifier-p

type

[Presentation Method]

The presentation-type-specifier-p method is responsible for checking the validity of the parameters and options for the presentation type type . The default method returns t .

Implementation note: the actual argument list to the presentation-type-specifier-p method is
(type-key parameters options type)

presentation-typep

object type

[Presentation Method]

The presentation-typep method is called when the presentation-typep function requires type-specific knowledge. If the type name in the presentation type type is a CLOS class or names a CLOS class, the method is called only if object is a member of the class and type contains parameters, and the method simply tests whether object is a member of the subtype specified by the parameters. For non-class types, the method is always called.

Implementation note: the actual argument list to the presentation-typep method is
(type-key parameters object type)

presentation-subtypep

type putative-supertype

[Presentation Method]

presentation-subtypep walks the type lattice (using map-over-presentation-supertypes ) to determine whethe or not the presentation type type is a subtype of thepresentation type putative-supertype , without looking at the type parameters. When a supertype of type has been found whose name is the same as the name of putative-supertype , then the subtypep method for that type is called in order to resolve the question by looking at the type parameters (that is, if the subtypep method is called, type and putative-supertype are guaranteed to be the same type, differing only in their parameters). If putative-supertype is never found during the type walk, then presentation-subtypep will never call the presentation-subtypep presentation method for putative-supertype .

Unlike all other presentation methods, presentation-subtypep receives a type argument that has been translated to the presentation type for which the method is specialized; type is never a subtype. The method is only called if putative-supertype has parameters and the two presentation type specifiers do not have equal parameters. The method must return the two values that presentation-subtypep returns.

Since presentation-subtypep takes two type arguments, the parameters are not lexically available as variables in the body of a presentation method.

Implementation note: the actual argument list to the presentation-subtypep method is
(type-key type putative-supertype)

map-over-presentation-type-supertypes

function type

[Presentation Method]

This method is called in order to apply function to the superclasses of the presentation type type .

Implementation note: the actual argument list to the map-over-presentation-type-supertypes method is
(type-class function type)

accept-present-default

type stream view default default-supplied-p present-p query-identifier

[Presentation Method]

The accept-present-default method is called when accept turns into present inside of accepting-values . The default method calls present or describe-presentation-type depending on whether default-supplied-p is true or false , respectively.

The boolean default-supplied-p will be true only in the case when the :default option was explicitly supplied in the call to accept that invoked accept-present-default .

Implementation note: the actual argument list to the accept-present-default method is
(type-key parameters options type stream view default default-supplied-p present-p query-identifier)

presentation-type-history

type

[Presentation Method]

This method is responsible for returning a history object for the presentation type type .

Implementation note: the actual argument list to the presentation-type-history method is
(type-key parameters type)

presentation-default-preprocessor

default type &key default-type

[Presentation Method]

This method is responsible for taking the object default , and coercing it to match the presentation type type (which is the type being accepted) and default-type (which is the presentation type of 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 type and 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 type .

Implementation note: the actual argument list to the presentation-default-preprocessor method is
(type-key parameters default type &key default-type)

presentation-refined-position-test

type record x y

[Presentation Method]

This method used to definitively answer hit detection queries for a presentation, that is, determining that the point (x,y) is contained within the output record record . Its contract is exactly the same as for output-record-refined-position-test , except that it is intended to specialize on the presentation type type .

Implementation note: the actual argument list to the presentation-refined-position-test method is
(type-key parameters options type record x y)

highlight-presentation

type record stream state

[Presentation Method]

This method is responsible for drawing a highlighting box around the presentation record on the output recording stream stream . state will be either :highlight or :unhighlight .

Implementation note: the actual argument list to the highlight-presentation method is
(type-key parameters options type record stream state)

23.3.4 Presentation Type Functions

type can be a presentation type abbreviation.

presentation-type-parameters

type-name &optional env

[Function]

Returns a lambda-list, the parameters specified when the presentation type or presentation type abbreviation whose name is type-name was defined. type-name is a symbol or a class. env is a macro-expansion environment, as in find-class .

presentation-type-options

type-name &optional env

[Function]

Returns the list of options specified when the presentation type or presentation type abbreviation whose name is type-name was defined. This does not include the standard options unless the presentation-type definition mentioned them explicitly. type-name is a symbol or a class. env is a macro-expansion environment, as in find-class .

with-presentation-type-decoded

(name-var &optional parameters-var options-var) type &body body

[Macro]

The specified variables are bound to the components of the presentation type specifier produced by evaluating type , the forms in body are executed, and the values of the last form are returned. name-var , if non-nil , is bound to the presentation type name. parameters-var , if non-nil , is bound to a list of the parameters. options-var , if non-nil , is bound to a list of the options. When supplied, name-var , parameters-var , and options-var must be symbols.

The name-var , parameters-var , and options-var arguments are not evaluated. body may have zero or more declarations as its first forms.

presentation-type-name

type

[Function]

Returns the presentation type name of the presentation type specifier type . This function is provided as a convenience. It could be implemented with the following code:

(defun presentation-type-name (type)
  (with-presentation-type-decoded (name) type
    name))

The value of the form type must be a presentation type specifier whose name is type-name . The type-name and type arguments are not evaluated. body may have zero or more declarations as its first forms.

with-presentation-type-options

(type-name type) &body body

[Macro]

Variables with the same name as each option in the definition of the presentation type are bound to the option values in type , if present, or else to the defaults specified in the definition of the presentation type. The forms in body are executed in the scope of these variables and the values of the last form are returned.

The value of the form type must be a presentation type specifier whose name is type-name . The type-name and type arguments are not evaluated. body may have zero or more declarations as its first forms.

presentation-type-specifier-p

object

[Function]

Returns true if object is a valid presentation type specifier , otherwise returns false .

presentation-typep

object type

[Function]

Returns true if object is of the presentation type specified by the presentation type specifier type , otherwise returns false .

type may not be a presentation type abbreviation.

This is analogous to the Common Lisp typep function.

presentation-type-of

object

[Function]

Returns a presentation type of which object is a member. 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.

If presentation-type-of cannot determine the presentation type of the object, it may return either expression or t .

This is analogous to the Common Lisp typep function.

presentation-subtypep

type putative-supertype

[Function]

Answers the question ``is the type specified by the presentation type specifier type a subtype of the type specified by the presentation type specifier putative-supertype ?''. presentation-subtypep returns two values, subtypep and known-p . When known-p is true , subtypep can be either true (meaning that type is definitely a subtype of putative-supertype ) or false (meaning that type is definitely not a subtype of putative-supertype ). When known-p is false , then subtypep must also be false ; this means that the answer cannot reliably be determined.

type may not be a presentation type abbreviation.

This is analogous to the Common Lisp subtypep function.

map-over-presentation-type-supertypes

function type

[Function]

Calls the function function on the presentation type specifier type and each of its supertypes. 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. 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.

presentation-type-direct-supertypes

type

[Function]

Returns a sequence consisting of the names of all of the presentation types that are direct supertypes of the presentation type specifier type , or nil if type has no supertypes. The consequences of modifying the returned sequence are unspecified.

find-presentation-type-class

name &optional (errorp t ) environment

[Function]

Returns the class corresponding to the presentation type named name , which must be a symbol or a class object. errorp and environment are as for find-class .

class-presentation-type-name

class &optional environment

[Function]

Returns the presentation type name corresponding to the class class . This is essentially the inverse of find-presentation-type-class . environment is as for find-class .

default-describe-presentation-type

description stream plural-count

[Function]

Performs the default actions for describe-presentation-type , notably pluralization and prepending an indefinite article if appropriate. description is a string or a symbol, typically the :description presentation type option or the :description option to define-presentation-type . plural-count is as for describe-presentation-type .

make-presentation-type-specifier

type-name-and-parameters &rest options

[Function]

A convenient way to assemble a presentation type specifier with only non-default options included. This is only useful for abbreviation expanders, not for :inherit-from . type-name-and-parameters is a presentation type specifier, which must be in the (type-name parameters... ) form. options are alternating keywords and values that are added as options to the presentation type specifier, except that if a value is equal to type-name 's default, that option is omitted, producing a more concise presentation type specifier.

23.4 Typed Output

with-output-as-presentation

(stream object type &key modifier single-box allow-sensitive-inferiors parent record-type &allow-other-keys ) &body body

[Macro]

The output of body to the extended output recording stream is used to generate a presentation whose underlying object is object and whose presentation type is 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 :allow-sensitive-inferiors nil was specified at a higher level, in which case the presentation object is not inserted into the history. with-output-as-presentation returns the presentation corresponding to the output.

The stream argument is not evaluated, and must be a symbol that is bound to an extended output stream or output recording stream. If stream is t , *standard-output* is used. body may have zero or more declarations as its first forms.

type may be a presentation type abbreviation.

modifier , which defaults to 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 object after a user somehow ``edits'' the presentation. modifier must have indefinite extent.

single-box is used to specify the presentation-single-box component of the resulting presentation. It can take on the values described under presentation-single-box .

When the boolean allow-sensitive-inferiors is false , nested calls to present or with-output-as-presentation inside this one will not generate presentations. The default is true .

parent specifies what output record should serve as the parent for the newly created presentation. If unspecified, stream-current-output-record of stream will be used as the parent.

record-type specifies the class of the presentation output record to be created. It defaults to 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.

All arguments of this macro are evaluated.

For example,

(with-output-as-presentation (stream #p"foo" 'pathname)
  (princ "FOO" stream))

The returned value of present is the presentation object that contains the output corresponding to the object.

present must be implemented by first expanding any presentation type abbreviations (type and for-context-type ), and then calling stream-present on stream , object , type , and the remaining keyword arguments, which are described below.

stream-present

stream object type &key view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type

[Generic function]

stream-present is the per-stream implementation of present , analogous to the relationship between write-char and stream-write-char . All extended output streams and output recording streams must implement a method for stream-present . The default method (on standard-extended-output-stream ) implements the following behavior.

The object object of type type is presented to the stream stream by calling the type's present method for the supplied view view . The returned value is the presentation containing the output corresponding to the object.

type is a presentation type specifier. view is a view object that defaults to stream-default-view of stream .

for-context-type is a presentation type specifier that is passed to the present method for type , which can use it to tailor how the object will be presented. for-context-type defaults to type .

modifier , single-box , allow-sensitive-inferiors , and record-type are the same as for with-output-as-presentation .

acceptably defaults to nil , which requests the present method to produce text designed to be read by human beings. If acceptably is t , it requests the present method to produce text that is recognized by the accept method for for-context-type . This makes no difference to most presentation types.

The boolean sensitive defaults to true . If it is false , no presentation is produced.

present-to-string

object &optional type &key view acceptably for-context-type string index

[Function]

Same as present inside with-output-to-string . If string is supplied, it must be a string with a fill pointer. When index is supplied, it is used as an index into string . view , acceptably , and for-context-type are as for present .

The first returned value is the string. When string is supplied, a second value is returned, the updated index .

23.5 Context-dependent (Typed) Input

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. *input-context* and the elements in it may have dynamic extent.

input-context-type

context-entry

[Function]

Given one element from *input-context* , context-entry , returns the presentation type of the context entry.

with-input-context

(type &key override) (&optional object-var type-var event-var options-var) form &body pointer-cases

[Macro]

Establishes an input context of presentation type type ; this must be done by binding *input-context* to reflect the new input context. When the boolean override is false (the default), this invocation of 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 override is true , it overrides the current input context rather than nesting inside the current input context.

type can be a presentation type abbreviation.

After establishing the new input context, form is evaluated. If no pointer gestures are made by the user during the evaluation of form , the values of form are returned. Otherwise, one of the 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 call-presentation-menu and throw-highlighted-presentation .) pointer-cases is constructed like a typecase statement clause list whose keys are presentation types; the first clause whose key satisfies the condition (presentation-subtypep type key ) is the one that is chosen.

During the execution of one of the pointer-cases , object-var is bound to the object that was clicked on (the first returned value from the presentation translator that was invoked), type-var is bound to its presentation type (the second returned value from the translator), and event-var is bound to the pointer button event that was used. options-var is bound to any options that a presentation translator might have returned (the third value from the translator), and will be either nil or a list of keyword-value pairs. object-var , type-var , event-var , and options-var must all be symbols.

type , stream , and override are evaluated, the others are not.

For example,

(with-input-context ('pathname)
                    (path)
     (read)
   (pathname
     (format t "~&The pathname ~A was clicked on." path)))

accept must be implemented by first expanding any presentation type abbreviations (type , default-type , and history ), handling the interactions between the default, default type, and presentation history, prompting the user by calling prompt-for-accept , and then calling stream-accept on stream , type , and the remaining keyword arguments.

stream-accept

stream type &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

[Generic function]

stream-accept is the per-stream implementation of accept , analogous to the relationship between read-char and stream-read-char . All extended input streams must implement a method for stream-accept . The default method (on standard-extended-input-stream ) simply calls accept-1 .

The arguments and overall behavior of stream-accept are as for accept-1 .

Rationale: the reason accept is specified as a three-function ``trampoline'' is to allow close tailoring of the behavior of accept . accept itself is the function that should be called by application programmers. CLIM implementors will specialize stream-accept on a per-stream basis. (For example, the behavior of accepting-values can be implemented by creating a special class of stream that turns calls to accept into fields of a dialog.) accept-1 is provided as a convenient function for the stream-accept methods to call when they require the default behavior.

accept-1

stream type &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

[Function]

Requests input of type type from the stream stream . type must be a presentation type specifier. view is a view object that defaults to stream-default-view of stream . accept-1 returns two values, the object representing the input and its presentation type. (If frame-maintain-presentation-histories is true for the current frame, then the returned object is also pushed on to the presentation history for that object.)

accept-1 establishes an input context via with-input-context , and then calls the accept presentation method for type and view . When called on an interactive stream, accept must allow input editing; see Chapter Input Editing and Completion Facilities for a discussion of input editing. The call to accept will be terminated when the 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 accept method is terminated.

A top-level accept satisfied by keyboard input discards the terminating keyboard gesture (which will be either a delimiter or an activation gesture). A nested call to accept leaves the terminating gesture unread.

If the user clicked on a matching presentation, accept-1 will insert the object into the input buffer by calling presentation-replace-input on the object and type returned by the presentation translator, unless either the boolean replace-input is false or the presentation translator returned an :echo option of false . replace-input defaults to true , but this default is overridden by the translator explicitly returning an :echo option of false .

If default is supplied, then it and default-type are returned as values from accept-1 when the input is empty. default-type must be a presentation type specifier. If default is not supplied and provide-default is true (the default is false ), then the default is determined by taking the most recent item from the presentation type history specified by history . If insert-default is true and there is a default, the default will be inserted into the input stream by calling presentation-replace-input .

history must be either 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 accept . history defaults to type .

prompt can be t , which prompts by describing the type, nil , which suppresses prompting, or a string, which is displayed as a prompt (via write-string ). The default is t , which produces ``Enter a type :'' in a top-level call to accept or ``(type )'' in a nested call to accept .

If the boolean display-default is true , the default is displayed (if one was supplied). If display-default is false , the default is not displayed. display-default defaults to true if prompt was provided, otherwise it defaults to false .

prompt-mode can be :normal (the default) or :raw , which suppresses putting a colon after the prompt and/or default in a top-level accept and suppresses putting parentheses around the prompt and/or default in a nested accept .

query-identifier is used within accepting-values to identify the field within the dialog. The active-p argument (which defaults to t ) can be used to control whether a field within an accepting-values is active; when 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.

activation-gestures is a list of gesture names that will override the current activation gestures (which are stored in *activation-gestures* ). Alternatively, additional-activation-gestures can be supplied to add activation gestures without overriding the current ones. See Chapter Input Editing and Completion Facilities for a discussion of activation gestures.

delimiter-gestures is a list of gesture names that will override the current delimiter gestures (which are stored in *delimiter-gestures* ). Alternatively, additional-delimiter-gestures can be supplied to add delimiter gestures without overriding the current ones. See Chapter Input Editing and Completion Facilities for a discussion of delimiter gestures.

accept-from-string

type string &key view default default-type start end

[Function]

Like accept , except that the input is taken from string , starting at the position specified by start and ending at end . view , default , and default-type are as for accept .

accept-from-string returns an object and a presentation type (as in accept ), but also returns a third value, the index at which input terminated.

prompt-for-accept

stream type view &rest accept-args &key

[Generic function]

Called by accept to prompt the user for input of presentation type type on the stream stream for the view view . accept-args are all of the keyword arguments supplied to accept . The default method (on standard-extended-input-stream ) simply calls prompt-for-accept-1 .

prompt-for-accept-1

stream type &key default default-type display-default prompt prompt-mode &allow-other-keys

[Function]

Prompts the user for input of presentation type type on the stream stream .

If the boolean display-default is true , then the default is displayed; otherwise, the default is not displayed. When the default is being displayed, default and default-type are the taken as the object and presentation type of the default to display. display-default defaults to true if prompt is non-nil , otherwise it defaults to false .

If prompt is nil , no prompt is displayed. If it is a string, that string is displayed as the prompt. If prompt is t (the default), the prompt is generated by calling describe-presentation-type to produce a prompt of the form ``Enter a type :'' in a top-level call to accept , or ``(type )'' in a nested call to accept .

prompt-mode can be :normal (the default) or :raw , which suppresses putting a colon after the prompt and/or default in a top-level accept and suppresses putting parentheses around the prompt and/or default in a nested accept .

23.6 Views

view	[Protocol Class]

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 view. Subclasses of view must obey the view protocol.All of the view classes are immutable.

viewp

object

[Predicate]

Returns true if object is a view , otherwise returns false .

textual-view

[Class]

The instantiable class representing all textual views, a subclass of view . Presentation methods that apply to a textual view must only do textual input and output (such as read-char and write-string ).

textual-menu-view

[Class]

The instantiable class that represents the default view that is used inside menu-choose for frame managers that are not using a gadget-oriented look and feel. It is a subclass of textual-view .

textual-dialog-view

[Class]

The instantiable class that represents the default view that is used inside accepting-values dialogs for frame managers that are not using a gadget-oriented look and feel. It is a subclass of textual-view .

gadget-view

[Class]

The instantiable class representing all gadget views, a subclass of view .

gadget-menu-view

[Class]

The instantiable class that represents the default view that is used inside menu-choose for frame managers that are using a gadget-oriented look and feel. It is a subclass of gadget-view .

gadget-dialog-view

[Class]

The instantiable class that represents the default view that is used inside accepting-values dialogs for frame managers that are using a gadget-oriented look and feel. It is a subclass of gadget-view .

pointer-documentation-view

[Class]

The instantiable class that represents the default view that is used when computing pointer documentation. It is a subclass of textual-view .

+textual-view+

[Constant]

+textual-menu-view+

[Constant]

+textual-dialog-view+

[Constant]

+gadget-view+

[Constant]

+gadget-menu-view+

[Constant]

+gadget-dialog-view+

[Constant]

+pointer-documentation-view+

[Constant]

These are objects of class textual-view , textual-menu-view , textual-dialog-view , gadget-view , gadget-menu-view , gadget-dialog-view , and pointer-documentation-view , respectively.

stream-default-view

stream

[Generic function]

Returns the default view for the extended stream stream . accept and present get the default value for the view argument from this. All extended input and output streams must implement a method for this generic function.

(setf stream-default-view)

view stream

[Generic function]

Changes the default view for stream to the view view . All extended input and output streams must implement a method for this generic function.

23.7 Presentation Translators

Note that the exact representation of a presentation translator has been left explicitly unspecified.

23.7.1 Defining Presentation Translators

command-table is a command table designator . The translator created by this invocation of define-presentation-translator will be stored in the command table command-table .

gesture is a gesture name that names a pointer gesture (described in Section Gestures and 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 applicability , or matching , in detail below.) gesture defaults to :select .

tester is either a function or a list of the form
(tester-arglist . tester-body)
where tester-arglist takes the same form as arglist (see below), and tester-body is the body of the tester. The tester must return either true or false . If it returns false , then the translator is definitely not applicable. If it returns true , then the translator might be applicable, and the body of the translator might be run (if tester-definitive is 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 true .

When the boolean tester-definitive is 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 tester-definitive is false . When there is no explicitly supplied tester, the tester supplied by CLIM is assumed to be definitive.

Both documentation and pointer-documentation are objects that will be used for documenting the translator. pointer-documentation will be used to generate documentation for the pointer documentation window; the documentation generated by pointer-documentation should be very brief and computing it should be very fast and preferably not cons. documentation is used to generate such things as items in the :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
(doc-arglist . doc-body)
where doc-arglist takes the same form as arglist , but includes a named (keyword) stream argument as well (see below), and doc-body is the body of the documentation function. The body of the documentation function should write the documentation to stream . The default for documentation is 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 pointer-documentation is documentation .

menu must be t or nil . When it is t , the translator will be included in the :menu -gesture menu if it matches. When it is nil , the translator will not be included in the :menu -gesture menu. Other non-nil values are reserved for future extensions to allow multiple presentation translator menus.

priority is either 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.

arglist , tester-arglist , and doc-arglist are each an argument list that must ``match'' the following ``canonical'' argument list.
(object &key presentation context-type frame event window x y)
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 string-equal to do the comparison).

In the body of the translator (or the tester), the positional object argument will be bound to the presentation's object. The named arguments presentation will be bound to the presentation that was clicked on, context-type will be bound to the presentation type of the context that actually matched, frame will be bound to the application frame that is currently active (usually *application-frame* ), event will be bound to the pointer button event that the user used, window will be bound to the window stream from which the event came, and x and y will be bound to the x and y positions within window that the pointer was at when the event occurred. The special variable *input-context* will be bound to the current input context. Note that, in many implementations context-type and *input-context* will have dynamic extent, so programmers should not store without first copying them.

body is the body of the translator, and is run in the context of the application. 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 presentation-typep of to-type , and the second value is a presentation type that must be presentation-subtypep of to-type . The consequences are unspecified if the object is not presentation-typep of to-type or the type is not presentation-subtypep of to-type . The first two returned values of body are used, in effect, as the returned values for the call to accept that established the matching input context.

The third value returned by body must either be nil or a list of options (as keyword-value pairs) that will be interpreted by accept . The only option defined so far is :echo , whose value must be either true (the default) or false . If it is true , the object returned by the translator will be ``echoed'' by accept , which will use presentation-replace-input to insert the textual representation of the object into the input buffer. If it is false , the object will not be echoed.

None of define-presentation-translator 's arguments is evaluated.

define-presentation-to-command-translator

name (from-type command-name command-table &key gesture tester documentation pointer-documentation menu priority echo) arglist &body body

[Macro]

This is similar to define-presentation-translator , except that the to-type will be derived to be the command named by command-name in the command table command-table . command-name is the name of the command that this translator will translate to.

The echo option is a boolean value (the default is true ) that indicates whether the command line should be echoed when a user invokes the translator.

The other arguments to define-presentation-to-command-translator are the same as for define-presentation-translator . Note that the tester for command translators is always assumed to be definitive, so there is no :tester-definitive option. The default for pointer-documentation is the string command-name with dash characters replaced by spaces, and each word capitalized (as in add-command-to-command-table ).

The body of the translator must return a list of the arguments to the command named by command-name . body is run in the context of the application. The returned value of the body, appended to the command name, are eventually passed to execute-frame-command . body may have zero or more declarations as its first forms.

None of define-presentation-to-command-translator 's arguments is evaluated.

define-presentation-action

name (from-type to-type command-table &key gesture tester documentation pointer-documentation menu priority) arglist &body body

[Macro]

define-presentation-action is similar to 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.

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.

The other arguments to define-presentation-action are the same as for define-presentation-translator . Note that the tester for presentation actions is always assumed to be definitive.

None of define-presentation-action 's arguments is evaluated.

define-drag-and-drop-translator

name (from-type to-type destination-type command-table &key gesture tester documentation pointer-documentation menu priority feedback highlighting) arglist &body body

[Macro]

Defines a ``drag and drop'' (or ``direct manipulation'') translator named name that translates from objects of type from-type to objects of type to-type when a ``from presentation'' is ``picked up'', ``dragged'' over, and ``dropped'' on to a ``to presentation'' having type destination-type . from-type , to-type , and destination-type are presentation type specifiers, but must not include any presentation type options. from-type , to-type and destination-type may be presentation type abbreviations.

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 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 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.

While the pointer is being dragged, the function specified by 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 x and y positions of the pointer, the current x and y positions of the pointer, and a feedback state (either :highlight to draw feedback, or :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. feedback defaults to frame-drag-and-drop-feedback .

When the ``from presentation'' is dragged over any other presentation that has a direct manipulation translator, the function specified by 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 :highlight or :unhighlight ). highlighting defaults to frame-drag-and-drop-highlighting .

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.

The other arguments to define-drag-and-drop-translator are the same as for define-presentation-translator .

23.7.2 Presentation Translator Functions

Implementation note: Because 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.

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 find-applicable-translators .

test-presentation-translator

translator presentation context-type frame window x y &key event modifier-state for-menu

[Function]

Returns true if the translator translator applies to the presentation presentation in input context type context-type , otherwise returns false . (There is no from-type argument because it is derived from presentation .) x and y are the x and y positions of the pointer within the window stream window .

event and modifier-state are a pointer button event and modifier state (see event-modifier-key-state ), and are compared against the translator's gesture. event defaults to nil , and modifier-state defaults to 0, meaning that no modifier keys are held down. Only one of event or modifier-state may be supplied; it is unspecified what will happen if both are supplied.

If for-menu is true , the comparison against event and modifier-state is not done.

presentation , context-type , frame , window , x , y , and event are passed along to the translator's tester if and when the tester is called.

test-presentation-translator is responsible for matching type parameters and calling the translator's tester. Under some circumstances, test-presentation-translator may also call the body of the translator to ensure that its value matches to-type .

find-applicable-translators

presentation input-context frame window x y &key event modifier-state for-menu fastp

[Function]

Returns a list that describes the translators that definitely apply to the presentation presentation in the input context input-context . Each element in the returned list is of the form
(translator the-presentation context-type . rest)
where translator is a presentation translator, the-presentation is the presentation that the translator applies to (and can be different from presentation due to nesting of presentations), context-type is the context type in which the translator applies, and rest is other unspecified data reserved for internal use by CLIM. translator , the-presentation , and context-type can be passed to such functions as call-presentation-translator and document-presentation-translator .

Since input contexts can be nested, find-applicable-translators must iterate over all the contexts in input-context . window , x , and y are as for test-presentation-translator . event and modifier-state (which default to nil and the current modifier state for window , respectively) are used to further restrict the set of applicable translators. (Only one of event or modifier-state may be supplied; it is unspecified what will happen if both are supplied.)

Presentations can also be nested. The ordering of the translators returned by 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.

When for-menu is non-nil , this matches the value of for-menu against the presentation's menu specification, and returns only those translators that match. event and modifier-state are disregarded in this case. for-menu defaults to nil .

When the boolean fastp is true , find-applicable-translators will simply return true if there are any translators. fastp defaults to false .

When fastp is false , the list of translators returned by 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.

The rules used for ordering the translators returned by find-applicable-translators are as follows (in order):

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.

Translators with a more specific ``from type'' precede translators with a less specific ``from type''.

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.

Translators from the current command table precede translators inherited from superior command tables.

If there are no applicable translators, presentation-matches-context-type will return false .

call-presentation-translator

translator presentation context-type frame event window x y

[Function]

Calls the function that implements the body of the translator translator on the presentation presentation 's object, and passes presentation , context-type , frame , event , window , x , and y to the body of the translator as well.

The returned values are the same as the values returned by the body of the translator, namely, the translated object and the translated type.

document-presentation-translator

translator presentation context-type frame event window x y &key (stream *standard-output* ) documentation-type

[Function]

Computes the documentation string for the translator translator and outputs it to the stream stream . presentation , context-type , frame , event , window , x , and y are as for test-presentation-translator .

documentation-type must be either :normal or :pointer . If it is :normal , the usual translator documentation function is called. If it is :pointer , the translator's pointer documentation is called.

call-presentation-menu

presentation input-context frame window x y &key for-menu label

[Function]

Finds all the applicable translators for the presentation presentation in the input context 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 call-presentation-menu and the matching input context that was established by with-input-context is terminated.

window , x , y , and event are as for find-applicable-translators . for-menu , which defaults to t , is used to decide which of the applicable translators will go into the menu; only those translators whose :menu option matches menu will be included.

label is either a string to use as a label for the menu, or is nil (the default), meaning the menu will not be labelled.

23.7.3 Finding Applicable Presentations

event and modifier-state are a pointer button event and modifier state (see event-modifier-key-state ). event defaults to nil , and modifier-state defaults to the current modifier state for window . Only one of event or modifier-state may be supplied; it is unspecified what will happen if both are supplied.

frame defaults to the current frame, *application-frame* .

The default method for frame-find-innermost-applicable-presentation will call this function.

throw-highlighted-presentation

presentation input-context button-press-event

[Function]

Given a presentation presentation , input context input-context , and a button press event (which contains the window, pointer, x and 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 with-input-context will be terminated.

Note that it is possible that more than one translator having the same gesture may be applicable to 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.

highlight-applicable-presentation