CLIM provides several helper macros to control the output recording facility.
with-output-recording-options [Macro]
Arguments: (stream &key record draw) &body body
Summary: Enables or disables output recording and/or drawing on the output recording stream designated by stream , within the extent of body .
The stream argument is not evaluated, and must be a symbol that is bound to an output recording stream. If stream is t , *standard-output* is used. body may have zero or more declarations as its first forms.
with-output-recording-options expands into a call to invoke-with-output-recording-options , supplying a function that executes body as the continuation argument to invoke-with-output-recording-options .
invoke-with-output-recording-options [Generic Function]
Arguments: stream continuation record draw
Summary: Enables or disables output recording and/or drawing on the output recording stream stream , and calls the function continuation with the new output recording options in effect. continuation is a function of one argument, the stream; it has dynamic extent.
If draw is nil , output to the stream is not drawn on the viewport, but recording proceeds according to record ; if draw is t , the output is drawn. If record is nil , output recording is disabled, but output otherwise proceeds according to draw ; if draw is t , output recording is enabled.
All output recording streams must implement a method for invoke-with-output-recording-options .
with-new-output-record [Macro]
Arguments: (stream &optional record-type record &rest init-args) &body body
Summary: Creates a new output record of type record-type (which defaults to standard-sequence-output-record ), captures the output of body into the new output record, and inserts the new record into the current "open" output record associated with the output recording stream stream . While body is being evaluated, the current output record for stream will be bound to the new output record.
If record is supplied, it is the name of a variable that will be lexically bound to the new output record inside of body. init-args are CLOS initialization arguments that are passed to make-instance when the new output record is created.
with-new-output-record returns the output record it creates.
The stream argument is not evaluated, and must be a symbol that is bound to an output recording stream. If stream is t , *standard-output* is used. body may have zero or more declarations as its first forms.
with-new-output-record expands into a call to invoke-with-new-output-record , supplying a function that executes body as the continuation argument to invoke-with-new-output-record .
with-output-to-output-record [Macro]
Arguments: (stream &optional record-type record &rest init-args) &body body
Summary: Like with-new-output-record , except that the new output record is not inserted into the output record hierarchy, and the text cursor position of stream is initially bound to (0, 0).
record-type is the type of output record to create, which defaults to standard-sequence-output-record . init-args are CLOS initialization arguments that are passed to make-instance when the new output record is created. record , if supplied, is a variable that will be bound to the new output record while body is evaluated.
with-output-to-output-record returns the output record it creates.
The stream argument is not evaluated, and must be a symbol that is bound to an output recording stream. If stream is t , *standard-output* is used. Unlike facilities such as with-output-to-string , stream must be an actual stream, but no output will be done to it. body may have zero or more declarations as its first forms.
with-output-to-output-record expands into a call to invoke-with-output-to-output-record , supplying a function that executes body as the continuation argument to invoke-with-output-to-output-record .
invoke-with-new-output-record [Generic Function]
Arguments: stream continuation record-type &rest init-args &key
Summary: Creates a new output record of type record-type . The function continuation is then called, and any output it does to the output recording stream stream is captured in the new output record. The new record is then inserted into the current "open" output record associated with stream (or the top-level output record if there is no currently "open" one). While continuation is being executed, the current output record for stream will be bound to the new output record.
continuation is a function of two arguments, the stream and the output record; it has dynamic extent. init-args are CLOS initialization arguments that are passed to make-instance when the new output record is created.
invoke-with-new-output-record returns the output record it creates.
All output recording streams must implement a method for invoke-with-new-output-record .
invoke-with-output-to-output-record [Generic Function]
Arguments: stream continuation record-type &rest init-args &key
Summary: Like invoke-with-new-output-record except that the new output record is not inserted into the output record hierarchy, and the text cursor position of stream is initially bound to (0, 0). That is, when invoke-with-output-to-output-record is used, no drawing on the stream occurs and nothing is put into the stream's normal output history. The function continuation is called, and any output it does to stream is captured in the output record.
continuation is a function of two arguments, the stream and the output record; it has dynamic extent. record-type is the type of output record to create. init-args are CLOS initialization arguments that are passed to make-instance when the new output record is created.
invoke-with-output-to-output-record returns the output record it creates.
All output recording streams must implement a method for invoke-with-output-to-output-record .
make-design-from-output-record [Generic Function]
Summary: Makes a design that replays the output record record when drawn via draw-design . If record is changed after the design is made, the consequences are unspecified. Applying a transformation to the design and calling draw-design on the new design is equivalent to establishing the same transformation before creating the output record.
The current version of CLIM supports this only for those output records that correspond to the geometric object classes (for example, the output records created by draw-line* and draw-ellipse* ).