The setting of any CAPI property that should affect the display causes CAPI to redisplay the relevant elements. However, when what is displayed depends on a state which is not a CAPI state, and this state changes, you may need to cause CAPI to redisplay.
For example, you may have a list-panel where the items are some objects, and the print-function generates a string for each object, based on some property of the object (typically a slot value). If that property changes then the display also needs to change, but there is no way for CAPI to know that so you need to tell CAPI explicitly.
A simple way to achieve this is to set a CAPI state which will cause redisplay. For example, doing
leaves my-pane 's items unchanged, but because the value is set CAPI redisplays all of the items. This approach, however, is both computationally expensive when done often with large number of items, and causes flickering on screen that can be avoided.
Instead you can use one of the following functions.
Often you need several distinct updates to the display to appear simultaneously. For example when you set the text in several elements at the same time, or you set the text of an element and then also set the background. To ensure that multiple updates appear together, wrap the macro with-atomic-redisplay around the updates.
CAPI User Guide and Reference Manual (Macintosh version) - 25 Feb 2015