12.5 Transient display on output-pane and subclasses

It is quite often that you want to transiently add some drawing on top of the permanent drawing of an output-pane. Most typically, you want to allow the user to select an area by dragging the mouse while pressing a button, and you want to include some transient graphics to indicate what they are going to select. This could simply be a rectangle, but you may want something more complex.

Ideally, the display-callback of the pane would be fast enough to handle this, in which case you simply need to make the display-callback draw the transient graphics. For example, in the case of a pinboard-layout, it can be done by adding a transient pinboard-object above the other objects. This is demonstrated by the "outliner" example:

Note that in this case the outliner's drawing is simple, but it could draw much more complex graphics if required.

However, that solution does not work well if the display-callback is not fast enough for these situations. The Cached Display functionality is intended to be used in this case. There are two ways to use the Cached Display interface:

1. Use output-pane-cache-display to cache the display, and then output-pane-draw-from-cached-display to draw from the cache. In this case you have to ensure that the display-callback knows when to use output-pane-draw-from-cached-display, either by replacing the display-callback for the duration of the Cached Display operation or by keeping a flag that the display-callback checks, for example:

(if (drawing-by-cached-display-p pane)

    (progn 

      (output-pane-draw-from-cached-display pane x y width height)

      (do-some-transient-drawing pane))

  (real-display-callback pane x y width height))

2. Use start-drawing-with-cached-display, which replaces the display-callback , and then use update-drawing-with-cached-display or update-drawing-with-cached-display-from-points to update the display. This technique is illustrated in

In both cases you finish using the cached display by calling output-pane-free-cached-display. The function output-pane-cached-display-user-info can be used to hold temporary data during the operation.

CAPI User Guide and Reference Manual (Unix version) - 25 Feb 2015