diff options
Diffstat (limited to 'doc/CanvTkwin.3')
| -rw-r--r-- | doc/CanvTkwin.3 | 161 |
1 files changed, 161 insertions, 0 deletions
diff --git a/doc/CanvTkwin.3 b/doc/CanvTkwin.3 new file mode 100644 index 0000000..b421b5e --- /dev/null +++ b/doc/CanvTkwin.3 @@ -0,0 +1,161 @@ +'\" +'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) CanvTkwin.3 1.8 96/08/27 13:21:54 +'\" +.so man.macros +.TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures" +.BS +.SH NAME +Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers +.SH SYNOPSIS +.nf +\fB#include <tk.h>\fR +.sp +Tk_Window +\fBTk_CanvasTkwin\fR(\fIcanvas\fR) +.sp +int +\fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR) +.sp +\fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR) +.sp +\fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR) +.sp +\fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR) +.sp +\fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR) +.sp +Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR; +.sp +Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR; +.SH ARGUMENTS +.AS Tk_ItemType *drawableXPtr +.AP Tk_Canvas canvas in +A token that identifies a canvas widget. +.AP Tcl_Interp *interp in/out +Interpreter to use for error reporting. +.AP char *string in +Textual description of a canvas coordinate. +.AP double *doublePtr out +Points to place to store a converted coordinate. +.AP double x in +An x coordinate in the space of the canvas. +.AP double y in +A y coordinate in the space of the canvas. +.AP 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. +.AP 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. +.AP GC gc out +Graphics context to modify. +.AP short *screenXPtr out +Points to a location in which to store the screen coordinate in the +canvas window that corresponds to \fIx\fR. +.AP short *screenYPtr out +Points to a location in which to store the screen coordinate in the +canvas window that corresponds to \fIy\fR. +.AP 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. +.AP int y1 in +Top edge of the region that needs redisplay. Only pixels at or below +this coordinate need to be redisplayed. +.AP int x2 in +Right edge of the region that needs redisplay. Only pixels to +the left of this coordinate need to be redisplayed. +.AP int y2 in +Bottom edge of the region that needs redisplay. Only pixels above +this coordinate need to be redisplayed. +.BE + +.SH DESCRIPTION +.PP +These procedures are called by canvas type managers to perform various +utility functions. +.PP +\fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular +canvas. +.PP +\fBTk_CanvasGetCoord\fR translates a string specification of a +coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision +canvas coordinate. +If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR +stores the corresponding canvas coordinate at *\fIdoublePtr\fR +and returns TCL_OK. +Otherwise it stores an error message in \fIinterp->result\fR and +returns TCL_ERROR. +.PP +\fBTk_CanvasDrawableCoords\fR is called by type managers during +redisplay to compute where to draw things. +Given \fIx\fR and \fIy\fR coordinates in the space of the +canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding +pixel in the drawable that is currently being used for redisplay; +it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR. +This procedure should not be invoked except during redisplay. +.PP +\fBTk_CanvasSetStippleOrigin\fR is also used during redisplay. +It sets the stipple origin in \fIgc\fR so that stipples drawn +with \fIgc\fR in the current offscreen pixmap will line up +with stipples drawn with origin (0,0) in the canvas's actual +window. +\fBTk_CanvasSetStippleOrigin\fR 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 \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR +to draw something; after it is finished drawing, the type manager +calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0) +(the restore is needed because graphics contexts are shared, so +they cannot be modified permanently). +.PP +\fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR +except that it returns coordinates in the canvas's window on the +screen, instead of coordinates in an off-screen pixmap. +.PP +\fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager +to inform Tk that a portion of a canvas needs to be redrawn. +The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments +specify the region that needs to be redrawn, in canvas coordinates. +Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR, +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 \fIconfigureProc\fR or \fIscaleProc\fR). +The only time that a type manager needs to call +\fBTk_CanvasEventuallyRedraw\fR 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. +.PP +\fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are +procedures that handle the \fB\-tags\fR option for canvas items. +The code of a canvas type manager won't call these procedures +directly, but will use their addresses to create a \fBTk_CustomOption\fR +structure for the \fB\-tags\fR option. The code typically looks +like this: +.CS +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}, + ... +}; +.CE + +.SH KEYWORDS +canvas, focus, item type, redisplay, selection, type manager |