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
79                                               coordinate 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
98

DESCRIPTION

100       These procedures are called by canvas type managers to perform  various
101       utility functions.
102
103       Tk_CanvasTkwin  returns the Tk_Window associated with a particular can‐
104       vas.
105
106       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
113       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
120       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
137       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
141       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
153       Tk_CanvasTagsParseProc  and  Tk_CanvasTagsPrintProc are procedures that
154       handle the -tags option for canvas items.  The code of  a  canvas  type
155       manager  won't  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
162              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
169

KEYWORDS

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