1Tk_CanvasTkwin(3)            Tk Library Procedures           Tk_CanvasTkwin(3)
2
3
4
5______________________________________________________________________________
6

NAME

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

SYNOPSIS

13       #include <tk.h>
14
15       Tk_Window
16       Tk_CanvasTkwin(canvas)
17
18       int
19       Tk_CanvasGetCoord(interp, canvas, string, doublePtr)
20
21       Tk_CanvasDrawableCoords(canvas, x, y, drawableXPtr, drawableYPtr)
22
23       Tk_CanvasSetStippleOrigin(canvas, gc)
24
25       Tk_CanvasWindowCoords(canvas, x, y, screenXPtr, screenYPtr)
26
27       Tk_CanvasEventuallyRedraw(canvas, x1, y1, x2, y2)
28
29       Tk_OptionParseProc *Tk_CanvasTagsParseProc;
30
31       Tk_OptionPrintProc *Tk_CanvasTagsPrintProc;
32

ARGUMENTS

34       Tk_Canvas canvas (in)                   A  token that identifies a can‐
35                                               vas widget.
36
37       Tcl_Interp *interp (in/out)             Interpreter to  use  for  error
38                                               reporting.
39
40       const char *string (in)                 Textual description of a canvas
41                                               coordinate.
42
43       double *doublePtr (out)                 Points to place to store a con‐
44                                               verted coordinate.
45
46       double x (in)                           An x coordinate in the space of
47                                               the canvas.
48
49       double y (in)                           A y coordinate in the space  of
50                                               the canvas.
51
52       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
58       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
64       GC gc (out)                             Graphics context to modify.
65
66       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
71       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
76       int x1 (in)                             Left  edge  of  the region that
77                                               needs redisplay.   Only  pixels
78                                               at  or to the right of this co‐
79                                               ordinate  need  to  be   redis‐
80                                               played.
81
82       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
87       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
92       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

DESCRIPTION

99       These procedures are called by canvas type managers to perform  various
100       utility functions.
101
102       Tk_CanvasTkwin  returns the Tk_Window associated with a particular can‐
103       vas.
104
105       Tk_CanvasGetCoord translates a string  specification  of  a  coordinate
106       (such  as  2p  or  1.6c) into a double-precision canvas coordinate.  If
107       string is a valid coordinate description then Tk_CanvasGetCoord  stores
108       the  corresponding  canvas coordinate at *doublePtr and returns TCL_OK.
109       Otherwise it stores an error message in the interpreter result and  re‐
110       turns TCL_ERROR.
111
112       Tk_CanvasDrawableCoords  is called by type managers during redisplay to
113       compute where to draw things.  Given x and y coordinates in  the  space
114       of the canvas, Tk_CanvasDrawableCoords computes the corresponding pixel
115       in the drawable that is currently being used for redisplay; it  returns
116       those  coordinates  in *drawableXPtr and *drawableYPtr.  This procedure
117       should not be invoked except during redisplay.
118
119       Tk_CanvasSetStippleOrigin is also used during redisplay.  It  sets  the
120       stipple origin in gc so that stipples drawn with gc in the current off‐
121       screen pixmap will line up with stipples drawn with origin (0,0) in the
122       canvas's  actual  window.  Tk_CanvasSetStippleOrigin is needed in order
123       to guarantee that stipple patterns line up properly when the canvas  is
124       redisplayed  in  small  pieces.   Redisplays are carried out in double-
125       buffered fashion where a piece of the canvas is redrawn in an offscreen
126       pixmap  and  then  copied  back  onto the screen.  In this approach the
127       stipple origins in graphics contexts need to be  adjusted  during  each
128       redisplay to compensate for the position of the off-screen pixmap rela‐
129       tive to the window.  If an item is being drawn with stipples, its  type
130       manager  typically calls Tk_CanvasSetStippleOrigin just before using gc
131       to draw something;  after it is  finished  drawing,  the  type  manager
132       calls  XSetTSOrigin  to restore the origin in gc back to (0,0) (the re‐
133       store is needed because graphics contexts are shared, so they cannot be
134       modified permanently).
135
136       Tk_CanvasWindowCoords is similar to Tk_CanvasDrawableCoords except that
137       it returns coordinates in the canvas's window on the screen, instead of
138       coordinates in an off-screen pixmap.
139
140       Tk_CanvasEventuallyRedraw may be invoked by a type manager to inform Tk
141       that a portion of a canvas needs to be redrawn.  The x1, y1, x2, and y2
142       arguments  specify the region that needs to be redrawn, in canvas coor‐
143       dinates.  Type managers rarely need  to  invoke  Tk_CanvasEventuallyRe‐
144       draw,  since  Tk  can  normally figure out when an item has changed and
145       make the redisplay request on its behalf  (this  happens,  for  example
146       whenever  Tk calls a configureProc or scaleProc).  The only time that a
147       type manager needs to call Tk_CanvasEventuallyRedraw is if an item  has
148       changed  on its own without being invoked through one of the procedures
149       in its Tk_ItemType; this could happen, for example, in an image item if
150       the image is modified using image commands.
151
152       Tk_CanvasTagsParseProc  and  Tk_CanvasTagsPrintProc are procedures that
153       handle the -tags option for canvas items.  The code of  a  canvas  type
154       manager will not call these procedures directly, but will use their ad‐
155       dresses to create a Tk_CustomOption structure  for  the  -tags  option.
156       The code typically looks like this:
157
158              static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
159                  Tk_CanvasTagsPrintProc, NULL
160              };
161
162              static const Tk_ConfigSpec configSpecs[] = {
163                  ...
164                  {TK_CONFIG_CUSTOM, "-tags", NULL, NULL,
165                      NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
166                  ...
167              };
168

KEYWORDS

170       canvas, focus, item type, redisplay, selection, type manager
171
172
173
174Tk                                    4.1                    Tk_CanvasTkwin(3)
Impressum