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 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 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_CanvasEventu-
       allyRedraw, 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 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 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									4.1							 Tk_CanvasTkwin(3)