16 Output Recording
16.1 Overview of Output Recording
CLIM provides a mechanism whereby output (textual and graphical) may be captured
into an output history for later replay on the same stream. This
mechanism serves as the basis for many other tools, such as the formatted output
and presentation mechanisms described elsewhere.
The output recording facility is layered on top of the graphics and text output
protocols. It works by intercepting the operations in the graphics and text
output protocols, and saving information about these operations in objects
called output records . In general, an output record is a kind of
display list, that is, a collection of instructions for drawing something on a
stream. Some output records may have children , that is, a collection
of inferior output records. Other output records, which are called
displayed output records , correspond directly to displayed information
on the stream, and do not have children. If you think of output records being
arranged in a tree, displayed output records are all of the leaf nodes in the
tree, for example, displayed text and graphics records.
Displayed output records must record the state of the supplied drawing options
at the instant the output record is created, as follows. The ink supplied by
the programmer must be captured without resolving indirect inks; this is so that
a user can later change the default foreground and background ink of the medium
and have that change affect the already-created output records during replay.
The effect of the specified ``user'' transformation (composed with the medium
transformation) must be captured; CLIM implementations are free to do this
either by saving the transformation object or by saving the transformed values
of all objects that are affected by the transformation. The user clipping
region and line style must be captured in the output record as well. Subsequent
replaying of the record under a new user transformation, clipping region, or
line style will not affect the replayed output. CLIM implementation are
permitted to capture the text style either fully merged against the medium's
default, or not; in the former case, subsequent changes to the medium's default
text style will not affect replaying the record, but in the latter case changing
the default text style will affect replaying.
A CLIM stream that supports output recording has an output history object, which
is a special kind of output record that supports some other operations. CLIM
defines a standard set of output history implementations and a standard set of
output record types.
The output recording mechanism is defined so as to permit application specific
or host window system specific implementations of the various recording
protocols. CLIM implementations should provide several types of standard output
records with different characteristics for search, storage, and retrieval. Two
examples are ``sequence'' output records (which store elements in a sequence,
and whose insertion and retrieval complexity is O(n)) and ``tree'' output
records (which store elements in some sort of tree based on the location of the
element, and whose insertion and retrieval complexity is O(log~n)).
Issue: York, SWM
There is a proposal on the table to unify the sheet and
output record protocols, not by unifying the class structure, but by making them
implement the same generic functions where that makes sense. For instance,
sheets and output records both have regions, transformations (that relate sheets
to their parents), both support a repainting operation, and so forth.
In particular, sheet-parent and output-record-parent are equivalent,
as are sheet-children and output-record-children ,
sheet-adopt-child and add-output-record , sheet-disown-child and
delete-output-record , and repaint-sheet and replay-output-record ,
and the mapping functions. output-record-position and its setf function have sheet analogs. The sheet and output record notification functions
are also equivalent.
This simplifies the conceptual framework of CLIM, and could eventually simplify
the implementation as well. Doing this work now opens the door for later
unifications, such unifying the pane layout functionality with table formatting.
16.2 Output Records
| output-record | [Protocol Class] |
The protocol class that is used to indicate that an object is an output record,
that is, an object that contains other output records. This is a subclass of
bounding-rectangle , and as such, 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 | [Predicate] |
Returns true if object is an output record , otherwise
returns false .
| displayed-output-record | [Protocol Class] |
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 | object | [Predicate] |
Returns true if object is a displayed output record ,
otherwise returns false .
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.
All subclasses of output-record must handle the :size initarg. It is
used to specify how much room should be left for child output records (if, for
example, the children are stored in a vector). It is permissible for :size to be ignored, provided that the resulting output record is able to store the
specified number of child output records.
16.2.1 The Basic Output Record Protocol
All subclasses of output-record and displayed-output-record must
inherit or implement methods for the following generic functions.
When the generic functions in this section take both record and a
stream arguments, CLIM implementations will specialize the stream argument for the standard-output-recording-stream class and the
record argument for all of the implementation-specific output record
classes.
| output-record-position | record | [Generic function] |
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) | x y record | [Generic function] |
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.
For CLIM implementations that do not support setf* , the ``setter'' function
for this is output-record-set-position .
| output-record-start-cursor-position | record | [Generic function] |
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) | x y record | [Generic function] |
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 is a no-op.
For CLIM implementations that do not support setf* , the ``setter'' function
for this is output-record-set-start-cursor-position .
| output-record-end-cursor-position | record | [Generic function] |
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 of the stream. 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) | x y record | [Generic function] |
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 is a no-op.
For CLIM implementations that do not support setf* , the ``setter'' function
for this is output-record-set-end-cursor-position .
| output-record-parent | record | [Generic function] |
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 | [Function] |
This function bind stream-recording-p of stream to false , and
then calls replay-output-record on the arguments record ,
stream , and region . If stream-drawing-p of stream is
false , replay does nothing. replay is typically called during
scrolling, by repaint handlers, and so on.
CLIM implementations are permitted to default region either to nil or
to the region corresponding to viewport of stream .
| replay-output-record | record stream &optional region x-offset y-offset | [Generic function] |
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 can be supplied to limit what records are
displayed. Only those records that overlap region are replayed. The
default for region is +everywhere+ .
It is permissible for implementations to restrict replay-output-record such
that stream must be the same stream on which the output records were
originally recorded.
Issue: SWM
How does replaying a text output record (or any record that
maintains the cursor position) affect the cursor position of the stream? It
is probably that case that replay should not affect the cursor position.
| output-record-hit-detection-rectangle* | record | [Generic function] |
This method is used to establish the usual ``effective size'' of record for hit detection queries. Four values are returned corresponding to the edges
of the bounding rectangle that is the hit detection rectangle. The default
method (on CLIM's standard output record class) is equivalent to calling calling
bounding-rectangle* on record , but this method can be specialized to
return a larger bounding rectangle in order to implement a form of hysteresis.
| output-record-refined-position-test | record x y | [Generic function] |
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 provides a more precise definition of a
hit, 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 | record stream state | [Generic function] |
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) will simply draw a
rectangle that corresponds the the bounding rectangle of record .
| displayed-output-record-ink | displayed-output-record | [Generic function] |
Returns the ink used by the displayed output record displayed-output-record .
16.2.2 The Output Record ``Database'' Protocol
All classes that are subclasses of output-record must implement methods for
the following generic functions.
| output-record-children | record | [Generic function] |
Returns a sequence of all of the children of the output record record . It is unspecified whether the sequence is a freshly created
object or a ``live'' object representing the state of record .
| add-output-record | child record | [Generic function] |
Adds the new output record child to the output record record . The bounding rectangle for record (and all its ancestors)
must be updated to account for the new child record.
The methods for the add-output-record will typically specialize only the
record argument.
| delete-output-record | child record &optional (errorp t ) | [Generic function] |
Removes the output record child from the output record record . The bounding rectangle for record (and all its ancestors)
may be updated to account for the child having been removed, although this is
not mandatory.
If errorp is true (the default) and child is not contained
within record , then an error is signalled.
The methods for the delete-output-record will typically specialize only the
record argument.
| clear-output-record | record | [Generic function] |
Removes all of the children from the output record record , and
resets the bounding rectangle of record to its initial state.
| output-record-count | record | [Generic function] |
Returns the number of children contained within the output record record .
| map-over-output-records-containing-position | function record x y &optional x-offset y-offset &rest function-args | [Generic function] |
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 or more arguments, the first argument being
the record containing the point; it has dynamic extent. function is also
called with all of function-args as ``apply'' arguments.
If there are multiple records that contain the point and that overlap each
other, map-over-output-records-containing-position must hit the uppermost
(most recently inserted) record first and the bottommost (least recently
inserted) record last. Otherwise, the order in which the records are traversed
is unspecified.
| map-over-output-records-overlapping-region | function record region &optional x-offset y-offset &rest function-args | [Generic function] |
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 or more arguments, the first argument being
the record overlapping the region; it has dynamic extent. function is
also called with all of function-args as ``apply'' arguments.
If there are multiple records that overlap the region and that overlap each
other, map-over-output-records-overlapping-region must hit the bottommost
(least recently inserted) record first and the uppermost (most recently
inserted) record last. Otherwise, the order in which the records are traversed
is unspecified.
16.2.3 Output Record Change Notification Protocol
The following functions are called by programmers and by CLIM itself in order to
notify a parent output record when the bounding rectangle of one of its child output
record changes.
| recompute-extent-for-new-child | record child | [Generic function] |
This function is called whenever a new child is added to an output record. Its
contract is to update the bounding rectangle of the output record record to be large enough to completely contain the new child output
record child . The parent of record must be notified by calling
recompute-extent-for-changed-child .
add-output-record is required to call recompute-extent-for-new-child .
| recompute-extent-for-changed-child | record child
old-min-x old-min-y old-max-x old-max-y | [Generic function] |
This function is called whenever the bounding rectangle of one of the childs of
a record has been changed. Its contract is to update the bounding rectangle of
the output record record to be large enough to completely contain
the new bounding rectangle of the child output record child . All
of the ancestors of record must be notified by recursively calling
recompute-extent-for-changed-child .
Whenever the bounding rectangle of an output record is changed or
delete-output-record is called, recompute-extent-for-changed-child must be called to inform the parent of the record that a change has taken place.
| tree-recompute-extent | record | [Generic function] |
This function is called whenever the bounding rectangles of a number of children
of a record have been changed, such as happens during table and graph
formatting. Its contract is to compute the bounding rectangle large enough to
contain all of the children of the output record record , adjust the
bounding rectangle of the output record record accordingly, and
then call recompute-extent-for-changed-child on record .
16.3 Types of Output Records
This section discusses several types of output records, including two standard
classes of output records and the displayed output record protocol.
16.3.1 Standard Output Record Classes
| standard-sequence-output-record | [Class] |
The standard instantiable class provided by CLIM to store a relatively short
sequence of output records; a subclass of output-record . The insertion and
retrieval complexity of this class is O(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] |
The standard instantiable class provided by CLIM to store longer sequences of
output records. Typically, the child records of a tree output record will be
maintained in some sort of sorted order, such as a lexicographic ordering on the
x and y coordinates of the children. The insertion and retrieval complexity
of this class is O(log~n).
16.3.2 Graphics Displayed Output Records
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.
The exact contents of graphics displayed output records is unspecified, but they
must store sufficient information to be able to exactly redraw the original
output at replay time. The minimum information that must be captured for
all graphics displayed output records is as follows:
- The description of the graphical object itself, for example, the end
points of a line or the center point and radius of a circle.
- The programmer-supplied ink at the time the drawing function was called.
Indirect inks must not be resolved, so that a user can later change the default
foreground and background ink of the medium and have that change affect the
already-created output records during replay.
- For paths, the programmer-supplied line-style at the time the drawing
function was called.
- The programmer-supplied clipping region at the time the drawing function
was called.
- The user transformation. This may be accomplished by either explicitly
storing the transformation, or by transforming the coordinates supplied to the
drawing function and capturing the transformed coordinates.
| graphics-displayed-output-record | [Protocol Class] |
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 | object | [Predicate] |
Returns true if object is a graphics displayed output
record , otherwise returns false .
16.3.3 Text Displayed Output Record
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 described below).
The exact contents of text displayed output records is unspecified, but they
must store sufficient information to be able to exactly redraw the original
output at replay time. The minimum information that must be captured for all
text displayed output records is as follows:
- The displayed text strings.
- The starting and ending cursor positions.
- The text style in which the text string was written. Depending on the
CLIM implementation, this may be either fully merged against the medium's
default or not; in the former case, subsequent changes to the medium's default
text style will not affect replaying the record, but in the latter case changing
the default text style will affect replaying.
- The programmer-supplied ink at the time the drawing function was called.
Indirect inks must not be resolved, so that a user can later change the default
foreground and background ink of the medium and have that change affect the
already-created output records during replay.
- The programmer-supplied clipping region at the time the drawing function
was called.
| text-displayed-output-record | [Protocol Class] |
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 | object | [Predicate] |
Returns true if object is a text displayed output record ,
otherwise returns false .
The following two generic functions comprise the text displayed output record
protocol.
| add-character-output-to-text-record | text-record character text-style
width height baseline | [Generic function] |
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 | text-record string start end text-style
width height baseline | [Generic function] |
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 | text-record | [Generic function] |
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. 16.3.4 Top-Level Output Records
Top-level output records are similar to ordinary output records, except that
they must maintain additional state, such as the information required to display
scroll bars.
| stream-output-history-mixin | [Class] |
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. This class is not
intended to be instantiated.
When the bounding rectangle of an member of this class is updated, CLIM
implementations must update any window decorations (such as scroll bars)
associated with the stream with which the output record history is
associated.
| standard-tree-output-history | [Class] |
The standard instantiable 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 .
| standard-sequence-output-history | [Class] |
Another instantiable class provided by CLIM to use for top-level output records
that have only a small number of children. This will typically be a subclass of
both standard-sequence-output-record and stream-output-history-mixin .
16.4 Output Recording Streams
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.
Issue: SWM
Do we want to support only output recording streams, or do we
want to support output recording sheets as well? If the latter, we need to
split apart graphics output recording and textual output recording, and rename
lots of things.
| output-recording-stream | [Protocol Class] |
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 | object | [Predicate] |
Returns true if object is an output recording stream ,
otherwise returns false .
| standard-output-recording-stream | [Class] |
The class used by CLIM to implement output record streams. This is a subclass
of output-recording-stream .
Members of this class are mutable. 16.4.1 The Output Recording Stream Protocol
The following generic functions comprise the output recording stream protocol.
All subclasses of output-recording-stream must implement methods for these
generic functions.
| stream-recording-p | stream | [Generic function] |
Returns true when the output recording stream stream is
recording all output performed to it, otherwise returns false .
| (setf stream-recording-p) | recording-p stream | [Generic function] |
Changes the state of stream-recording-p to be recording-p , which must
be either t or nil .
| stream-drawing-p | stream | [Generic function] |
Returns true when the output recording stream stream will
actually draw on the viewport when output is being performed to it, otherwise
returns false .
| (setf stream-drawing-p) | drawing-p stream | [Generic function] |
Changes the state of stream-recording-p to be drawing-p , which must
be either t or nil .
| stream-output-history | stream | [Generic function] |
Returns the history (or top-level output record) for the output recording
stream stream .
| stream-current-output-record | stream | [Generic function] |
The current ``open'' output record for the output recording stream stream , the one 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) | record stream | [Generic function] |
Sets the current ``open'' output record for the output recording stream stream to the output record record .
| stream-add-output-record | stream record | [Generic function] |
Adds the output record record to the current output record on the
output recording stream stream (that is,
stream-current-output-record ).
| stream-replay | stream &optional region | [Generic function] |
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.
| erase-output-record | record stream &optional (errorp t ) | [Generic function] |
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 .
If record is not in the stream's output history, then an error is
signalled, unless errorp is false .
| copy-textual-output-history | window stream &optional region record | [Function] |
Given an output recording stream window and a character output
stream stream , copy-textual-output-history maps over all of the
textual output records in the region region and writes them to
stream , in order from the top of the output to the bottom of the output.
If record is supplied, it is the top-level record to map over. It
defaults to stream-output-history of window .
16.4.2 Graphics Output Recording
Using draw-line* as an example, calling any of the drawing functions
specified in Section Drawing Functions and
Section Graphics Protocols on an output recording stream results in the
following series of function calls:
- A program calls draw-line* on arguments stream (and output
recording stream), x1 , y1 , x2 , and y2 , and perhaps some
drawing options.
- draw-line* merges the supplied drawing options into the stream's
medium, and then calls medium-draw-line* on the stream. (Note that a
compiler macro could detect the case where there are no drawing options or
constant drawing options, and do this at compile time.)
- The :around method for medium-draw-line* on the output recording
stream is called. If stream-recording-p is true , this creates an
output record with all of the information necessary to replay the output record.
If stream-drawing-p is true , this then does a call-next-method .
(Note that the call-next-method could be replaced by a call to the
medium-draw-line* method on the stream's medium, avoiding the need for a
trampolining function call.)
- An :around method for medium-draw-line* performs the necessary
user transformations by applying the medium transformation to x1 ,
y1 , x2 , and y2 , and to the clipping region, and then calls the
medium-specific method.
- The ``real'' medium-draw-line* transforms the start and end
coordinates of the line by the stream's device transformation, decodes the ink
and line style into port-specific objects, and finally invokes a port-specific
function (such as xlib:draw-line ) to do the actual drawing.
replay-output-record for a graphics displayed output record simply binds
the state of the medium to the state captured in the output record, and calls
the medium drawing function (such as medium-draw-line* ) directly on the
medium, with stream-recording-p of the stream set to false and
stream-drawing-p set to true .
16.4.3 Text Output Recording
Issue: SWM
This is the place where write-string and friends get captured
in order to create output record. The generic functions include things like
stream-write-string , which are specialized by output recording streams to
do the output recording. Describe exactly what happens.
| stream-text-output-record | stream text-style | [Generic function] |
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 simply returned. Otherwise a new text output record
is created that can hold characters in that text style, and its starting cursor
position set to the cursor position of stream .
| stream-close-text-output-record | stream | [Generic function] |
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 or 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 must close the current text output record.
Some CLIM implementations may also choose to close the current text output
record when the stream's drawing options or text style are changed, depending on
the exact implementation of text output records.
| stream-add-character-output | stream character text-style
width height baseline | [Generic function] |
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 must be implemented by calling
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 true .
| stream-add-string-output | stream string start end text-style
width height baseline | [Generic function] |
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 must be implemented by
calling 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 true .
16.4.4 Output Recording Utilities
CLIM provides several helper macros to control the output recording facility.
| with-output-recording-options | (stream &key record draw) &body body | [Macro] |
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 must be implemented by expanding 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 . The exact behavior of this macro is
described under invoke-with-output-recording-options .
| invoke-with-output-recording-options | stream continuation record draw | [Generic function] |
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 false , output to the stream is not drawn on the
viewport, but recording proceeds according to record ; if draw is
true , the output is drawn. If record is nil , output recording
is disabled, but output otherwise proceeds according to draw ; if
draw is true , 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 initargs)
&body body | [Macro] |
Creates a new output record of type record-type (which defaults to
standard-sequence-output-record ) and then 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 designated by
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. initargs are CLOS initargs
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 must be implemented by expanding 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 . The exact
behavior of this macro is described under invoke-with-new-output-record .
| invoke-with-new-output-record | stream continuation record-type
&rest initargs &key parent &allow-other-keys | [Generic function] |
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.
initargs are CLOS initargs that are passed to make-instance when the
new output record is created. The parent initarg is handled specially,
and specifies what output record should serve as the parent for the newly
created record. If unspecified, stream-current-output-record of
stream will be used as the parent.
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 .
| with-output-to-output-record | (stream &optional record-type record
&rest initargs))
&body body | [Macro] |
This is identical to 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 . initargs are CLOS initargs that are
passed to make-instance when the new output record is created.
If record is supplied, it 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 must be implemented by expanding 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 . The exact behavior of this macro is
described under invoke-with-output-to-output-record .
| invoke-with-output-to-output-record | stream continuation record-type
&rest initargs &key | [Generic function] |
This is similar to 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. initargs are CLOS initargs 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 | record | [Generic function] |
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.
It is permissible for implementations to support 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* ).