Use define-presentation-method to define presentation methods.
define-presentation-method[Macro]
Arguments: name qualifiers* specialized-lambda-list
&body
body
Summary: 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 vary depending on what name is. qualifiers* is zero or more of the usual CLOS method qualifier symbols. define-presentation-method supports standard method combination (the :before , :after , and :around method qualifiers).
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 those for 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.
Presentation methods inherit and combine in the same way as ordinary CLOS methods. However, they do not resemble ordinary CLOS methods with respect to the type argument. The parameter specializer for type is handled in a special way, and presentation method inheritance arranges the type parameters and options seen by each method.
For example, consider three types int , rrat , and num defined as follows:
(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
((int 1 5))
in each of the methods.
Following are the names of the various presentation methods defined by define-presentation-method , along with the lambda-list for each method. For all of the presentation methods, the type will always be specialized. Where appropriate, view may be specialized as well. The other arguments are not usually specialized.
accept
Arguments: type stream view
&key
default default-type
Summary: This presentation method is responsible for "parsing" the representation of type for a particular view view on the stream stream.The accept method returns 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.
Note that accept presentation methods can call the function accept recursively. In this case, the programmer should be careful to specify nil for :prompt and :display-default unless recursive prompting is really desired.
present
Arguments: object type stream view
&key
acceptably for-context-type
Summary: This presentation method is responsible for displaying the representation of object having type type for a particular view view; see the function accept .
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.
describe-presentation-type
Arguments: type stream plural-count
Summary: This presentation method is responsible for textually describing the type type. stream is a stream, and will not be nil as it can be for the describe-presentation-type function.
presentation-type-specifier-p
Summary: This presentation method is responsible for checking the validity of the parameters and options for the presentation type type . The default method returns t .
presentation-typep
Summary: This presentation method is called when the presentation-typep function requires type-specific knowledge. If the type name in the presentation type type is or names a CLOS class, the method is called only if object is a member of the class and type contains parameters. 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.
For example, the type method will not get called in
(presentation-typep 1.0 `(integer 10))
because 1.0 is not an integer. The method will get called by
(presentation-typep 10 `(integer 0 5))
.
presentation-subtypep
Arguments: type putative-supertype
Summary: This presentation method is called when the presentation-subtypep function requires type-specific knowledge.
presentation-subtypep walks the type lattice (using map-over-presentation-supertypes ) to determine whether or not the presentation type type is a subtype of the presentation 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.
map-over-presentation-type-supertypes
Summary: This method is called in order to apply function to the superclasses of the presentation type type .
accept-present-default
Arguments: type stream view default default-supplied-p present-p query-identifier
Summary: This method specializes the kind of default that is to be presented to the user. It is called when accept turns into present inside accepting-values . The default method calls present or describe-presentation-type , depending on whether default-supplied-p is t or nil , respectively.
The boolean default-supplied-p will be t only in the case when the :default option was explicitly supplied in the call to accept that invoked accept-present-default .
present-p and query-identifier are arguments that are called internally by the accept-values mechanism that this method needs to handle. The form of present-p as it is handed down (internally) from
accepting-values
is a list of the presentation type of the accepting-values query (
accept-values-choice
) and the query object itself, e.g.,
(list 'accept-values-choice <
AV-query-object
>)
. The value of query-identifier is an internal
accept-values
query identifier object.
presentation-type-history
Summary: This method returns a history object for the presentation type type , or nil if there is none.
presentation-refined-position-test
Arguments: (record presentation-type x y)
Summary: This method is supplied when the user wants a more precise test of whether the supplied coordinate arguments ( x and y ) are "contained" by the record argument. Without this test, whether or not a position is within a record is determined by simply by seeing if the position is inside the bounding-rectangle of that record.
highlight-presentation
Arguments: type record stream state
Summary: 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 .
See 7.4, Advanced Topics for more in-depth material relating to defining presentation methods.