NAME
TkCanvasTkwin, TkCanvasGetCoord, TkCanvasDrawableCoords, TkCanvas-
SetStippleOrigin, TkCanvasWindowCoords, TkCanvasEventuallyRedraw,TkCanvasTagsOption - utility procedures for canvas type managers
SYNOPSIS
##iinncclluuddee <
TkWindow TTkkCCaannvvaassTTkkwwiinn(canvas) int TTkkCCaannvvaassGGeettCCoooorrdd(interp, canvas, string, doublePtr) TTkkCCaannvvaassDDrraawwaabblleeCCoooorrddss(canvas, x, y, drawableXPtr, drawableYPtr) TTkkCCaannvvaassSSeettSSttiipppplleeOOrriiggiinn(canvas, gc) TTkkCCaannvvaassWWiinnddoowwCCoooorrddss(canvas, x, y, screenXPtr, screenYPtr) TTkkCCaannvvaassEEvveennttuuaallllyyRReeddrraaww(canvas, x1, y1, x2, y2) TkOptionParseProc *TTkkCCaannvvaassTTaaggssPPaarrsseePPrroocc; TkOptionPrintProc *TTkkCCaannvvaassTTaaggssPPrriinnttPPrroocc; AARRGGUUMMEENNTTSS> TkCanvas canvas (in) A token that identifies a can-
vas widget. TclInterp *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 con-
verted 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 coordinatein the canvas window that cor-
responds to x. short *screenYPtr (out) Points to a location in which to store the screen coordinatein the canvas window that cor-
responds to y. int x1 (in) Left edge of the region that needs redisplay. Only pixels at or to the right of thiscoordinate need to be redis-
played. 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.TTkkCCaannvvaassTTkkwwiinn returns the TkWindow associated with a particular can-
vas. TTkkCCaannvvaassGGeettCCoooorrdd translates a string specification of a coordinate(such as 22pp or 11..66cc) into a double-precision canvas coordinate. If
string is a valid coordinate description then TTkkCCaannvvaassGGeettCCoooorrdd stores the corresponding canvas coordinate at *doublePtr and returns TCLOK.Otherwise it stores an error message in interp->result and returns
TCLERROR.
TTkkCCaannvvaassDDrraawwaabblleeCCoooorrddss is called by type managers during redisplay to compute where to draw things. Given x and y coordinates in the space of the canvas, TTkkCCaannvvaassDDrraawwaabblleeCCoooorrddss 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. TTkkCCaannvvaassSSeettSSttiipppplleeOOrriiggiinn is also used during redisplay. It sets thestipple origin in gc so that stipples drawn with gc in the current off-
screen pixmap will line up with stipples drawn with origin (0,0) in the canvas's actual window. TTkkCCaannvvaassSSeettSSttiipppplleeOOrriiggiinn is needed in order to guarantee that stipple patterns line up properly when the canvas isredisplayed 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 eachredisplay to compensate for the position of the off-screen pixmap rela-
tive to the window. If an item is being drawn with stipples, its type manager typically calls TTkkCCaannvvaassSSeettSSttiipppplleeOOrriiggiinn just before using gc to draw something; after it is finished drawing, the type manager calls XXSSeettTTSSOOrriiggiinn 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). TTkkCCaannvvaassWWiinnddoowwCCoooorrddss is similar to TTkkCCaannvvaassDDrraawwaabblleeCCoooorrddss except that it returns coordinates in the canvas's window on the screen, instead ofcoordinates in an off-screen pixmap.
TTkkCCaannvvaassEEvveennttuuaallllyyRReeddrraaww 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 y2arguments specify the region that needs to be redrawn, in canvas coor-
dinates. Type managers rarely need to invoke TTkkCCaannvvaassEEvveennttuuaallllyyRRee-
ddrraaww, 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 TTkkCCaannvvaassEEvveennttuuaallllyyRReeddrraaww is if an item has changed on its own without being invoked through one of the procedures in its TkItemType; this could happen, for example, in an image item if the image is modified using image commands. TTkkCCaannvvaassTTaaggssPPaarrsseePPrroocc and TTkkCCaannvvaassTTaaggssPPrriinnttPPrroocc are procedures thathandle the -ttaaggss option for canvas items. The code of a canvas type
manager won't call these procedures directly, but will use theirdrse t cet a TkCustomOption tutr fr h -tags pin
The code typically looks like this: static TkCustomOption tagsOption = {TkCanvasTagsParseProc, TkCanvasTagsPrintProc, (ClientData) NULL }; static TkConfigSpec configSpecs[] = { ...{TKCONFIGCUSTOM, "-tags", (char *) NULL, (char *) NULL,
(char *) NULL, 0, TKCONFIGNULLOK, &tagsOption}, ... }; KKEEYYWWOORRDDSS canvas, focus, item type, redisplay, selection, type manager Tk 4.1 TkCanvasTkwin(3)