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. [annotate]
Minor issue: 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. --- SWM [annotate]
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. All instantiable subclasses of output-recording-stream must obey the output recording stream protocol. [annotate] |
Returns true if object is an output recording stream, otherwise returns false. [annotate] |
The class used by CLIM to implement output record streams. This is a subclass of output-recording-stream. Members of this class are mutable. [annotate] |
The following generic functions comprise the output recording stream protocol. All subclasses of output-recording-stream must implement methods for these generic functions. [annotate]
Changes the state of stream-recording-p to be recording-p, which must be either t or nil. [annotate] |
Returns true when the output recording stream stream will actually draw on the viewport when output is being performed to it, otherwise returns false. [annotate] |
Changes the state of stream-recording-p to be drawing-p, which must be either t or nil. [annotate] |
Returns the history (or top-level output record) for the output recording stream stream. [annotate] |
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". [annotate] |
Sets the current "open" output record for the output recording stream stream to the output record record. [annotate] |
Adds the output record record to the current output record on the output recording stream stream (that is, stream-current-output-record). [annotate] |
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. [annotate] |
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. [annotate] If record is not in the stream's output history, then an error is signalled, unless errorp is false. [annotate] |
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. [annotate] If record is supplied, it is the top-level record to map over. It defaults to stream-output-history of window. [annotate] |
Using draw-line* as an example, calling any of the drawing functions specified in Section 12.5 and Section 12.7 on an output recording stream results in the following series of function calls: [annotate]
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. [annotate]
Major issue: 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. --- SWM [annotate]
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. [annotate] |
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. [annotate] If there is no "open" text output record, stream-close-text-output-record does nothing. [annotate] 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. [annotate] Note: STREAM-{FINISH,FORCE}-OUTPUT close the text output record to ensure that it is added to the output record history; but can we "reopen" the line afterwards? Functions TERPRI and FRESH-LINE are different from (SETF STREAM-CURSOR-POSITION) because the former should open a new text output record with position relative to the old one; while the latter makes the new text output record to have an absolute position. [edit]-- DK 2024-07-04 09:32Z |
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. [annotate] stream-write-char on an output recording stream will call stream-add-character-output when stream-recording-p is true. [annotate] |
| 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. [annotate] stream-write-string on an output recording stream will call stream-add-string-output when stream-recording-p is true. [annotate] |
CLIM provides several helper macros to control the output recording facility. [annotate]
Enables or disables output recording and/or drawing on the output recording stream designated by stream, within the extent of body. [annotate] 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. [annotate] 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. [annotate] |
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. [annotate] 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. [annotate] Note: I presume that the second "if draw is true" there is meant to read "if record is true". [edit]-- Christophe Rhodes 2004-02-28 16:23Z All output recording streams must implement a method for invoke-with-output-recording-options. [annotate] |
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. [annotate] 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. [annotate] with-new-output-record returns the output record it creates. [annotate] 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. [annotate] 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. [annotate] |
| 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. [annotate] continuation is a function of two arguments, the stream and the output record; it has dynamic extent. [annotate] 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. [annotate] invoke-with-new-output-record returns the output record it creates. [annotate] All output recording streams must implement a method for invoke-with-new-output-record. [annotate] |
| 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). [annotate] 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. [annotate] If record is supplied, it is a variable that will be bound to the new output record while body is evaluated. [annotate] with-output-to-output-record returns the output record it creates. [annotate] 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. [annotate] 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. [annotate] |
| 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. [annotate] 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. [annotate] invoke-with-output-to-output-record returns the output record it creates. [annotate] All output recording streams must implement a method for invoke-with-output-to-output-record. [annotate] |
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. [annotate] 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*). [annotate] |