Temporarily replaces an output pane's display-callback such that it draws from the cached display and optionally adds further drawing.
capi
start-drawing-with-cached-display pane temp-display-callback &key automatic-cancel resize-automatic-cancel user-info from-display-p
pane⇩ |
An output-pane. |
temp-display-callback⇩ | |
A function designator, or nil . | |
automatic-cancel⇩ | nil , t or a designator for a function of one argument. |
resize-automatic-cancel⇩ | |
nil , t or a designator for function of one argument. | |
user-info⇩ |
A Lisp object. |
from-display-p⇩ |
A boolean. |
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.
: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.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.
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")
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
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:32:42