21.3 Incremental Redisplay Protocol

Major issue: While the description of the API here is accurate, the description of the protocol is a disaster. This is no surprise, since the protocol for increment redisplay is itself a disaster. --- SWM [annotate]

updating-output-record   [Protocol Class]

The protocol class corresponding to records that support incremental redisplay; a subclass of output-record. If you want to create a new class that behaves like an updating output record, it should be a subclass of updating-output-record. All instantiable subclasses of updating-output-record must obey the updating output record protocol. [annotate]


updating-output-record-p  object [Protocol Predicate]

Returns true if object is an updating output record, otherwise returns false. [annotate]


:unique-id   [Initarg]
:id-test   [Initarg]
:cache-value   [Initarg]
:cache-test   [Initarg]
:fixed-position   [Initarg]

All subclasses of updating-output-record must handle these four initargs, which are used to specify, respectively, the unique id and id test, cache value and cache test, and the "fixed position" component of the output record. [annotate]


standard-updating-output-record   [Class]

The instantiable class of output record that supports incremental redisplay. This is a subclass of updating-output-record. [annotate]


output-record-unique-id  record [Generic Function]

Returns the unique id associated with the updating output record record. [annotate]


output-record-cache-value  record [Generic Function]

Returns the cache value associated with the updating output record record. [annotate]


output-record-fixed-position  record [Generic Function]

Returns true if the updating output record record is at a fixed location on the output stream, otherwise returns false. Output records that are not at fixed location on the output stream will be moved by incremental redisplay when any of their siblings adjust their size or position. [annotate]


output-record-displayer  record [Generic Function]

Returns the function that produces the output for this output record. This is the function that is called during redisplay to produce new output if the cache value mismatches. [annotate]


compute-new-output-records  record stream [Generic Function]

compute-new-output-records modifies an output record tree to reflect new output done by the application. In addition to inserting the new output records into the output record tree, it must save enough information to be able to compute the difference set, such as the old bounding rectangle, old cursor positions, old children, and so forth. [annotate]

compute-new-output-records recursively invokes itself on each child of record. [annotate]

compute-new-output-records of an output record of type updating-output-record runs the displayer (output-record-displayer), which gives the behavior of incremental redisplay. That is, it reruns the code (getting hints from updating-output) and figures out the changes from there by comparing it to the old output history. [annotate]


compute-difference-set  record &optional (check-overlapping t) (offset-x 0) (offset-y 0) (old-offset-x 0) (old-offset-y 0) [Generic Function]

compute-difference-set compares the current state of the output record record with its previous state, and returns a "difference set" as five values. The difference set controls what needs to be done to the display device in order to accomplish the incremental redisplay. [annotate]

The values returned are erases (what areas of the display device need to be erased), moves (what output records need to be moved), draws (what output records need to be freshly replayed), erase-overlapping, and move-overlapping. Each is a list whose elements are lists of the form: [annotate]

When check-overlapping is false, this means that CLIM can assume that no sibling output records overlap each other at any level. Supplying a false value for this argument can improve performance of redisplay. [annotate]

  • erases are lists of (record old-box) [annotate]
  • moves are lists of (record old-box new-position) [annotate]
  • draws are lists of (record old-box) [annotate]
  • erase-overlapping is a list of (record old-box) [annotate]
  • move-overlapping is a list of (record old-box new-position) [annotate]


augment-draw-set  record erases moves draws erase-overlapping move-overlapping &optional x-offset y-offset old-x-offset old-y-offset [Generic Function]

Minor issue: To be supplied. --- SWM [annotate]



After CLIM-TOS source code:

If there are any output records that can have overlapping children, none of which have been inserted into the "erase" or "draw" sets, but overlap anything in the "erase" set, then we must insert the child into the "draw" set so that it does not simply disappear.

[edit]-- DK 2021-11-23 19:13Z

note-output-record-child-changed   [Generic Function]

record child mode old-position old-bounding-rectangle stream &optional erases moves draws erase-overlapping move-overlapping &key check-overlapping [annotate]

note-output-record-child-changed is called after an output history has had changes made to it, but before any of the new output has been displayed. It will call propagate-output-record-changes-p to determine if the parent output record should be notified, and if so, will call propagate-output-record-changes to create an updated difference set. If no changes need to be propagated to the parent output record, then note-output-record-child-changed will call incremental-redisplay in order display the difference set. [annotate]

mode is one of :delete, :add, :change, :move, or :none [annotate]

old-position and old-bounding-rectangle describe where child was before it was moved. [annotate]

check-overlapping is as for compute-difference-set. [annotate]


propagate-output-record-changes-p  record child mode old-position old-bounding-rectangle [Generic Function]

propagate-output-record-changes-p is a predicate that returns true if the change made to the child will cause record to be redisplayed in any way. Otherwise, it returns false. mode is one of :delete, :add, :change, :move, or :none. [annotate]


propagate-output-record-changes   [Generic Function]

record child mode &optional old-position old-bounding-rectangle erases moves draws erase-overlapping move-overlapping check-overlapping [annotate]

Called when the changed child output record requires that its parent, record, be redisplayed as well. propagate-output-record-changes will update the difference set to reflect the additional changes. [annotate]

check-overlapping is as for compute-difference-set. [annotate]


match-output-records  record &rest initargs [Generic Function]

Returns true if record matches the supplied class initargs initargs, otherwise returns false. [annotate]

Note: This is pretty useless for records that either have undocumented initargs or slots that aren't initialized by initargs (i.e. all the graphics output records and text output records). Also, how is generic code supposed to generate the list of initargs and values? In McCLIM I've defined output-record-equal which compares two records for equivalence; it's much more useful. [edit]-- Tim Moore 2003-02-22 17:56Z


find-child-output-record  record use-old-elements record-type &rest initargs &key unique-id unique-id-test [Generic Function]

Finds a child of record matching the record-type and the supplied initargs initargs. unique-id and unique-id-test are used to match against the children as well. use-old-elements controls whether the desired record is to be found in the previous (before redisplay) contents of the record. [annotate]


output-record-contents-ok  record [Generic Function]

Returns true if the current state of record are up to date, otherwise returns false. [annotate]


recompute-contents-ok  record [Generic Function]

Compares the old (before redisplay) and new contents of record to determine whether or not this record changed in such a way so that the display needs updating. [annotate]


cache-output-record  record child unique-id [Generic Function]

record stores child such that it can be located later using unique-id. [annotate]


decache-child-output-record  record child use-old-elements [Generic Function]

Invalidates the redisplay state of record. [annotate]


find-cached-output-record  record use-old-elements record-type &rest initargs &key unique-id unique-id-test &allow-other-keys  [Generic Function]

Finds a previously cached child matching record-type, initargs, unique-id, and unique-id-test. use-old-elements controls whether the desired record is to be found in the previous (before redisplay) contents of the record. [annotate]