Tk_CanvasTkwin(3Tk)Tk_CanvasTkwin(3Tk)NAME
Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords,
Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords,
Tk_CanvasEventuallyRedraw - utility procedures for canvas type managers
SYNOPSIS
#include <tk.h>
Tk_Window
Tk_CanvasTkwin(canvas)
int
Tk_CanvasGetCoord(interp, canvas, string, doublePtr)
Tk_CanvasDrawableCoords(canvas, x, y, drawableXPtr, drawableYPtr)
Tk_CanvasSetStippleOrigin(canvas, gc)
Tk_CanvasWindowCoords(canvas, x, y, screenXPtr, screenYPtr)
Tk_CanvasEventuallyRedraw(canvas, x1, y1, x2, y2)
ARGUMENTS
Tk_Canvas canvas (in) A token that identifies a canvas
widget.
Tcl_Interp *interp (in/out) Interpreter to use for error
reporting.
char *string (in) Textual description of a canvas
coordinate.
double *doublePtr (out) Points to place to store a
converted coordinate.
double x (in) An x coordinate in the space of
the canvas.
double y (in) A y coordinate in the space of
the canvas.
short *drawableXPtr (out) Pointer to a location in which to
store an x coordinate in the
space of the drawable currently
being used to redisplay the
canvas.
short *drawableYPtr (out) Pointer to a location in which to
store a y coordinate in the space
of the drawable currently being
used to redisplay the canvas.
Page 1
Tk_CanvasTkwin(3Tk)Tk_CanvasTkwin(3Tk)
GC gc (out) Graphics context to modify.
short *screenXPtr (out) Points to a location in which to
store the screen coordinate in
the canvas window that
corresponds to x.
short *screenYPtr (out) Points to a location in which to
store the screen coordinate in
the canvas window that
corresponds to y.
int x1 (in) Left edge of the region that
needs redisplay. Only pixels at
or to the right of this
coordinate need to be
redisplayed.
int y1 (in) Top edge of the region that needs
redisplay. Only pixels at or
below this coordinate need to be
redisplayed.
int x2 (in) Right edge of the region that
needs redisplay. Only pixels to
the left of this coordinate need
to be redisplayed.
int y2 (in) Bottom edge of the region that
needs redisplay. Only pixels
above this coordinate need to be
redisplayed.
DESCRIPTION
These procedures are called by canvas type managers to perform various
utility functions.
Tk_CanvasTkwin returns the Tk_Window associated with a particular canvas.
Tk_CanvasGetCoord translates a string specification of a coordinate (such
as 2p or 1.6c) into a double-precision canvas coordinate. If string is a
valid coordinate description then Tk_CanvasGetCoord stores the
corresponding canvas coordinate at *doublePtr and returns TCL_OK.
Otherwise it stores an error message in interp->result and returns
TCL_ERROR.
Tk_CanvasDrawableCoords is called by type managers during redisplay to
compute where to draw things. Given x and y coordinates in the space of
the canvas, Tk_CanvasDrawableCoords computes the corresponding pixel in
the drawable that is currently being used for redisplay; it returns those
Page 2
Tk_CanvasTkwin(3Tk)Tk_CanvasTkwin(3Tk)
coordinates in *drawableXPtr and *drawableYPtr. This procedure should
not be invoked except during redisplay.
Tk_CanvasSetStippleOrigin is also used during redisplay. It sets the
stipple origin in gc so that stipples drawn with gc in the current
offscreen pixmap will line up with stipples drawn with origin (0,0) in
the canvas's actual window. Tk_CanvasSetStippleOrigin is needed in order
to guarantee that stipple patterns line up properly when the canvas is
redisplayed in small pieces. Redisplays are carried out in double-
buffered fashion where a piece of the canvas is redrawn in an offscreen
pixmap and then copied back onto the screen. In this approach the
stipple origins in graphics contexts need to be adjusted during each
redisplay to compensate for the position of the off-screen pixmap
relative to the window. If an item is being drawn with stipples, its
type manager typically calls Tk_CanvasSetStippleOrigin just before using
gc to draw something; after it is finished drawing, the type manager
calls XSetTSOrigin to restore the origin in gc back to (0,0) (the restore
is needed because graphics contexts are shared, so they cannot be
modified permanently).
Tk_CanvasWindowCoords is similar to Tk_CanvasDrawableCoords except that
it returns coordinates in the canvas's window on the screen, instead of
coordinates in an off-screen pixmap.
Tk_CanvasEventuallyRedraw may be invoked by a type manager to inform Tk
that a portion of a canvas needs to be redrawn. The x1, y1, x2, and y2
arguments specify the region that needs to be redrawn, in canvas
coordinates. Type managers rarely need to invoke
Tk_CanvasEventuallyRedraw, since Tk can normally figure out when an item
has changed and make the redisplay request on its behalf (this happens,
for example whenever Tk calls a configureProc or scaleProc). The only
time that a type manager needs to call Tk_CanvasEventuallyRedraw is if an
item has changed on its own without being invoked through one of the
procedures in its Tk_ItemType; this could happen, for example, in an
image item if the image is modified using image commands.
KEYWORDS
canvas, focus, item type, redisplay, selection, type manager
Page 3
