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