tk_canvastkwin(3)

NAME

Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCo
ords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords,
Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption - 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)
Tk_OptionParseProc *Tk_CanvasTagsParseProc;
Tk_OptionPrintProc *Tk_CanvasTagsPrintProc;

ARGUMENTS

Tk_Canvas canvas (in) A token that iden

tifies a canvas
widget.

Tcl_Interp *interp (in/out) Interpreter to use

for error report
ing.

CONST char *string (in) Textual descrip

tion 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 loca

tion in which to
store an x coordi
nate in the space
of the drawable
currently being
used to redisplay
the canvas.

short *drawableYPtr (out) Pointer to a loca

tion in which to
store a y coordi
nate in the space
of the drawable
currently being
used to redisplay
the canvas.

GC gc (out) Graphics context

to modify.

short *screenXPtr (out) Points to a loca

tion in which to
store the screen
coordinate in the
canvas window that
corresponds to x.

short *screenYPtr (out) Points to a loca

tion 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 redis
played.

int x2 (in) Right edge of the

region that needs
redisplay. Only
pixels to the left
of this coordinate
need to be redis
played.

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 correspond ing 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_CanvasDrawable Coords computes the corresponding pixel in the drawable that is currently being used for redisplay; it returns
those coordinates in *drawableXPtr and *drawableYPtr. This procedure should not be invoked except during redis
play.

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 offscreen 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_CanvasDrawableCo ords except that it returns coordinates in the canvas's
window on the screen, instead of coordinates in an offscreen 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_CanvasEventuallyRe draw, 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 proce
dures in its Tk_ItemType; this could happen, for example,
in an image item if the image is modified using image com
mands.

Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc are pro cedures that handle the -tags option for canvas items.
The code of a canvas type manager won't call these proce
dures directly, but will use their addresses to create a
Tk_CustomOption structure for the -tags option. The code typically looks like this:

static Tk_CustomOption tagsOption = {Tk_Can

vasTagsParseProc,

Tk_CanvasTagsPrintProc, (ClientData) NULL

};

static Tk_ConfigSpec configSpecs[] = {

...
{TK_CONFIG_CUSTOM, "-tags", (char *) NULL, (char

*) NULL,

(char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOp

tion},

...

};

KEYWORDS

canvas, focus, item type, redisplay, selection, type man
ager

Tk 4.1 Tk_CanvasTkwin(3)