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. [annotate]

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. [annotate]

[output records, Concept← A Glossary]

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. [annotate]

Note: It is said that the clipping region is captured by the output record but this is bollocks. We need to treat the clipping region as a separate record, so it is moved with other output records when the formatting macro moves cells, and stay in place if only its descendants are moved. [edit]-- DK 2022-11-03 15:24Z

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. [annotate]

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)). [annotate]

Major issue: 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. [annotate]

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. [annotate]

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. --- York, SWM [annotate]