2 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 .TH Tk_CanvasTkwin 3 4.1 Tk "Tk Library Procedures"
8 .\" The -*- nroff -*- definitions below are for supplemental macros used
9 .\" in Tcl/Tk manual entries.
11 .\" .AP type name in/out ?indent?
12 .\" Start paragraph describing an argument to a library procedure.
13 .\" type is type of argument (int, etc.), in/out is either "in", "out",
14 .\" or "in/out" to describe whether procedure reads or modifies arg,
15 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
16 .\" needed; use .AS below instead)
19 .\" Give maximum sizes of arguments for setting tab stops. Type and
20 .\" name are examples of largest possible arguments that will be passed
21 .\" to .AP later. If args are omitted, default tab stops are used.
24 .\" Start box enclosure. From here until next .BE, everything will be
25 .\" enclosed in one large box.
28 .\" End of box enclosure.
31 .\" Begin code excerpt.
36 .\" .VS ?version? ?br?
37 .\" Begin vertical sidebar, for use in marking newly-changed parts
38 .\" of man pages. The first argument is ignored and used for recording
39 .\" the version when the .VS was added, so that the sidebars can be
40 .\" found and removed when they reach a certain age. If another argument
41 .\" is present, then a line break is forced before starting the sidebar.
44 .\" End of vertical sidebar.
47 .\" Begin an indented unfilled display.
50 .\" End of indented unfilled display.
53 .\" Start of list of standard options for a Tk widget. The manpage
54 .\" argument defines where to look up the standard options; if
55 .\" omitted, defaults to "options". The options follow on successive
56 .\" lines, in three columns separated by tabs.
59 .\" End of list of standard options for a Tk widget.
61 .\" .OP cmdName dbName dbClass
62 .\" Start of description of a specific option. cmdName gives the
63 .\" option's name as specified in the class command, dbName gives
64 .\" the option's name in the option database, and dbClass gives
65 .\" the option's class in the option database.
68 .\" Print arg1 underlined, then print arg2 normally.
71 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
74 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
75 .\" (for trailing punctuation) and then a closing parenthesis.
77 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
81 .\" # Start an argument description
85 . ie !"\\$2"" .TP \\n()Cu
90 \&\\$1 \\fI\\$2\\fP (\\$3)
103 .\" # define tabbing values for .AP
106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
112 .AS Tcl_Interp Tcl_CreateInterp in/out
113 .\" # BS - start boxed text
114 .\" # ^y = starting y location
122 .if n \l'\\n(.lu\(ul'
125 .\" # BE - end boxed text (draw box now)
130 .ie n \l'\\n(^lu\(ul'
132 .\" Draw four-sided box normally, but don't draw top of
133 .\" box if the box started on an earlier page.
135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 .\" # VS - start vertical sidebar
146 .\" # ^Y = starting y location
147 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
151 .ie n 'mc \s12\(br\s0
154 .\" # VE - end of vertical sidebar
162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
169 .\" # Special macro to handle page bottom: finish off current
170 .\" # box/sidebar if in box/sidebar mode, then invoked standard
171 .\" # page bottom macro.
178 .\" Draw three-sided box if this is the box's first page,
179 .\" draw two sides but no top otherwise.
180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
184 .nr ^x \\n(^tu+1v-\\n(^Yu
185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
198 .\" # DS - begin display
204 .\" # DE - end display
210 .\" # SO - start of list of standard options
212 'ie '\\$1'' .ds So \\fBoptions\\fR
213 'el .ds So \\fB\\$1\\fR
214 .SH "STANDARD OPTIONS"
220 .\" # SE - end of list of standard options
225 See the \\*(So manual entry for details on the standard options.
227 .\" # OP - start of full description for a single option
232 Command-Line Name: \\fB\\$1\\fR
233 Database Name: \\fB\\$2\\fR
234 Database Class: \\fB\\$3\\fR
238 .\" # CS - begin code excerpt
244 .\" # CE - end code excerpt
249 .\" # UL - underline word
253 .\" # QW - apply quotation marks to word
255 .ie '\\*(lq'"' ``\\$1''\\$2
256 .\"" fix emacs highlighting
257 .el \\*(lq\\$1\\*(rq\\$2
259 .\" # PQ - apply parens and quotation marks to word
261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
262 .\"" fix emacs highlighting
263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
265 .\" # QR - quoted range
267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
268 .\"" fix emacs highlighting
269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
271 .\" # MT - "empty" string
277 Tk_CanvasTkwin, Tk_CanvasGetCoord, Tk_CanvasDrawableCoords, Tk_CanvasSetStippleOrigin, Tk_CanvasWindowCoords, Tk_CanvasEventuallyRedraw, Tk_CanvasTagsOption \- utility procedures for canvas type managers
280 \fB#include <tk.h>\fR
283 \fBTk_CanvasTkwin\fR(\fIcanvas\fR)
286 \fBTk_CanvasGetCoord\fR(\fIinterp, canvas, string, doublePtr\fR)
288 \fBTk_CanvasDrawableCoords\fR(\fIcanvas, x, y, drawableXPtr, drawableYPtr\fR)
290 \fBTk_CanvasSetStippleOrigin\fR(\fIcanvas, gc\fR)
292 \fBTk_CanvasWindowCoords\fR(\fIcanvas, x, y, screenXPtr, screenYPtr\fR)
294 \fBTk_CanvasEventuallyRedraw\fR(\fIcanvas, x1, y1, x2, y2\fR)
296 Tk_OptionParseProc *\fBTk_CanvasTagsParseProc\fR;
298 Tk_OptionPrintProc *\fBTk_CanvasTagsPrintProc\fR;
300 .AS Tk_ItemType *drawableXPtr
301 .AP Tk_Canvas canvas in
302 A token that identifies a canvas widget.
303 .AP Tcl_Interp *interp in/out
304 Interpreter to use for error reporting.
305 .AP "const char" *string in
306 Textual description of a canvas coordinate.
307 .AP double *doublePtr out
308 Points to place to store a converted coordinate.
310 An x coordinate in the space of the canvas.
312 A y coordinate in the space of the canvas.
313 .AP short *drawableXPtr out
314 Pointer to a location in which to store an x coordinate in the space
315 of the drawable currently being used to redisplay the canvas.
316 .AP short *drawableYPtr out
317 Pointer to a location in which to store a y coordinate in the space
318 of the drawable currently being used to redisplay the canvas.
320 Graphics context to modify.
321 .AP short *screenXPtr out
322 Points to a location in which to store the screen coordinate in the
323 canvas window that corresponds to \fIx\fR.
324 .AP short *screenYPtr out
325 Points to a location in which to store the screen coordinate in the
326 canvas window that corresponds to \fIy\fR.
328 Left edge of the region that needs redisplay. Only pixels at or to
329 the right of this coordinate need to be redisplayed.
331 Top edge of the region that needs redisplay. Only pixels at or below
332 this coordinate need to be redisplayed.
334 Right edge of the region that needs redisplay. Only pixels to
335 the left of this coordinate need to be redisplayed.
337 Bottom edge of the region that needs redisplay. Only pixels above
338 this coordinate need to be redisplayed.
342 These procedures are called by canvas type managers to perform various
345 \fBTk_CanvasTkwin\fR returns the Tk_Window associated with a particular
348 \fBTk_CanvasGetCoord\fR translates a string specification of a
349 coordinate (such as \fB2p\fR or \fB1.6c\fR) into a double-precision
351 If \fIstring\fR is a valid coordinate description then \fBTk_CanvasGetCoord\fR
352 stores the corresponding canvas coordinate at *\fIdoublePtr\fR
353 and returns \fBTCL_OK\fR.
354 Otherwise it stores an error message in the interpreter result and
355 returns \fBTCL_ERROR\fR.
357 \fBTk_CanvasDrawableCoords\fR is called by type managers during
358 redisplay to compute where to draw things.
359 Given \fIx\fR and \fIy\fR coordinates in the space of the
360 canvas, \fBTk_CanvasDrawableCoords\fR computes the corresponding
361 pixel in the drawable that is currently being used for redisplay;
362 it returns those coordinates in *\fIdrawableXPtr\fR and *\fIdrawableYPtr\fR.
363 This procedure should not be invoked except during redisplay.
365 \fBTk_CanvasSetStippleOrigin\fR is also used during redisplay.
366 It sets the stipple origin in \fIgc\fR so that stipples drawn
367 with \fIgc\fR in the current offscreen pixmap will line up
368 with stipples drawn with origin (0,0) in the canvas's actual
370 \fBTk_CanvasSetStippleOrigin\fR is needed in order to guarantee
371 that stipple patterns line up properly when the canvas is
372 redisplayed in small pieces.
373 Redisplays are carried out in double-buffered fashion where a
374 piece of the canvas is redrawn in an offscreen pixmap and then
375 copied back onto the screen.
376 In this approach the stipple origins in graphics contexts need to
377 be adjusted during each redisplay to compensate for the position
378 of the off-screen pixmap relative to the window.
379 If an item is being drawn with stipples, its type manager typically
380 calls \fBTk_CanvasSetStippleOrigin\fR just before using \fIgc\fR
381 to draw something; after it is finished drawing, the type manager
382 calls \fBXSetTSOrigin\fR to restore the origin in \fIgc\fR back to (0,0)
383 (the restore is needed because graphics contexts are shared, so
384 they cannot be modified permanently).
386 \fBTk_CanvasWindowCoords\fR is similar to \fBTk_CanvasDrawableCoords\fR
387 except that it returns coordinates in the canvas's window on the
388 screen, instead of coordinates in an off-screen pixmap.
390 \fBTk_CanvasEventuallyRedraw\fR may be invoked by a type manager
391 to inform Tk that a portion of a canvas needs to be redrawn.
392 The \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR arguments
393 specify the region that needs to be redrawn, in canvas coordinates.
394 Type managers rarely need to invoke \fBTk_CanvasEventuallyRedraw\fR,
395 since Tk can normally figure out when an item has changed and make
396 the redisplay request on its behalf (this happens, for example
397 whenever Tk calls a \fIconfigureProc\fR or \fIscaleProc\fR).
398 The only time that a type manager needs to call
399 \fBTk_CanvasEventuallyRedraw\fR is if an item has changed on its own
400 without being invoked through one of the procedures in its Tk_ItemType;
401 this could happen, for example, in an image item if the image is
402 modified using image commands.
404 \fBTk_CanvasTagsParseProc\fR and \fBTk_CanvasTagsPrintProc\fR are
405 procedures that handle the \fB\-tags\fR option for canvas items.
406 The code of a canvas type manager will not call these procedures
407 directly, but will use their addresses to create a \fBTk_CustomOption\fR
408 structure for the \fB\-tags\fR option. The code typically looks
412 static const Tk_CustomOption tagsOption = {Tk_CanvasTagsParseProc,
413 Tk_CanvasTagsPrintProc, (ClientData) NULL
416 static const Tk_ConfigSpec configSpecs[] = {
418 {TK_CONFIG_CUSTOM, "\-tags", NULL, NULL,
419 NULL, 0, TK_CONFIG_NULL_OK, &tagsOption},
424 canvas, focus, item type, redisplay, selection, type manager