The type associated with a presentation is specified with a presentation type specifier, an object matching one of the following three patterns:
| name |
| (name parameters...) |
| ((name parameters...) options...) |
[presentation type specifier, Concept← 23.3.4 Presentation Type Functions, presentation-type-direct-supertypes]
[presentation type specifier, Concept← 23.3.4 Presentation Type Functions, map-over-presentation-type-supertypes]
[presentation type specifier, Concept← 23.3.4 Presentation Type Functions, presentation-subtypep]
[presentation type specifier, Concept← 23.3.4 Presentation Type Functions, presentation-subtypep]
[presentation type specifier, Concept← 23.3.4 Presentation Type Functions, presentation-typep]
[presentation type specifier, Concept← 23.3.4 Presentation Type Functions, presentation-type-specifier-p]
[presentation type specifier, Concept← 23.3.4 Presentation Type Functions, describe-presentation-type]
[presentation type specifier, Concept← 23.3.2 Presentation Type Abbreviations, expand-presentation-type-abbreviation-1]
Note that name can be either a symbol that names a presentation type or a CLOS class object (but not a built-in-class object), in order to support anonymous CLOS classes. [annotate]
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. [annotate]
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. [annotate]
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. [annotate]
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. [annotate]
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. [annotate]
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. [annotate]
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. [annotate]
| define-presentation-type | name parameters &key options inherit-from description history parameters-are-types | [Macro] |
Defines a presentation type whose name is the symbol or class name and whose parameters are specified by the lambda-list parameters. These parameters are visible within inherit-from and within the methods created with define-presentation-method. For example, the parameters are used by presentation-typep and presentation-subtypep methods to refine their tests for type inclusion. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] Minor issue: What is a presentation type history? Should they be exposed? --- SWM [annotate] If the boolean parameters-are-types is true, this means that the parameters to the presentation type are themselves presentation types. If they are not presentation types, parameters-are-types should be supplied as false. Types such as and, or, and sequence will specify this as true. [annotate] 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. [annotate] 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. [annotate] 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. [annotate] None of the arguments, except inherit-from, is evaluated. [annotate] |
name, parameters, and options are as in define-presentation-type. This defines a presentation type that is an abbreviation for the presentation type equivalent-type. Presentation type abbreviations can only be used in places where this specification explicitly permits them. In such places, equivalent-type and abbreviation are exactly equivalent and can be used interchangeably. [annotate] name must be a symbol and must not be the name of a CLOS class. [annotate] 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. [annotate] Note that you cannot define any presentation methods on a presentation type abbreviation. If you need methods, use define-presentation-type instead. [annotate] 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 [annotate]
(define-presentation-type-abbreviation octal-integer (&optional low high)
`((integer ,low ,high) :base 8 :description "octal integer"))
None of the arguments, except equivalent-type, is evaluated. [annotate] |
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. [annotate] env is a macro-expansion environment, as for macroexpand. [annotate] |
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. [annotate] |
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 type argument. The parameter specializer for 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 int, rrat, and num defined as follows: [annotate]
Minor issue: How are massaged arguments passed along? Right now, we pass along those parameters of the same name, and no others. --- SWM [annotate]
(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))
If the user were to evaluate the form (presentation-typep X '(int 1 5)), then the type parameters will be (1 5) in the presentation-typep method for int, (5 1) in the method for rrat, and nil in the method for num. The value for type will be or ((int 1 5)) in each of the methods. [annotate]
| 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. [annotate] 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. [annotate] Note: It is open how type-key, type-class, parameters, options and type are to be matched. I see two options: 1. Use the string= like matching. That is don't take the package into account. 2. Use eq but then export the relevant symbols from the clim package. Because otherwise the user who wants to define a presentation generic function is forced to tamper with clim-internals. In McCLIM of today option 2 is used but the exporting. [edit]-- Gilbert Baumann 2004-06-12 17:11ZFor example, the accept presentation generic function might be defined as follows: [annotate] (define-presentation-generic-function present-method present (type-key parameters options object type stream view &key acceptably for-context-type)) None of the arguments is evaluated. [annotate] |
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. [annotate] body defines the body of the method. body may have zero or more declarations as its first forms. [annotate] 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. [annotate] 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. [annotate] |
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. [annotate] |
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. [annotate] funcall-presentation-generic-function is analogous to funcall. [annotate] The presentation-function-name argument is not evaluated. [annotate] For example, to call the present presentation generic function, one might use the following: [annotate] (funcall-presentation-generic-function present object presentation-type stream view) |
Like funcall-presentation-generic-function, except that apply-presentation-generic-function is analogous to apply. [annotate] The presentation-function-name argument is not evaluated. [annotate] 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. [annotate] 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. [annotate] |
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. [annotate] 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. [annotate] Implementation note: the actual argument list to the present method is 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. [annotate] [← 27.6.1 Command Presentation Types, command] [← 25 Menu Facilities, menu-choose-from-drawer] [← 25 Menu Facilities, frame-manager-menu-choose] [← 24.4 Reading and Writing of Tokens, write-token] [← 24.4 Reading and Writing of Tokens, presentation-replace-input] [← 23.8.7 "Meta" Presentation Types, and] [← 23.8.5 "One-of" and "Some-of" Presentation Types, completion] [← 23.6 Views, stream-default-view] [← 23.6 Views] [← 23.4 Typed Output, present-to-string] [← 23.4 Typed Output, stream-present] [← 23.4 Typed Output, with-output-as-presentation] [← 23.3.3 Presentation Methods, accept-present-default] [← 23.3.3 Presentation Methods, funcall-presentation-generic-function] [← 23.3.3 Presentation Methods, define-presentation-method] [← 23.3.1 Defining Presentation Types, define-presentation-type] [← 23.2 Presentations, standard-presentation] |
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. [annotate] Implementation note: the actual argument list to the describe-presentation-type method is [← 23.5 Context-dependent (Typed) Input, prompt-for-accept-1] [← 23.3.4 Presentation Type Functions, default-describe-presentation-type] [← 23.3.3 Presentation Methods, accept-present-default] [← 23.3.3 Presentation Methods, define-presentation-method] [← 23.3.1 Defining Presentation Types, define-presentation-type] |
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. [annotate] Implementation note: the actual argument list to the presentation-type-specifier-p method is |
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. [annotate] Implementation note: the actual argument list to the presentation-typep method is |
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. [annotate] 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. [annotate] Since presentation-subtypep takes two type arguments, the parameters are not lexically available as variables in the body of a presentation method. [annotate] Implementation note: the actual argument list to the presentation-subtypep method is |
This method is called in order to apply function to the superclasses of the presentation type type. [annotate] Implementation note: the actual argument list to the map-over-presentation-type-supertypes method is |
| 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. [annotate] 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. [annotate] Implementation note: the actual argument list to the accept-present-default method is |
This method is responsible for returning a history object for the presentation type type. [annotate] Note: while discussing this on IRC, Andy Hefner and I came to the conclusion that the "history object" needs only be used in ACCEPT and similar methods and is therefore left not very specified. Is that correct? [edit]-- Andreas Fuchs 2003-06-09 18:49Z Implementation note: the actual argument list to the presentation-type-history method is |
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. [annotate] Implementation note: the actual argument list to the presentation-default-preprocessor method is |
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. [annotate] Implementation note: the actual argument list to the presentation-refined-position-test method is |
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. [annotate] Implementation note: the actual argument list to the highlight-presentation method is |
Describes the presentation type specifier type on the stream stream, which defaults to *standard-output*. If stream is nil, a string containing the description is returned. plural-count is either nil (meaning that the description should be the singular form of the name), 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 1. [annotate] type can be a presentation type abbreviation. [annotate] [← 23.5 Context-dependent (Typed) Input, prompt-for-accept-1] [← 23.3.4 Presentation Type Functions, default-describe-presentation-type] [← 23.3.3 Presentation Methods, accept-present-default] [← 23.3.3 Presentation Methods, define-presentation-method] [← 23.3.1 Defining Presentation Types, define-presentation-type] |
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. [annotate] |
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. [annotate] |
| 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. [annotate] The name-var, parameters-var, and options-var arguments are not evaluated. body may have zero or more declarations as its first forms. [annotate] |
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: [annotate]
(defun presentation-type-name (type)
(with-presentation-type-decoded (name) type
name))
|
Variables with the same name as each parameter in the definition of the presentation type are bound to the parameter 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. [annotate] 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. [annotate] |
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. [annotate] 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. [annotate] |
Returns true if object is a valid presentation type specifier, otherwise returns false. [annotate] Note: What should be done if `object' is an unknown presentation type specifier? An error? [edit]-- Troels "Athas" Henriksen 2006-12-12 19:52Z |
Returns true if object is of the presentation type specified by the presentation type specifier type, otherwise returns false. [annotate] type may not be a presentation type abbreviation. [annotate] This is analogous to the Common Lisp typep function. [annotate] |
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. [annotate] If presentation-type-of cannot determine the presentation type of the object, it may return either expression or t. [annotate] This is analogous to the Common Lisp typep function. [annotate] Note: Exactly how is this analogous? Was `type-of' intended? [edit]-- Troels "Athas" Henriksen 2006-10-19 20:09Z Note: I think that in the old days `one-argument TYPEP' was what we now call TYPE-OF, so this is probably a braino from some old-timer. (I should say that this is hearsay; I wasn't born when CL was invented ;-) [edit]-- Christophe Rhodes 2006-11-16 17:06Z |
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. [annotate] type may not be a presentation type abbreviation. [annotate] This is analogous to the Common Lisp subtypep function. [annotate] |
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. [annotate] Note: What is meant to happen when the presentation type specifier is NIL? The existence of this type breaks the assumption that we have hierarchical inheritance, and indeed a fixed supertype list... [edit]-- Christophe Rhodes 2007-01-09 10:58Z |
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. [annotate] |
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. [annotate] |
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. [annotate] |
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. [annotate] |
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. [annotate] |