Function

Summary

Temporarily replaces an output pane's display-callback such that it draws from the cached display and optionally adds further drawing.

Package

capi

Signature

start-drawing-with-cached-display pane temp-display-callback &key automatic-cancel user-info

Arguments

pane

An output-pane.

temp-display-callback

A function designator, or nil.

automatic-cancel

A generalized boolean.

user-info

A Lisp object.

Description

The function start-drawing-with-cached-display caches the display of the output pane pane (by calling output-pane-cache-display), remembers the current display-callback , and replaces the display-callback with a callback that first uses the cached display to redraw the area and then uses the temp-display-callback (if non-nil) to draw additional arbitrary drawing. temp-display-callback has the same signature as the display-callback of pane :

temp-display-callback pane x y width height

The arguments that will be passed to the temp-display-callback are determined by calls to update-drawing-with-cached-display or update-drawing-with-cached-display-from-points. These functions should be called whenever the temporary display needs to be updated.

The effect of start-drawing-with-cached-display is undone by any call to output-pane-free-cached-display (implicit or explicit). Since output-pane-cache-display, and hence start-drawing-with-cached-display itself, makes an implicit call to output-pane-free-cached-display, it is not essential to call output-pane-free-cached-display between calls. However, the cached display can be quite large, so it is normally better to call output-pane-free-cached-display as soon as the cache is no longer needed.

If automatic-cancel is true then the cached drawing is automatically cancelled (by an implicit call to output-pane-free-cached-display) when the pane loses the focus. This is useful when a cached display is used temporarily, for example during drag and drop. If the cached display needs to survive longer, pass :automatic-cancel nil. The default value of automatic-cancel is true.

user-info is an arbitrary value which will be returned by calls to output-pane-cached-display-user-info and the call to output-pane-free-cached-display. It is useful for keeping information during an operation that uses the cached display, for example drag and drop.

Notes

1. The most natural usage of this function is in the :press input model handler, with a matching output-pane-free-cached-display call in the :release handler, to temporarily draw something on top of the permanent display while the user drags the mouse.
2. start-drawing-with-cached-display and its associated functions (update-drawing-with-cached-display and update-drawing-with-cached-display-from-points) use the cached display functions (output-pane-cache-display, output-pane-draw-from-cached-display, and output-pane-free-cached-display). Calling the cached display functions in the scope of start-drawing-with-cached-display and output-pane-free-cached-display would confuse them.

Examples

This file shows how to use start-drawing-with-cached-display in the :press input model handler:

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

See also

output-pane-cache-display
output-pane-free-cached-display
output-pane-cached-display-user-info
redraw-drawing-with-cached-display
update-drawing-with-cached-display
update-drawing-with-cached-display-from-points
Transient display on output-pane and subclasses