Tk_CanvasTkwin(3) Tk Library Procedures Tk_CanvasTkwin(3)

____________________________________________________________________________

NAME

Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords,
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 identifies a
canvas widget.

Tcl_Interp *interp (in/out) Interpreter to use for error
reporting.

const 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.

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 the interpreter
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 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.

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

static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
Tk_CanvasTagsPrintProc, NULL
};

static const Tk_ConfigSpec configSpecs[] = {
...
{TK_CONFIG_CUSTOM, "-tags", NULL, NULL,
NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
...
};

KEYWORDS

canvas, focus, item type, redisplay, selection, type manager

Tk 4.1 Tk_CanvasTkwin(3)