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:

(example-edit-file "capi/graphics/pinboard-test")

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:

   (example-edit-file "capi/output-panes/cached-display")
   

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.