Presentations for program output so that the objects presented will be acceptable to input functions. Suppose, for example, you present an object, such as 5, as a TV channel. When a command that takes a TV channel as an argument is issued or when a presentation translation function is "looking for" such a thing, the system will make that object sensitive. Also, when a command that is looking for a different kind of object (such as a highway number), the object 5 is not sensitive, because that object represents a TV channel, not a highway number.
A presentation includes not only the displayed representation itself, but also the object presented and its presentation type. When a presentation is output to a CLIM window, the object and presentation type are "remembered"—that is, the object and type of the display at a particular set of window coordinates are recorded in the window's output history. Because this information remains available, previously presented objects are themselves available for input to functions for accepting objects.
An application can use the following operators to produce output that will be associated with a given Lisp object and declared to be of a specified presentation type. This output is saved in the window's output history as a presentation. Specifically, the presentation remembers the output that was performed (by saving the associated output record), the Lisp object associated with the output, and the presentation type specified at output time. The object can be any Lisp object.
CLOS provides these top-level facilities for presenting output. with-output-as-presentation is the most general operator, and present and present-to-string support common idioms.
with-output-as-presentation Macro
with-output-as-presentation (stream object type &key modifier single-box allow-sensitive-inferiors record-type) &body body
Summary: The output of body to the extended output recording stream 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 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 is a presentation type specifier and may be an abbreviation.
modifier, which defaults to nil, is a function 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 nil, nested calls to present or with-output-as-presentation inside this one will not generate presentations. The default is t.
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:
(with-output-as-presentation (stream #p"foo" 'pathname)
(princ "FOO" stream))
present object &optional type &key stream view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type
Summary: The object of presentation type type is presented to the extended output stream stream (which defaults to *standard-output*), using the type's present method for the supplied view view. type is a presentation type specifier, and can be an abbreviation. It defaults to (presentation-type-of object). The other arguments and overall behavior of present are as for stream-present.
The returned value of present is the presentation object that contains the output corresponding to the object.
present expands any presentation type abbreviations (type and for-context-type), and then calls stream-present on stream, object, type, and the remaining keyword arguments.
stream-present Generic Function
stream-present stream object type &key view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type
Summary: 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 implement a method for stream-present. The default method (on standard-extended-output-stream) is as follows.
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 t. If it is nil, no presentation is produced.
present-to-string object &optional type &key view acceptably for-context-type string index
Summary: 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.
The following functions can be used to examine or modify presentations:
Summary: The protocol class that corresponds to a presentation and is a subclass of output-record. If you want to create a new class that behaves like a presentation, it should be a subclass of presentation. Subclasses of presentation obey the presentation protocol.
presentationp object
Summary: Returns t if and only if object is of type presentation.
presentation-object Generic Function
presentation-object presentation
Summary: Returns the object represented by the presentation presentation.
(setf presentation-object) Generic Function
(setf presentation-object) object presentation
Summary: Changes the object associated with the presentation presentation to object.
presentation-type Generic Function
presentation-type presentation
Summary: Returns the presentation type of the presentation presentation.
(setf presentation-type) Generic Function
(setf presentation-type) type presentation
Summary: Changes the type associated with the presentation presentation to type.
presentation-single-box Generic Function
presentation-single-box presentation
Summary: 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.
(setf presentation-single-box) Generic Function
(setf presentation-single-box) single-box presentation
Summary: Changes the "single box" attribute of the presentation presentation to single-box.
presentation-modifier Generic Function
presentation-modifier presentation
Summary: 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.
Summary: The output record class that represents presentations. present normally creates output records of this class. Members of this class are mutable.
:object
:type
:view
:single-box
:modifier Initargs
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.
CLIM 2.0 User Guide - 01 Dec 2021 19:38:57