7.2.1 Presentation Methods in CLIM

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.

(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

Arguments: type

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

Arguments: object type

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

Arguments: function type

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

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

Arguments: type

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
.