NAME

       Tk_CanvasTkwin,   Tk_CanvasGetCoord,  Tk_CanvasDrawableCo­
       ords,  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 iden­
                                               tifies   a  canvas
                                               widget.

       Tcl_Interp    *interp         (in/out)  Interpreter to use
                                               for  error report­
                                               ing.

       char          *string         (in)      Textual   descrip­
                                               tion  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.
                                               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 coordi­
                                               nate 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 loca­
                                               tion in  which  to
                                               store  the  screen
                                               coordinate in  the
                                               canvas window that
                                               corresponds to  x.

       short         *screenYPtr     (out)     Points  to a loca­
                                               tion 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  redis­
                                               played.

       int           x2              (in)      Right  edge of the
                                               region that  needs
                                               of this coordinate
                                               need to be  redis­
                                               played.

       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 correspond­
       ing 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_CanvasDrawable­
       Coords  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  redis­
       play.

       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
       (0,0) (the restore is needed because graphics contexts are
       shared, so they cannot be modified permanently).

       Tk_CanvasWindowCoords  is  similar to Tk_CanvasDrawableCo­
       ords 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_CanvasEventuallyRe­
       draw,  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 proce­
       dures  in its Tk_ItemType; this could happen, for example,
       in an image item if the image is modified using image com­
       mands.

       Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc are pro­
       cedures that handle the -tags  option  for  canvas  items.
       The  code of a canvas type manager won't call these proce­
       dures 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  man­
       ager