1Tk_CanvasTkwin(3) Tk Library Procedures Tk_CanvasTkwin(3)
2______________________________________________________________________________
6
8 Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_Canvas‐
9 SetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw,
10 Tk_CanvasTagsOption - utility procedures for canvas type managers
11
13 #include <tk.h>
14 Tk_Window
16 Tk_CanvasTkwin(canvas)
17 int
19 Tk_CanvasGetCoord(interp, canvas, string, doublePtr)
20 Tk_CanvasDrawableCoords(canvas, x, y, drawableXPtr, drawableYPtr)
22 Tk_CanvasSetStippleOrigin(canvas, gc)
24 Tk_CanvasWindowCoords(canvas, x, y, screenXPtr, screenYPtr)
26 Tk_CanvasEventuallyRedraw(canvas, x1, y1, x2, y2)
28 Tk_OptionParseProc *Tk_CanvasTagsParseProc;
30 Tk_OptionPrintProc *Tk_CanvasTagsPrintProc;
32
34 Tk_Canvas canvas (in) A token that identifies a can‐
35 vas widget.
36 Tcl_Interp *interp (in/out) Interpreter to use for error
38 reporting.
39 const char *string (in) Textual description of a canvas
41 coordinate.
42 double *doublePtr (out) Points to place to store a con‐
44 verted coordinate.
45 double x (in) An x coordinate in the space of
47 the canvas.
48 double y (in) A y coordinate in the space of
50 the canvas.
51 short *drawableXPtr (out) Pointer to a location in which
53 to store an x coordinate in the
54 space of the drawable currently
55 being used to redisplay the
56 canvas.
57 short *drawableYPtr (out) Pointer to a location in which
59 to store a y coordinate in the
60 space of the drawable currently
61 being used to redisplay the
62 canvas.
63 GC gc (out) Graphics context to modify.
65 short *screenXPtr (out) Points to a location in which
67 to store the screen coordinate
68 in the canvas window that cor‐
69 responds to x.
70 short *screenYPtr (out) Points to a location in which
72 to store the screen coordinate
73 in the canvas window that cor‐
74 responds to y.
75 int x1 (in) Left edge of the region that
77 needs redisplay. Only pixels
78 at or to the right of this
79 coordinate need to be redis‐
80 played.
81 int y1 (in) Top edge of the region that
83 needs redisplay. Only pixels
84 at or below this coordinate
85 need to be redisplayed.
86 int x2 (in) Right edge of the region that
88 needs redisplay. Only pixels
89 to the left of this coordinate
90 need to be redisplayed.
91 int y2 (in) Bottom edge of the region that
93 needs redisplay. Only pixels
94 above this coordinate need to
95 be redisplayed.
96_________________________________________________________________
97
100 These procedures are called by canvas type managers to perform various
101 utility functions.
102 Tk_CanvasTkwin returns the Tk_Window associated with a particular can‐
104 vas.
105 Tk_CanvasGetCoord translates a string specification of a coordinate
107 (such as 2p or 1.6c) into a double-precision canvas coordinate. If
108 string is a valid coordinate description then Tk_CanvasGetCoord stores
109 the corresponding canvas coordinate at *doublePtr and returns TCL_OK.
110 Otherwise it stores an error message in interp->result and returns
111 TCL_ERROR.
112 Tk_CanvasDrawableCoords is called by type managers during redisplay to
114 compute where to draw things. Given x and y coordinates in the space
115 of the canvas, Tk_CanvasDrawableCoords computes the corresponding pixel
116 in the drawable that is currently being used for redisplay; it returns
117 those coordinates in *drawableXPtr and *drawableYPtr. This procedure
118 should not be invoked except during redisplay.
119 Tk_CanvasSetStippleOrigin is also used during redisplay. It sets the
121 stipple origin in gc so that stipples drawn with gc in the current off‐
122 screen pixmap will line up with stipples drawn with origin (0,0) in the
123 canvas's actual window. Tk_CanvasSetStippleOrigin is needed in order
124 to guarantee that stipple patterns line up properly when the canvas is
125 redisplayed in small pieces. Redisplays are carried out in double-
126 buffered fashion where a piece of the canvas is redrawn in an offscreen
127 pixmap and then copied back onto the screen. In this approach the
128 stipple origins in graphics contexts need to be adjusted during each
129 redisplay to compensate for the position of the off-screen pixmap rela‐
130 tive to the window. If an item is being drawn with stipples, its type
131 manager typically calls Tk_CanvasSetStippleOrigin just before using gc
132 to draw something; after it is finished drawing, the type manager
133 calls XSetTSOrigin to restore the origin in gc back to (0,0) (the
134 restore is needed because graphics contexts are shared, so they cannot
135 be modified permanently).
136 Tk_CanvasWindowCoords is similar to Tk_CanvasDrawableCoords except that
138 it returns coordinates in the canvas's window on the screen, instead of
139 coordinates in an off-screen pixmap.
140 Tk_CanvasEventuallyRedraw may be invoked by a type manager to inform Tk
142 that a portion of a canvas needs to be redrawn. The x1, y1, x2, and y2
143 arguments specify the region that needs to be redrawn, in canvas coor‐
144 dinates. Type managers rarely need to invoke Tk_CanvasEventuallyRe‐
145 draw, since Tk can normally figure out when an item has changed and
146 make the redisplay request on its behalf (this happens, for example
147 whenever Tk calls a configureProc or scaleProc). The only time that a
148 type manager needs to call Tk_CanvasEventuallyRedraw is if an item has
149 changed on its own without being invoked through one of the procedures
150 in its Tk_ItemType; this could happen, for example, in an image item if
151 the image is modified using image commands.
152 Tk_CanvasTagsParseProc and Tk_CanvasTagsPrintProc are procedures that
154 handle the -tags option for canvas items. The code of a canvas type
155 manager will not call these procedures directly, but will use their
156 addresses to create a Tk_CustomOption structure for the -tags option.
157 The code typically looks like this:
158 static Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
159 Tk_CanvasTagsPrintProc, (ClientData) NULL
160 };
161 static Tk_ConfigSpec configSpecs[] = {
163 ...
164 {TK_CONFIG_CUSTOM, "-tags", (char *) NULL, (char *) NULL,
165 (char *) NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
166 ...
167 };
168
171 canvas, focus, item type, redisplay, selection, type manager
172Tk 4.1 Tk_CanvasTkwin(3)