Tk_CanvasTkwin(3) Tk Library Procedures Tk_CanvasTkwin(3) 







Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords,
    Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw,
    Tk_CanvasTagsOption - utility procedures for canvas type managers








#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;









  
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.
    
    

    

  










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},


    ...
};












canvas, focus, item type, redisplay, selection, type manager







  

    4.1
    Tk