The following functions are used to create an output record that should be incrementally redisplayed, and then to redisplay that record.
updating-output (stream &rest args &key unique-id (id-test \#'eql) cache-value (cache-test \#'eql) copy-cache-value fixed-position all-new parent-cache record-type) &body body
Summary: Introduces a caching point for incremental redisplay.
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.
record-type specifies the class of output record to create. The default is standard-updating-output-record. This argument should only be supplied by a programmer if there is a new class of output record that supports the updating output record protocol.
updating-output expands into a call to invoke-updating-output, supplying a function that executes body as the continuation argument to invoke-updating-output.
invoke-updating-output Generic Function
invoke-updating-output stream continuation record-type unique-id id-test cache-value cache-test copy-cache-value &key all-new parent-cache
Summary: Introduces a caching point for incremental redisplay. Calls the function continuation, which generates the output records to be redisplayed. continuation is a function of one argument, the stream; it has dynamic extent.
If this is used outside the dynamic scope of an incremental redisplay, it has no particular effect. However, when incremental redisplay is occurring, the supplied cache-value is compared with the value stored in the cache identified by unique-id. If the values differ or the code in body has not been run before, the code in body runs, and cache-value is saved for next time. If the cache values are the same, the code in body is not run, because the current output is still valid.
unique-id uniquely identifies the output done by body. If unique-id is not supplied, CLIM will generate one that is guaranteed to be unique. unique-id may be any object as long as it is unique with respect to the id-test predicate among all such unique ids in the current incremental redisplay. id-test is a function of two arguments that is used for comparing unique ids; it has indefinite extent.
cache-value is a value that remains constant if and only if the output produced by body does not need to be recomputed. If the cache value is not supplied, CLIM will not use a cache for this piece of output. cache-test is a function of two arguments that is used for comparing cache values; it has indefinite extent. If copy-cache-value is t, then the supplied cache value will be copied using copy-seq before it is stored in the output record. The default for copy-cache-value is nil.
If fixed-position is t, then the location of this output is fixed relative to its parent output record. When CLIM redisplays an output record that has a fixed position, then if the contents have not changed, the position of the output record will not change. If the contents have changed, CLIM assumes that the code will take care to preserve its position. The default for fixed-position is nil.
If all-new is t, that indicates that all of the output done by body is new, and will never match output previously recorded. In this case, CLIM will discard the old output and do the redisplay from scratch. The default for all-new is nil.
The output record tree created by updating-output defines a caching structure where mappings from a unique-id to an output record are maintained. If the programmer specifies an output record via the parent-cache argument, then CLIM will try to find a corresponding output record with the matching unique-id in the cache belonging to parent-cache. If neither parent-cache is not provided, then CLIM looks for the unique-id in the output record created by immediate dynamically enclosing call to updating-output. If that fails, CLIM use the unique-id to find an output record that is a child of the output history of stream. Once CLIM has found an output record that matches the unique-id, it uses the cache value and cache test to determine whether the output record has changed. If the output record has not changed, it may have moved, in which case CLIM will simply move the display of the output record on the display device.
redisplay record stream &key (check-overlapping t)
Summary: This function calls redisplay-output-record on the arguments record and stream. When check-overlapping is t, redisplay checks overlapped output records more carefully in order to display them correctly. The default is nil.
redisplay-output-record Generic Function
redisplay-output-record record stream &optional (check-overlapping t) x y parent-x parent-y
Summary: (redisplay-output-record record stream) causes the output of record to be recomputed. CLIM redisplays the changes "incrementally"; that is, it only displays those parts that have been changed. record must already be part of the output history of the output recording stream stream, although it can be anywhere inside the hierarchy.
When check-overlapping is t, redisplay checks overlapped output records more carefully in order to display them correctly. The default is nil. 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.
The other optional arguments can be used to specify where on the stream the output record should be redisplayed. x and y represent where the cursor should be, relative to (output-record-parent record), before record is redisplayed. parent-x and parent-y can be supplied to say: do the output as if the parent started at positions parent-x and parent-y (which are in absolute coordinates). The default values for x and y are (output-record-start-position record). The default values for parent-x and parent-y are:
(convert-from-relative-to-absolute-coordinates stream (output-record-parent record))
record will usually be an output record created by updating-output. If it is not, then redisplay-output-record will be equivalent to replay-output-record.
CLIM 2.0 User Guide - 01 Dec 2021 19:38:59