Page 182 Table of Contents Index Page 184
Chapters
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30
A, B, C, D, E


CHAPTER 21. INCREMENTAL REDISPLAY

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 provides a means to uniquely identify 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 true, 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 false.

If fixed-position is true, 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 false.

If all-new is true, 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 false.

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 some output record P 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 P. 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) [Function]
This function simply calls redisplay-output-record on the arguments record and stream.

=> redisplay-output-record record stream &optional (check-overlapping t) x y parent-x parent-
y [Generic Function]


Minor issue: The coordinate system stuff affected by the x/y and parent-x/y arguments is

Page 182 Table of Contents Index Page 184
Chapters
1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30
A, B, C, D, E