6.3 Using CLIM Presentation Types for Output

6.3.1 CLOS Operators

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]

(stream object type&key modifier single-box allow-sensitive-inferiors record-type)&body body
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 [Function]
object&optional type&key stream view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type
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 object type&key view modifier acceptably for-context-type single-box allow-sensitive-inferiors sensitive record-type
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 [Function]
object&optional type&key view acceptably for-context-type string index
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.

CLIM 2.0 User's Guide - OCT 1998

Generated with Harlequin WebMaker