update-drawing-with-cached-display

update-drawing-with-cached-display-from-points Functions

Summary

Updates the drawing using the cached display.

Package

capi

Signatures

update-drawing-with-cached-display pane &optional x y width height

update-drawing-with-cached-display-from-points pane x1 y1 x2 y2 &key extend extend-x extend-y

Arguments

`pane`⇩	An output-pane.
`x`⇩, `y`⇩, `width`⇩, `height`⇩
	Real numbers.
`x1`⇩, `y1`⇩, `x2`⇩, `y2`⇩, `extend`⇩, `extend-x`⇩, `extend-y`⇩
	Real numbers.

Description

The functions update-drawing-with-cached-display and update-drawing-with-cached-display-from-points update the drawing using the cached display, indicating the rectangle in which the temp-display-callback (argument to start-drawing-with-cached-display) needs to draw.

These functions must be called in the scope of start-drawing-with-cached-display or output-pane-free-cached-display. Calls outside this scope have no effect.

pane is the output pane to update. The other arguments specify the rectangle to be updated. The arguments are used in three ways: first they cause an implicit call to invalidate-rectangle with the appropriate arguments, secondly they define a mask that is used when calling the temp-display-callback, and third they provide arguments that are passed to the temp-display-callback.

In the case of update-drawing-with-cached-display, the arguments specify the rectangle in the standard way (the same way that they are passed to the display-callback). x and y default to 0, width defaults to the width of pane minus x, and height defaults to the height of pane minus y.

In the case of update-drawing-with-cached-display-from-points, the arguments specify two points, (x1,y1) and (x2,y2), which are corners of a rectangle. This rectangle is then extended horizontally in both directions by extend-x, and extended vertically in both directions by extend-y. extend-x and extend-y default to extend, which defaults to 0. The final result is:

x = (- (min x1 x2) extend-x)
y = (- (min y1 y2) extend-y)
width = (+ (- (max x1 x2) x) extend-x)
height = (+ (- (max y1 y2) y) extend-y)

Both extend-x and extend-y default to extent, which itself defaults to 0.

Notes

Omitting the rectangle (that is, calling update-drawing-with-cached-display with only pane) causes all of the pane to be redisplayed each time. On slow displays, that may cause the display to be sluggish. On Windows and Cocoa with the normal settings, it is probably always fast enough, at least with modern machines. On GTK+ it depends on the speed of the connection to the X server, which in many cases is too slow for medium-size panes.

These calls also take care to redraw the area that was drawn by previous calls to the temp-display-callback, so you do not to do anything about erasing the results of previous calls.

Examples

This file shows how to use update-drawing-with-cached-display-from-points to redraw an arrowhead shape:

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