Provided by: tk8.5-doc_8.5.19-3_all bug

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_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 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