1# Copyright (c) 1994-1996 Sun Microsystems, Inc. 2# See the file "license.terms" for information on usage and redistribution 3# of this file, and for a DISCLAIMER OF ALL WARRANTIES. 4# 5# 6 7=head1 NAME 8 9Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption - utility procedures for canvas type managers 10 11=for category C Programming 12 13=head1 SYNOPSIS 14 15B<#include E<lt>tk.hE<gt>> 16 17Tk_Window 18B<Tk_CanvasTkwin>(I<canvas>) 19 20int 21B<Tk_CanvasGetCoord>(I<interp, canvas, string, doublePtr>) 22 23B<Tk_CanvasDrawableCoords>(I<canvas, x, y, drawableXPtr, drawableYPtr>) 24 25B<Tk_CanvasSetStippleOrigin>(I<canvas, gc>) 26 27B<Tk_CanvasWindowCoords>(I<canvas, x, y, screenXPtr, screenYPtr>) 28 29B<Tk_CanvasEventuallyRedraw>(I<canvas, x1, y1, x2, y2>) 30 31Tk_OptionParseProc *B<Tk_CanvasTagsParseProc>; 32 33Tk_OptionPrintProc *B<Tk_CanvasTagsPrintProc>; 34 35=head1 ARGUMENTS 36 37=over 4 38 39=item Tk_Canvas canvas (in) 40 41A token that identifies a canvas widget. 42 43=item Tcl_Interp *interp (in/out) 44 45Interpreter to use for error reporting. 46 47=item char *string (in) 48 49Textual description of a canvas coordinate. 50 51=item double *doublePtr (out) 52 53Points to place to store a converted coordinate. 54 55=item double x (in) 56 57An x coordinate in the space of the canvas. 58 59=item double y (in) 60 61A y coordinate in the space of the canvas. 62 63=item short *drawableXPtr (out) 64 65Pointer to a location in which to store an x coordinate in the space 66of the drawable currently being used to redisplay the canvas. 67 68=item short *drawableYPtr (out) 69 70Pointer to a location in which to store a y coordinate in the space 71of the drawable currently being used to redisplay the canvas. 72 73=item GC gc (out) 74 75Graphics context to modify. 76 77=item short *screenXPtr (out) 78 79Points to a location in which to store the screen coordinate in the 80canvas window that corresponds to I<x>. 81 82=item short *screenYPtr (out) 83 84Points to a location in which to store the screen coordinate in the 85canvas window that corresponds to I<y>. 86 87=item int x1 (in) 88 89Left edge of the region that needs redisplay. Only pixels at or to 90the right of this coordinate need to be redisplayed. 91 92=item int y1 (in) 93 94Top edge of the region that needs redisplay. Only pixels at or below 95this coordinate need to be redisplayed. 96 97=item int x2 (in) 98 99Right edge of the region that needs redisplay. Only pixels to 100the left of this coordinate need to be redisplayed. 101 102=item int y2 (in) 103 104Bottom edge of the region that needs redisplay. Only pixels above 105this coordinate need to be redisplayed. 106 107=back 108 109=head1 DESCRIPTION 110 111These procedures are called by canvas type managers to perform various 112utility functions. 113 114B<Tk_CanvasTkwin> returns the Tk_Window associated with a particular 115canvas. 116 117B<Tk_CanvasGetCoord> translates a string specification of a 118coordinate (such as B<2p> or B<1.6c>) into a double-precision 119canvas coordinate. 120If I<string> is a valid coordinate description then B<Tk_CanvasGetCoord> 121stores the corresponding canvas coordinate at *I<doublePtr> 122and returns TCL_OK. 123Otherwise it stores an error message in I<interp-E<gt>result> and 124returns TCL_ERROR. 125 126B<Tk_CanvasDrawableCoords> is called by type managers during 127redisplay to compute where to draw things. 128Given I<x> and I<y> coordinates in the space of the 129canvas, B<Tk_CanvasDrawableCoords> computes the corresponding 130pixel in the drawable that is currently being used for redisplay; 131it returns those coordinates in *I<drawableXPtr> and *I<drawableYPtr>. 132This procedure should not be invoked except during redisplay. 133 134B<Tk_CanvasSetStippleOrigin> is also used during redisplay. 135It sets the stipple origin in I<gc> so that stipples drawn 136with I<gc> in the current offscreen pixmap will line up 137with stipples drawn with origin (0,0) in the canvas's actual 138window. 139B<Tk_CanvasSetStippleOrigin> is needed in order to guarantee 140that stipple patterns line up properly when the canvas is 141redisplayed in small pieces. 142Redisplays are carried out in double-buffered fashion where a 143piece of the canvas is redrawn in an offscreen pixmap and then 144copied back onto the screen. 145In this approach the stipple origins in graphics contexts need to 146be adjusted during each redisplay to compensate for the position 147of the off-screen pixmap relative to the window. 148If an item is being drawn with stipples, its type manager typically 149calls B<Tk_CanvasSetStippleOrigin> just before using I<gc> 150to draw something; after it is finished drawing, the type manager 151calls B<XSetTSOrigin> to restore the origin in I<gc> back to (0,0) 152(the restore is needed because graphics contexts are shared, so 153they cannot be modified permanently). 154 155B<Tk_CanvasWindowCoords> is similar to B<Tk_CanvasDrawableCoords> 156except that it returns coordinates in the canvas's window on the 157screen, instead of coordinates in an off-screen pixmap. 158 159B<Tk_CanvasEventuallyRedraw> may be invoked by a type manager 160to inform Tk that a portion of a canvas needs to be redrawn. 161The I<x1>, I<y1>, I<x2>, and I<y2> arguments 162specify the region that needs to be redrawn, in canvas coordinates. 163Type managers rarely need to invoke B<Tk_CanvasEventuallyRedraw>, 164since Tk can normally figure out when an item has changed and make 165the redisplay request on its behalf (this happens, for example 166whenever Tk calls a I<configureProc> or I<scaleProc>). 167The only time that a type manager needs to call 168B<Tk_CanvasEventuallyRedraw> is if an item has changed on its own 169without being invoked through one of the procedures in its Tk_ItemType; 170this could happen, for example, in an image item if the image is 171modified using image commands. 172 173B<Tk_CanvasTagsParseProc> and B<Tk_CanvasTagsPrintProc> are 174procedures that handle the B<-tags> option for canvas items. 175The code of a canvas type manager won't call these procedures 176directly, but will use their addresses to create a B<Tk_CustomOption> 177structure for the B<-tags> option. The code typically looks 178like this: 179 180 static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc, 181 Tk_CanvasTagsPrintProc, (ClientData) NULL 182 }; 183 184 static Tk_ConfigSpec configSpecs[] = { 185 ... 186 {TK_CONFIG_CUSTOM, "-tags", (char *) NULL, (char *) NULL, 187 (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption}, 188 ... 189 }; 190 191=head1 KEYWORDS 192 193canvas, focus, item type, redisplay, selection, type manager 194