The purpose of output recording is to capture the output done by an application onto a stream. The objects used to capture output are called output records and output record elements. The following classes and predicates correspond to the objects used in output recording.
Summary: The protocol class used to indicate that an object is an output record. A subclass of bounding-rectangle, output records obey the bounding rectangle protocol. If you want to create a new class that behaves like an output record, it should be a subclass of output-record. Subclasses of output-record must obey the output-record protocol.
All output records are mutable.
output-record-p object
Summary: Returns t if object is an output record; otherwise, it returns nil.
displayed-output-record Protocol Class
Summary: The protocol class that is used to indicate that an object is a displayed output record, that is, an object that represents a visible piece of output on some output stream. This is a subclass of bounding-rectangle. If you want to create a new class that behaves like a displayed output record, it should be a subclass of displayed-output-record. Subclasses of displayed-output-record must obey the displayed output record protocol.
All displayed output records are mutable.
displayed-output-record-p Function
displayed-output-record-p object
Summary: Returns t if object is a displayed output record; otherwise, it returns nil.
:x-position
:y-position
:parent Initargs
Summary: All subclasses of either output-record or displayed-output-record must handle these three initargs, which are used to specify, respectively, the x and y position of the output record, and the parent of the output record.
Summary: All subclasses of output-record must handle the :size initarg, which specifies how much room should be left for child output records (if, for example, the children are stored in a vector). :size may be ignored, provided that the resulting output record is able to store the specified number of child output records.
All subclasses of output-record and displayed-output-record must inherit or implement methods for the following generic functions. For details of setf*, see C.4 Multiple-Value Setf.
output-record-position Generic Function
output-record-position record
Summary: Returns the x and y position of the output record record as two rational numbers. The position of an output record is the position of the upper-left corner of its bounding rectangle. The position is relative to the stream, where (0, 0) is (initially) the upper-left corner of the stream.
(setf* output-record-position) Generic Function
(setf* output-record-position) x y record
Summary: Changes the x and y position of the output record record to be x and y (which are rational numbers), and updates the bounding rectangle to reflect the new position (and saved cursor positions, if the output record stores it). If record has any children, all of the children (and their descendants as well) will be moved by the same amount as record was moved. The bounding rectangles of all of record's ancestors will also be updated to be large enough to contain record. This does not replay the output record, but the next time the output record is replayed it will appear at the new position.
output-record-start-cursor-position Generic Function
output-record-start-cursor-position record
Summary: Returns the x and y starting cursor position of the output record record as two integer values. The positions are relative to the stream, where (0, 0) is (initially) the upper-left corner of the stream.
Text output records and updating output records maintain the cursor position. Graphical output records and other output records that do not require or affect the cursor position will return nil as both of the values.
(setf* output-record-start-cursor-position) Generic Function
(setf* output-record-start-cursor-position) x y record
Summary: Changes the x and y starting cursor position of the output record record to be x and y (which are integers). This does not affect the bounding rectangle of record, nor does it replay the output record. For those output records that do not require or affect the cursor position, the method for this function does nothing.
output-record-end-cursor-position Generic Function
output-record-end-cursor-position record
Summary: Returns the x and y ending cursor position of the output record record as two integer values. The positions are relative to the stream, where (0, 0) is initially the upper-left corner. Graphical output records do not track the cursor position, so only text output record and some others will return meaningful values for this.
Text output records and updating output records maintain the cursor position. Graphical output records and other output records that do not require or affect the cursor position will return nil as both of the values.
(setf* output-record-end-cursor-position) Generic Function
(setf* output-record-end-cursor-position) x y record
Summary: Changes the x and y ending cursor position of the output record record to be x and y (which are integers). This does not affect the bounding rectangle of record, nor does it replay the output record. For those output records that do not require or affect the cursor position, the method for this function does nothing.
output-record-parent Generic Function
output-record-parent record
Summary: Returns the output record that is the parent of the output record record, or nil if the record has no parent.
replay record stream &optional region
Summary: This function binds stream-recording-p of stream to nil, and then calls replay-output-record on the arguments record, stream, and region. If stream-drawing-p of stream is nil, replay does nothing. replay is typically called during scrolling, by repaint handlers, and so on.
region defaults to nil.
replay-output-record Generic Function
replay-output-record record stream &optional region x-offset y-offset
Summary: Displays the output captured by the output record record on the output recording stream stream, exactly as it was originally captured (subject to subsequent modifications). The current user transformation, line style, text style, ink, and clipping region of stream are all ignored during the replay operation. Instead, these are gotten from the output record.
If record is not a displayed output record, then replaying it involves replaying all of its children. If record is a displayed output record, then replaying it involves redoing the graphics operation captured in the record.
region is a region that limits what records are displayed. Only those records that overlap region are replayed. The default for region is +everywhere+.
stream must be the same stream on which the output records were originally recorded.
erase-output-record Generic Function
erase-output-record record stream
Summary: Erases the output record record from the output recording stream stream, removes record from stream's output history, and ensures that all other output records that were covered by record are visible. In effect, this draws background ink over the record, and then redraws all the records that overlap record.
output-record-refined-sensitivity-test Generic Function
output-record-refined-sensitivity-test record x y
Summary: This is used to definitively answer hit detection queries, that is, determining that the point (x, y) is contained within the output record record. Once the position (x, y) has been determined to lie within output-record-hit-detection-rectangle*, output-record-refined-sensitivity-test is invoked. Output record subclasses can provide a method that defines a hit more precisely; for example, output records for elliptical rings will implement a method that detects whether the pointing device is on the elliptical ring.
highlight-output-record Generic Function
highlight-output-record record stream state
Summary: This method is called in order to draw a highlighting box around the output record record on the output recording stream stream. state will be either :highlight (meaning to draw the highlighting) or :unhighlight (meaning to erase the highlighting). The default method (on CLIM's standard output record class) simply draws a rectangle that corresponds to the bounding rectangle of record.
All classes that are subclasses of output-record must implement methods for the following generic functions.
output-record-children Generic Function
output-record-children record
Summary: Returns a fresh list of all the children of the output record record.
add-output-record Generic Function
add-output-record child record
Summary: Adds the new output record child to the output record record. The bounding rectangle for record and all its ancestors is updated accordingly.
The methods for the add-output-record will typically specialize only the record argument.
delete-output-record Generic Function
delete-output-record child record &optional (errorp t)
Summary: Removes the output record child from the output record record. The bounding rectangle for record (and all its ancestors) is updated to account for the child having been removed.
If errorp is t (the default) and child is not contained within record, then an error is signaled.
The methods for the delete-output-record will typically specialize only the record argument.
clear-output-record Generic Function
clear-output-record record
Summary: Removes all of the children from the output record record, and resets the bounding rectangle of record to its initial state.
output-record-count Generic Function
output-record-count record
Summary: Returns the number of children contained within the output record record.
map-over-output-records-containing-position Generic Function
map-over-output-records-containing-position function record x y &optional x-offset y-offset
Summary: Maps over all of the children of the output record record that contain the point at (x, y), calling function on each one. function is a function of one argument, the record containing the point; it has dynamic extent.
If there are multiple records that contain the point and that overlap each other, map-over-output-records-containing-position hits the most recently inserted record first and the least recently inserted record last.
map-over-output-records-overlapping-region Generic Function
map-over-output-records-overlapping-region function record region &optional x-offset y-offset
Summary: Maps over all of the children of the output record record that overlap the region region, calling function on each one. function is a function of one argument, the record overlapping the region; it has dynamic extent.
If there are multiple records that overlap the region and that overlap each other, map-over-output-records-overlapping-region hits the least recently inserted record first and the most recently inserted record last.
This section discusses several types of output records, including two standard classes of output records and the displayed output record protocol.
standard-sequence-output-record Class
Summary: The standard class provided by CLIM to store a relatively short sequence of output records; a subclass of output-record. The retrieval complexity of this class is 0(n). Most of the formatted output facilities (such as formatting-table) create output records that are a subclass of standard-sequence-output-record.
standard-tree-output-record Class
Summary: The standard class provided by CLIM to store longer sequences of output records. Typically, the child records of a tree output record will be sorted in some way, such as an ordering on the x and y coordinates of the children. The retrieval complexity of this class is 0(log n).
Graphics displayed output records are used to record the output produced by the graphics functions, such as draw-line*. Each graphics displayed output record describes the output produced by a call to one of the graphics functions.
CLIM graphics displayed output records capture the following information, so that the original output can be redrawn exactly at replay time:
graphics-displayed-output-record Protocol Class
Summary: The protocol class that corresponds to output records for the graphics functions, such as draw-line*. This is a subclass of displayed-output-record. If you want to create a new class that behaves like a graphics displayed output record, it should be a subclass of graphics-displayed-output-record. Subclasses of graphics-displayed-output-record must obey the graphics displayed output record protocol.
graphics-displayed-output-record-p Function
graphics-displayed-output-record-p object
Summary: Returns t if object is a graphics displayed output record; otherwise, it returns nil.
Text displayed output records are used to record the textual output produced by such functions as stream-write-char and stream-write-string. Each text displayed output record corresponds to no more than one line of textual output (that is, line breaks caused by terpri and fresh-line create a new text output record, as do certain other stream operations).
Text displayed output records store the following information:
text-displayed-output-record Protocol Class
Summary: The protocol class that corresponds to text displayed output records. This is a subclass of displayed-output-record. If you want to create a new class that behaves like a text displayed output record, it should be a subclass of text-displayed-output-record. Subclasses of text-displayed-output-record must obey the text displayed output record protocol.
text-displayed-output-record-p Function
text-displayed-output-record-p object
Summary: Returns t if object is a text displayed output record; otherwise, it returns nil.
The following three generic functions comprise the text displayed output record protocol.
add-character-output-to-text-record Generic Function
add-character-output-to-text-record text-record character text-style width height baseline
Summary: Adds the character character to the text displayed output record text-record in the text style text-style. width and height are the width and height of the character in device units, and are used to compute the bounding rectangle for the text record. baseline is the new baseline for characters in the output record.
add-string-output-to-text-record Generic Function
add-string-output-to-text-record text-record string start end text-style width height baseline
Summary: Adds the string string to the text displayed output record text-record in the text style text-style. start and end are integers that specify the substring within string to add to the text output record. width and height are the width and height of the character in device units, and are used to compute the bounding rectangle for the text record. baseline is the new baseline for characters in the output record.
text-displayed-output-record-string Generic Function
text-displayed-output-record-string text-record
Summary: Returns the string contained by the text displayed output record text-record. This function returns objects that reveal CLIM's internal state; do not modify those objects.
Top-level output records are similar to ordinary output records, except that they maintain additional state, such as the information required to display scroll bars.
stream-output-history-mixin Class
Summary: This class is mixed into some other output record class to produce a new class that is suitable for use as a a top-level output history.
When the bounding rectangle of a member of this class is updated, any window decorations (such as scroll bars) associated with the stream with which the output record history is associated are updated, too.
standard-tree-output-history Class
Summary: The standard class provided by CLIM to use as the top-level output history. This will typically be a subclass of both standard-tree-output-record and stream-output-history-mixin.
CLIM defines an extension to the stream protocol that supports output recording. The stream has an associated output history record and provides controls to enable and disable output recording.
output-recording-stream Protocol Class
Summary: The protocol class that indicates that a stream is an output recording stream. If you want to create a new class that behaves like an output recording stream, it should be a subclass of output-recording-stream. Subclasses of output-recording-stream must obey the output recording stream protocol.
output-recording-stream-p Function
output-recording-stream-p object
Summary: Returns t if object is an output recording stream; otherwise, it returns nil.
standard-output-recording-stream Class
Summary: The class used by CLIM to implement output record streams. This is a subclass of output-recording-stream. Members of this class are mutable.
The following generic functions comprise the output recording stream protocol. All subclasses of output-recording-stream implement methods for these generic functions.
stream-recording-p Generic Function
stream-recording-p stream
Summary: Returns t when the output recording stream stream is recording all output performed to it; otherwise, it returns nil.
(setf stream-recording-p) Generic Function
(setf stream-recording-p) recording-p stream
Summary: Changes the state of stream-recording-p to be recording-p, which must be either t or nil.
stream-drawing-p Generic Function
stream-drawing-p stream
Summary: Returns t when the output recording stream stream will actually draw on the viewport when output is being performed to it; otherwise, it returns nil.
(setf stream-drawing-p) Generic Function
(setf stream-drawing-p) drawing-p stream
Summary: Changes the state of stream-recording-p to be drawing-p, which must be either t or nil.
stream-output-history Generic Function
stream-output-history stream
Summary: Returns the history (or top-level output record) for the output recording stream stream.
stream-current-output-record Generic Function
stream-current-output-record stream
Summary: The current "open" output record for the output recording stream stream, to which stream-add-output-record will add a new child record. Initially, this is the same as stream-output-history. As nested output records are created, this acts as a "stack".
(setf stream-current-output-record) Generic Function
(setf stream-current-output-record) record stream
Summary: Sets the current "open" output record for the output recording stream stream to the output record record.
stream-add-output-record Generic Function
stream-add-output-record stream record
Summary: Adds the output record record to the current output record on the output recording stream stream. (The current output record is the output record returned by stream-current-output-record.)
stream-replay Generic Function
stream-replay stream &optional region
Summary: Directs the output recording stream stream to invoke replay on its output history. Only those records that overlap the region region (which defaults to the viewport of the stream) are replayed.
We use draw-line* as an example here, but calling any of the drawing functions specified in 2.3 CLIM Drawing Functions and 2.4 Graphics Protocols results in the following series of function calls on an output recording stream:
:around method for medium-draw-line* on the output recording stream is called. This creates an output record with all of the information necessary to replay the output record, if stream-recording-p is t. If stream-drawing-p is t, this then does a call-next-method.
replay-output-record for a graphics displayed output record simply calls the medium drawing function (such as medium-draw-line*) directly on the sheet (not on the medium) with stream-recording-p set to nil and stream-drawing-p set to t.
This is the place where write-string and similar functions are captured in order to create an output record. The generic functions include protocol like stream-write-string that are specialized by output recording streams to do the output recording.
stream-text-output-record Generic Function
stream-text-output-record stream text-style
Summary: Returns a text output record for the output recording stream stream suitable for holding characters in the text style text-style. If there is a currently "open" text output record that can hold characters in the specified text style, it is returned. Otherwise a new text output record is created that can hold characters in that text style, and its starting cursor position is set to the cursor position of stream.
stream-close-text-output-record Generic Function
stream-close-text-output-record stream
Summary: Closes the output recording stream stream's currently "open" text output record by recording the stream's current cursor position as the ending cursor position of the record and adding the text output record to stream's current output record by calling stream-add-output-record.
If there is no "open" text output record, stream-close-text-output-record does nothing.
Calling stream-finish-output, stream-force-output, calling redisplay, setting the text cursor position (via stream-set-cursor-position, terpri, or fresh-line), creating a new output record (for example, via with-new-output-record), or changing the state of stream-recording-p closes the current text output record.
stream-add-character-output Generic Function
stream-add-character-output stream character text-style width height baseline
Summary: Adds the character character to the output recording stream stream's text output record in the text style text-style. width and height are the width and height of the character in device units. baseline is the new baseline for the stream. stream-add-character-output calls add-character-output-to-text-record.
stream-write-char on an output recording stream will call stream-add-character-output when stream-recording-p is t.
stream-add-string-output Generic Function
stream-add-string-output stream string start end text-style width height baseline
Summary: Adds the string string to the output recording stream stream's text output record in the text style text-style. start and end are integers that specify the substring within string to add to the text output record. width and height are the width and height of the string in device units. baseline is the new baseline for the stream. stream-add-string-output calls add-string-output-to-text-record.
stream-write-string on an output recording stream will call stream-add-string-output when stream-recording-p is t.
CLIM provides several helper macros to control the output recording facility.
with-output-recording-options Macro
with-output-recording-options (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
invoke-with-output-recording-options 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 (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
with-output-to-output-record (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
invoke-with-new-output-record 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
invoke-with-output-to-output-record 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
make-design-from-output-record record
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*).
CLIM 2.0 User Guide - 01 Dec 2021 19:38:59