Tk_CanvasTkwin(3)
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 identi-
fies a canvas
widget.
Tcl_Interp *interp (in/out) Interpreter to use
for error reporting.
const char *string (in) Textual description
of a canvas coordi-
nate.
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.
Tk Last change: 4.1 1
Tk_CanvasTkwin(3) Tk Library Procedures Tk_CanvasTkwin(3)
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 coordinate
in the space of the
drawable currently
being used to
redisplay the can-
vas.
GC gc (out) Graphics context to
modify.
short *screenXPtr (out) Points to a location
in which to store
the screen coordi-
nate in the canvas
window that
corresponds to x.
short *screenYPtr (out) Points to a location
in which to store
the screen coordi-
nate 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 coor-
dinate 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
Tk Last change: 4.1 2
Tk_CanvasTkwin(3) Tk Library Procedures Tk_CanvasTkwin(3)
redisplay.
Only pixels to the
left of this coordi-
nate 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 per-
form various utility functions.
Tk_CanvasTkwin returns the Tk_Window associated with a par-
ticular canvas.
Tk_CanvasGetCoord translates a string specification of a
coordinate (such as 2p or 1.6c) into a double-precision can-
vas coordinate. If string is a valid coordinate description
then Tk_CanvasGetCoord stores the corresponding canvas coor-
dinate 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 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 com-
pensate for the position of the off-screen pixmap relative
to the window. If an item is being drawn with stipples, its
Tk Last change: 4.1 3
Tk_CanvasTkwin(3) Tk Library Procedures Tk_CanvasTkwin(3)
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 exam-
ple 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 pro-
cedures 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 Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
Tk_CanvasTagsPrintProc, (ClientData) NULL
};
static Tk_ConfigSpec configSpecs[] = {
...
{TK_CONFIG_CUSTOM, "-tags", (char *) NULL, (char *) NULL,
(char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
...
};
KEYWORDS
canvas, focus, item type, redisplay, selection, type manager
Tk Last change: 4.1 4
Man(1) output converted with
man2html