start-drawing-with-cached-display 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 resize-automatic-cancel user-info from-display-p

Arguments

Description

The function start-drawing-with-cached-display caches the display of the output pane pane (by calling output-pane-cache-display with pane and from-display-p, which defaults to nil), 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 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 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 or is resized. 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. If automatic-cancel is a designator for function, it is called with pane after the cached displayed is canceled.

resize-automatic-cancel, which defaults to automatic-cancel, has the same effect as as automatic-cancel but controls what happens when the window is resized rather than when it loses the focus.

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
12.5 Transient display on output-pane and subclasses