Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | '\" |
2 | '\" Copyright (c) 1994-1995 Sun Microsystems, Inc. | |
3 | '\" | |
4 | '\" See the file "license.terms" for information on usage and redistribution | |
5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. | |
6 | '\" | |
7 | '\" RCS: @(#) $Id: CrtItemType.3,v 1.6 2000/07/25 21:14:34 jenglish Exp $ | |
8 | '\" | |
9 | '\" The definitions below are for supplemental macros used in Tcl/Tk | |
10 | '\" manual entries. | |
11 | '\" | |
12 | '\" .AP type name in/out ?indent? | |
13 | '\" Start paragraph describing an argument to a library procedure. | |
14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", | |
15 | '\" or "in/out" to describe whether procedure reads or modifies arg, | |
16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be | |
17 | '\" needed; use .AS below instead) | |
18 | '\" | |
19 | '\" .AS ?type? ?name? | |
20 | '\" Give maximum sizes of arguments for setting tab stops. Type and | |
21 | '\" name are examples of largest possible arguments that will be passed | |
22 | '\" to .AP later. If args are omitted, default tab stops are used. | |
23 | '\" | |
24 | '\" .BS | |
25 | '\" Start box enclosure. From here until next .BE, everything will be | |
26 | '\" enclosed in one large box. | |
27 | '\" | |
28 | '\" .BE | |
29 | '\" End of box enclosure. | |
30 | '\" | |
31 | '\" .CS | |
32 | '\" Begin code excerpt. | |
33 | '\" | |
34 | '\" .CE | |
35 | '\" End code excerpt. | |
36 | '\" | |
37 | '\" .VS ?version? ?br? | |
38 | '\" Begin vertical sidebar, for use in marking newly-changed parts | |
39 | '\" of man pages. The first argument is ignored and used for recording | |
40 | '\" the version when the .VS was added, so that the sidebars can be | |
41 | '\" found and removed when they reach a certain age. If another argument | |
42 | '\" is present, then a line break is forced before starting the sidebar. | |
43 | '\" | |
44 | '\" .VE | |
45 | '\" End of vertical sidebar. | |
46 | '\" | |
47 | '\" .DS | |
48 | '\" Begin an indented unfilled display. | |
49 | '\" | |
50 | '\" .DE | |
51 | '\" End of indented unfilled display. | |
52 | '\" | |
53 | '\" .SO | |
54 | '\" Start of list of standard options for a Tk widget. The | |
55 | '\" options follow on successive lines, in four columns separated | |
56 | '\" by tabs. | |
57 | '\" | |
58 | '\" .SE | |
59 | '\" End of list of standard options for a Tk widget. | |
60 | '\" | |
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. | |
66 | '\" | |
67 | '\" .UL arg1 arg2 | |
68 | '\" Print arg1 underlined, then print arg2 normally. | |
69 | '\" | |
70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ | |
71 | '\" | |
72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. | |
73 | .if t .wh -1.3i ^B | |
74 | .nr ^l \n(.l | |
75 | .ad b | |
76 | '\" # Start an argument description | |
77 | .de AP | |
78 | .ie !"\\$4"" .TP \\$4 | |
79 | .el \{\ | |
80 | . ie !"\\$2"" .TP \\n()Cu | |
81 | . el .TP 15 | |
82 | .\} | |
83 | .ta \\n()Au \\n()Bu | |
84 | .ie !"\\$3"" \{\ | |
85 | \&\\$1 \\fI\\$2\\fP (\\$3) | |
86 | .\".b | |
87 | .\} | |
88 | .el \{\ | |
89 | .br | |
90 | .ie !"\\$2"" \{\ | |
91 | \&\\$1 \\fI\\$2\\fP | |
92 | .\} | |
93 | .el \{\ | |
94 | \&\\fI\\$1\\fP | |
95 | .\} | |
96 | .\} | |
97 | .. | |
98 | '\" # define tabbing values for .AP | |
99 | .de AS | |
100 | .nr )A 10n | |
101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n | |
102 | .nr )B \\n()Au+15n | |
103 | .\" | |
104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n | |
105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n | |
106 | .. | |
107 | .AS Tcl_Interp Tcl_CreateInterp in/out | |
108 | '\" # BS - start boxed text | |
109 | '\" # ^y = starting y location | |
110 | '\" # ^b = 1 | |
111 | .de BS | |
112 | .br | |
113 | .mk ^y | |
114 | .nr ^b 1u | |
115 | .if n .nf | |
116 | .if n .ti 0 | |
117 | .if n \l'\\n(.lu\(ul' | |
118 | .if n .fi | |
119 | .. | |
120 | '\" # BE - end boxed text (draw box now) | |
121 | .de BE | |
122 | .nf | |
123 | .ti 0 | |
124 | .mk ^t | |
125 | .ie n \l'\\n(^lu\(ul' | |
126 | .el \{\ | |
127 | .\" Draw four-sided box normally, but don't draw top of | |
128 | .\" box if the box started on an earlier page. | |
129 | .ie !\\n(^b-1 \{\ | |
130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
131 | .\} | |
132 | .el \}\ | |
133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' | |
134 | .\} | |
135 | .\} | |
136 | .fi | |
137 | .br | |
138 | .nr ^b 0 | |
139 | .. | |
140 | '\" # VS - start vertical sidebar | |
141 | '\" # ^Y = starting y location | |
142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) | |
143 | .de VS | |
144 | .if !"\\$2"" .br | |
145 | .mk ^Y | |
146 | .ie n 'mc \s12\(br\s0 | |
147 | .el .nr ^v 1u | |
148 | .. | |
149 | '\" # VE - end of vertical sidebar | |
150 | .de VE | |
151 | .ie n 'mc | |
152 | .el \{\ | |
153 | .ev 2 | |
154 | .nf | |
155 | .ti 0 | |
156 | .mk ^t | |
157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' | |
158 | .sp -1 | |
159 | .fi | |
160 | .ev | |
161 | .\} | |
162 | .nr ^v 0 | |
163 | .. | |
164 | '\" # Special macro to handle page bottom: finish off current | |
165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard | |
166 | '\" # page bottom macro. | |
167 | .de ^B | |
168 | .ev 2 | |
169 | 'ti 0 | |
170 | 'nf | |
171 | .mk ^t | |
172 | .if \\n(^b \{\ | |
173 | .\" Draw three-sided box if this is the box's first page, | |
174 | .\" draw two sides but no top otherwise. | |
175 | .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 | |
176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c | |
177 | .\} | |
178 | .if \\n(^v \{\ | |
179 | .nr ^x \\n(^tu+1v-\\n(^Yu | |
180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c | |
181 | .\} | |
182 | .bp | |
183 | 'fi | |
184 | .ev | |
185 | .if \\n(^b \{\ | |
186 | .mk ^y | |
187 | .nr ^b 2 | |
188 | .\} | |
189 | .if \\n(^v \{\ | |
190 | .mk ^Y | |
191 | .\} | |
192 | .. | |
193 | '\" # DS - begin display | |
194 | .de DS | |
195 | .RS | |
196 | .nf | |
197 | .sp | |
198 | .. | |
199 | '\" # DE - end display | |
200 | .de DE | |
201 | .fi | |
202 | .RE | |
203 | .sp | |
204 | .. | |
205 | '\" # SO - start of list of standard options | |
206 | .de SO | |
207 | .SH "STANDARD OPTIONS" | |
208 | .LP | |
209 | .nf | |
210 | .ta 5.5c 11c | |
211 | .ft B | |
212 | .. | |
213 | '\" # SE - end of list of standard options | |
214 | .de SE | |
215 | .fi | |
216 | .ft R | |
217 | .LP | |
218 | See the \\fBoptions\\fR manual entry for details on the standard options. | |
219 | .. | |
220 | '\" # OP - start of full description for a single option | |
221 | .de OP | |
222 | .LP | |
223 | .nf | |
224 | .ta 4c | |
225 | Command-Line Name: \\fB\\$1\\fR | |
226 | Database Name: \\fB\\$2\\fR | |
227 | Database Class: \\fB\\$3\\fR | |
228 | .fi | |
229 | .IP | |
230 | .. | |
231 | '\" # CS - begin code excerpt | |
232 | .de CS | |
233 | .RS | |
234 | .nf | |
235 | .ta .25i .5i .75i 1i | |
236 | .. | |
237 | '\" # CE - end code excerpt | |
238 | .de CE | |
239 | .fi | |
240 | .RE | |
241 | .. | |
242 | .de UL | |
243 | \\$1\l'|0\(ul'\\$2 | |
244 | .. | |
245 | .TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures" | |
246 | .BS | |
247 | .SH NAME | |
248 | Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item | |
249 | .SH SYNOPSIS | |
250 | .nf | |
251 | \fB#include <tk.h>\fR | |
252 | .sp | |
253 | \fBTk_CreateItemType\fR(\fItypePtr\fR) | |
254 | .sp | |
255 | Tk_ItemType * | |
256 | \fBTk_GetItemTypes\fR() | |
257 | .SH ARGUMENTS | |
258 | .AS Tk_ItemType *typePtr | |
259 | .AP Tk_ItemType *typePtr in | |
260 | Structure that defines the new type of canvas item. | |
261 | .BE | |
262 | ||
263 | .SH INTRODUCTION | |
264 | .PP | |
265 | \fBTk_CreateItemType\fR is invoked to define a new kind of canvas item | |
266 | described by the \fItypePtr\fR argument. | |
267 | An item type corresponds to a particular value of the \fItype\fR | |
268 | argument to the \fBcreate\fR widget command for canvases, and | |
269 | the code that implements a canvas item type is called a \fItype manager\fR. | |
270 | Tk defines several built-in item types, such as \fBrectangle\fR | |
271 | and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR | |
272 | allows additional item types to be defined. | |
273 | Once \fBTk_CreateItemType\fR returns, the new item type may be used | |
274 | in new or existing canvas widgets just like the built-in item | |
275 | types. | |
276 | .PP | |
277 | \fBTk_GetItemTypes\fR returns a pointer to the first in the list | |
278 | of all item types currently defined for canvases. | |
279 | The entries in the list are linked together through their | |
280 | \fInextPtr\fR fields, with the end of the list marked by a | |
281 | NULL \fInextPtr\fR. | |
282 | .PP | |
283 | You may find it easier to understand the rest of this manual entry | |
284 | by looking at the code for an existing canvas item type such as | |
285 | bitmap (file tkCanvBmap.c) or text (tkCanvText.c). | |
286 | The easiest way to create a new type manager is to copy the code | |
287 | for an existing type and modify it for the new type. | |
288 | .PP | |
289 | Tk provides a number of utility procedures for the use of canvas | |
290 | type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR; | |
291 | these are described in separate manual entries. | |
292 | ||
293 | .SH "DATA STRUCTURES" | |
294 | .PP | |
295 | A type manager consists of a collection of procedures that provide a | |
296 | standard set of operations on items of that type. | |
297 | The type manager deals with three kinds of data | |
298 | structures. | |
299 | The first data structure is a Tk_ItemType; it contains | |
300 | information such as the name of the type and pointers to | |
301 | the standard procedures implemented by the type manager: | |
302 | .CS | |
303 | typedef struct Tk_ItemType { | |
304 | char *\fIname\fR; | |
305 | int \fIitemSize\fR; | |
306 | Tk_ItemCreateProc *\fIcreateProc\fR; | |
307 | Tk_ConfigSpec *\fIconfigSpecs\fR; | |
308 | Tk_ItemConfigureProc *\fIconfigProc\fR; | |
309 | Tk_ItemCoordProc *\fIcoordProc\fR; | |
310 | Tk_ItemDeleteProc *\fIdeleteProc\fR; | |
311 | Tk_ItemDisplayProc *\fIdisplayProc\fR; | |
312 | int \fIalwaysRedraw\fR; | |
313 | Tk_ItemPointProc *\fIpointProc\fR; | |
314 | Tk_ItemAreaProc *\fIareaProc\fR; | |
315 | Tk_ItemPostscriptProc *\fIpostscriptProc\fR; | |
316 | Tk_ItemScaleProc *\fIscaleProc\fR; | |
317 | Tk_ItemTranslateProc *\fItranslateProc\fR; | |
318 | Tk_ItemIndexProc *\fIindexProc\fR; | |
319 | Tk_ItemCursorProc *\fIicursorProc\fR; | |
320 | Tk_ItemSelectionProc *\fIselectionProc\fR; | |
321 | Tk_ItemInsertProc *\fIinsertProc\fR; | |
322 | Tk_ItemDCharsProc *\fIdCharsProc\fR; | |
323 | Tk_ItemType *\fInextPtr\fR; | |
324 | } Tk_ItemType; | |
325 | .CE | |
326 | .PP | |
327 | The fields of a Tk_ItemType structure are described in more detail | |
328 | later in this manual entry. | |
329 | When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR | |
330 | argument must point to a structure with all of the fields initialized | |
331 | except \fInextPtr\fR, which Tk sets to link all the types together | |
332 | into a list. | |
333 | The structure must be in permanent memory (either statically | |
334 | allocated or dynamically allocated but never freed); Tk retains | |
335 | a pointer to this structure. | |
336 | .PP | |
337 | The second data structure manipulated by a type manager is an | |
338 | \fIitem record\fR. | |
339 | For each item in a canvas there exists one item record. | |
340 | All of the items of a given type generally have item records with | |
341 | the same structure, but different types usually have different | |
342 | formats for their item records. | |
343 | The first part of each item record is a header with a standard structure | |
344 | defined by Tk via the type Tk_Item; the rest of the item | |
345 | record is defined by the type manager. | |
346 | A type manager must define its item records with a Tk_Item as | |
347 | the first field. | |
348 | For example, the item record for bitmap items is defined as follows: | |
349 | .CS | |
350 | typedef struct BitmapItem { | |
351 | Tk_Item \fIheader\fR; | |
352 | double \fIx\fR, \fIy\fR; | |
353 | Tk_Anchor \fIanchor\fR; | |
354 | Pixmap \fIbitmap\fR; | |
355 | XColor *\fIfgColor\fR; | |
356 | XColor *\fIbgColor\fR; | |
357 | GC \fIgc\fR; | |
358 | } BitmapItem; | |
359 | .CE | |
360 | The \fIheader\fR substructure contains information used by Tk | |
361 | to manage the item, such as its identifier, its tags, its type, | |
362 | and its bounding box. | |
363 | The fields starting with \fIx\fR belong to the type manager: | |
364 | Tk will never read or write them. | |
365 | The type manager should not need to read or write any of the | |
366 | fields in the header except for four fields | |
367 | whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. | |
368 | These fields give a bounding box for the items using integer | |
369 | canvas coordinates: the item should not cover any pixels | |
370 | with x-coordinate lower than \fIx1\fR or y-coordinate | |
371 | lower than \fIy1\fR, nor should it cover any pixels with | |
372 | x-coordinate greater than or equal to \fIx2\fR or y-coordinate | |
373 | greater than or equal to \fIy2\fR. | |
374 | It is up to the type manager to keep the bounding box up to | |
375 | date as the item is moved and reconfigured. | |
376 | .PP | |
377 | Whenever Tk calls a procedure in a type manager it passes in a pointer | |
378 | to an item record. | |
379 | The argument is always passed as a pointer to a Tk_Item; the type | |
380 | manager will typically cast this into a pointer to its own specific | |
381 | type, such as BitmapItem. | |
382 | .PP | |
383 | The third data structure used by type managers has type | |
384 | Tk_Canvas; it serves as an opaque handle for the canvas widget | |
385 | as a whole. | |
386 | Type managers need not know anything about the contents of this | |
387 | structure. | |
388 | A Tk_Canvas handle is typically passed in to the | |
389 | procedures of a type manager, and the type manager can pass the | |
390 | handle back to library procedures such as Tk_CanvasTkwin | |
391 | to fetch information about the canvas. | |
392 | ||
393 | .SH NAME | |
394 | .PP | |
395 | This section and the ones that follow describe each of the fields | |
396 | in a Tk_ItemType structure in detail. | |
397 | The \fIname\fR field provides a string name for the item type. | |
398 | Once \fBTk_CreateImageType\fR returns, this name may be used | |
399 | in \fBcreate\fR widget commands to create items of the new | |
400 | type. | |
401 | If there already existed an item type by this name then | |
402 | the new item type replaces the old one. | |
403 | ||
404 | .SH ITEMSIZE | |
405 | \fItypePtr->itemSize\fR gives the size in bytes of item records | |
406 | of this type, including the Tk_Item header. | |
407 | Tk uses this size to allocate memory space for items of the type. | |
408 | All of the item records for a given type must have the same size. | |
409 | If variable length fields are needed for an item (such as a list | |
410 | of points for a polygon), the type manager can allocate a separate | |
411 | object of variable length and keep a pointer to it in the item record. | |
412 | ||
413 | .SH CREATEPROC | |
414 | .PP | |
415 | \fItypePtr->createProc\fR points to a procedure for | |
416 | Tk to call whenever a new item of this type is created. | |
417 | \fItypePtr->createProc\fR must match the following prototype: | |
418 | .CS | |
419 | typedef int Tk_ItemCreateProc( | |
420 | Tcl_Interp *\fIinterp\fR, | |
421 | Tk_Canvas \fIcanvas\fR, | |
422 | Tk_Item *\fIitemPtr\fR, | |
423 | int \fIobjc\fR, | |
424 | Tcl_Obj* CONST \fIobjv\fR); | |
425 | .CE | |
426 | The \fIinterp\fR argument is the interpreter in which the canvas's | |
427 | \fBcreate\fR widget command was invoked, and \fIcanvas\fR is a | |
428 | handle for the canvas widget. | |
429 | \fIitemPtr\fR is a pointer to a newly-allocated item of | |
430 | size \fItypePtr->itemSize\fR. | |
431 | Tk has already initialized the item's header (the first | |
432 | \fBsizeof(Tk_ItemType)\fR bytes). | |
433 | The \fIobjc\fR and \fIobjv\fR arguments describe all of the | |
434 | arguments to the \fBcreate\fR command after the \fItype\fR | |
435 | argument. | |
436 | For example, in the widget command | |
437 | .CS | |
438 | \fB\&.c create rectangle 10 20 50 50 \-fill black\fR | |
439 | .CE | |
440 | \fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the | |
441 | integer object \fB10\fR. | |
442 | .PP | |
443 | \fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize | |
444 | the type-specific parts of the item record and set an initial value | |
445 | for the bounding box in the item's header. | |
446 | It should return a standard Tcl completion code and leave an | |
447 | error message in \fIinterp->result\fR if an error occurs. | |
448 | If an error occurs Tk will free the item record, so \fIcreateProc\fR | |
449 | must be sure to leave the item record in a clean state if it returns an error | |
450 | (e.g., it must free any additional memory that it allocated for | |
451 | the item). | |
452 | ||
453 | .SH CONFIGSPECS | |
454 | .PP | |
455 | Each type manager must provide a standard table describing its | |
456 | configuration options, in a form suitable for use with | |
457 | \fBTk_ConfigureWidget\fR. | |
458 | This table will normally be used by \fItypePtr->createProc\fR | |
459 | and \fItypePtr->configProc\fR, but Tk also uses it directly | |
460 | to retrieve option information in the \fBitemcget\fR and | |
461 | \fBitemconfigure\fR widget commands. | |
462 | \fItypePtr->configSpecs\fR must point to the configuration table | |
463 | for this type. | |
464 | Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR | |
465 | for implementing the \fB\-tags\fR option; see an existing type | |
466 | manager for an example of how to use it in \fIconfigSpecs\fR. | |
467 | ||
468 | .SH CONFIGPROC | |
469 | .PP | |
470 | \fItypePtr->configProc\fR is called by Tk whenever the | |
471 | \fBitemconfigure\fR widget command is invoked to change the | |
472 | configuration options for a canvas item. | |
473 | This procedure must match the following prototype: | |
474 | .CS | |
475 | typedef int Tk_ItemConfigureProc( | |
476 | Tcl_Interp *\fIinterp\fR, | |
477 | Tk_Canvas \fIcanvas\fR, | |
478 | Tk_Item *\fIitemPtr\fR, | |
479 | int \fIobjc\fR, | |
480 | Tcl_Obj* CONST \fIobjv\fR, | |
481 | int \fIflags\fR); | |
482 | .CE | |
483 | The \fIinterp\fR objument identifies the interpreter in which the | |
484 | widget command was invoked, \fIcanvas\fR is a handle for the canvas | |
485 | widget, and \fIitemPtr\fR is a pointer to the item being configured. | |
486 | \fIobjc\fR and \fIobjv\fR contain the configuration options. For | |
487 | example, if the following command is invoked: | |
488 | .CS | |
489 | \fB\&.c itemconfigure 2 \-fill red \-outline black\fR | |
490 | .CE | |
491 | \fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR | |
492 | through \fBblack\fR. | |
493 | \fIobjc\fR will always be an even value. | |
494 | The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; | |
495 | currently this value is always TK_CONFIG_ARGV_ONLY when Tk | |
496 | invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR | |
497 | procedure will usually invoke \fIconfigProc\fR with different flag values. | |
498 | .PP | |
499 | \fItypePtr->configProc\fR returns a standard Tcl completion code and | |
500 | leaves an error message in \fIinterp->result\fR if an error occurs. | |
501 | It must update the item's bounding box to reflect the new configuration | |
502 | options. | |
503 | ||
504 | .SH COORDPROC | |
505 | .PP | |
506 | \fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR | |
507 | widget command for an item. | |
508 | It must match the following prototype: | |
509 | .CS | |
510 | typedef int Tk_ItemCoordProc( | |
511 | Tcl_Interp *\fIinterp\fR, | |
512 | Tk_Canvas \fIcanvas\fR, | |
513 | Tk_Item *\fIitemPtr\fR, | |
514 | int \fIobjc\fR, | |
515 | Tcl_Obj* CONST \fIobjv\fR); | |
516 | .CE | |
517 | The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR | |
518 | all have the standard meanings, and \fIobjc\fR and \fIobjv\fR | |
519 | describe the coordinate arguments. | |
520 | For example, if the following widget command is invoked: | |
521 | .CS | |
522 | \fB\&.c coords 2 30 90\fR | |
523 | .CE | |
524 | \fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects | |
525 | \fB30\fR and \fB90\fR. | |
526 | .PP | |
527 | The \fIcoordProc\fR procedure should process the new coordinates, | |
528 | update the item appropriately (e.g., it must reset the bounding | |
529 | box in the item's header), and return a standard Tcl completion | |
530 | code. | |
531 | If an error occurs, \fIcoordProc\fR must leave an error message in | |
532 | \fIinterp->result\fR. | |
533 | ||
534 | .SH DELETEPROC | |
535 | .PP | |
536 | \fItypePtr->deleteProc\fR is invoked by Tk to delete an item | |
537 | and free any resources allocated to it. | |
538 | It must match the following prototype: | |
539 | .CS | |
540 | typedef void Tk_ItemDeleteProc( | |
541 | Tk_Canvas \fIcanvas\fR, | |
542 | Tk_Item *\fIitemPtr\fR, | |
543 | Display *\fIdisplay\fR); | |
544 | .CE | |
545 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual | |
546 | interpretations, and \fIdisplay\fR identifies the X display containing | |
547 | the canvas. | |
548 | \fIdeleteProc\fR must free up any resources allocated for the item, | |
549 | so that Tk can free the item record. | |
550 | \fIdeleteProc\fR should not actually free the item record; this will | |
551 | be done by Tk when \fIdeleteProc\fR returns. | |
552 | ||
553 | .SH "DISPLAYPROC AND ALWAYSREDRAW" | |
554 | .PP | |
555 | \fItypePtr->displayProc\fR is invoked by Tk to redraw an item | |
556 | on the screen. | |
557 | It must match the following prototype: | |
558 | .CS | |
559 | typedef void Tk_ItemDisplayProc( | |
560 | Tk_Canvas \fIcanvas\fR, | |
561 | Tk_Item *\fIitemPtr\fR, | |
562 | Display *\fIdisplay\fR, | |
563 | Drawable \fIdst\fR, | |
564 | int \fIx\fR, | |
565 | int \fIy\fR, | |
566 | int \fIwidth\fR, | |
567 | int \fIheight\fR); | |
568 | .CE | |
569 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. | |
570 | \fIdisplay\fR identifies the display containing the canvas, and | |
571 | \fIdst\fR specifies a drawable in which the item should be rendered; | |
572 | typically this is an off-screen pixmap, which Tk will copy into | |
573 | the canvas's window once all relevant items have been drawn. | |
574 | \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular | |
575 | region in canvas coordinates, which is the area to be redrawn; | |
576 | only information that overlaps this area needs to be redrawn. | |
577 | Tk will not call \fIdisplayProc\fR unless the item's bounding box | |
578 | overlaps the redraw area, but the type manager may wish to use | |
579 | the redraw area to optimize the redisplay of the item. | |
580 | .PP | |
581 | Because of scrolling and the use of off-screen pixmaps for | |
582 | double-buffered redisplay, the item's coordinates in \fIdst\fR | |
583 | will not necessarily be the same as those in the canvas. | |
584 | \fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR | |
585 | to transform coordinates from those of the canvas to those | |
586 | of \fIdst\fR. | |
587 | .PP | |
588 | Normally an item's \fIdisplayProc\fR is only invoked if the item | |
589 | overlaps the area being displayed. | |
590 | However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then | |
591 | \fIdisplayProc\fR is invoked during every redisplay operation, | |
592 | even if the item doesn't overlap the area of redisplay. | |
593 | \fIalwaysRedraw\fR should normally be set to 0; it is only | |
594 | set to 1 in special cases such as window items that need to be | |
595 | unmapped when they are off-screen. | |
596 | ||
597 | .SH POINTPROC | |
598 | .PP | |
599 | \fItypePtr->pointProc\fR is invoked by Tk to find out how close | |
600 | a given point is to a canvas item. | |
601 | Tk uses this procedure for purposes such as locating the item | |
602 | under the mouse or finding the closest item to a given point. | |
603 | The procedure must match the following prototype: | |
604 | .CS | |
605 | typedef double Tk_ItemPointProc( | |
606 | Tk_Canvas \fIcanvas\fR, | |
607 | Tk_Item *\fIitemPtr\fR, | |
608 | double *\fIpointPtr\fR); | |
609 | .CE | |
610 | \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. | |
611 | \fIpointPtr\fR points to an array of two numbers giving | |
612 | the x and y coordinates of a point. | |
613 | \fIpointProc\fR must return a real value giving the distance | |
614 | from the point to the item, or 0 if the point lies inside | |
615 | the item. | |
616 | ||
617 | .SH AREAPROC | |
618 | .PP | |
619 | \fItypePtr->areaProc\fR is invoked by Tk to find out the relationship | |
620 | between an item and a rectangular area. | |
621 | It must match the following prototype: | |
622 | .CS | |
623 | typedef int Tk_ItemAreaProc( | |
624 | Tk_Canvas \fIcanvas\fR, | |
625 | Tk_Item *\fIitemPtr\fR, | |
626 | double *\fIrectPtr\fR); | |
627 | .CE | |
628 | \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. | |
629 | \fIrectPtr\fR points to an array of four real numbers; | |
630 | the first two give the x and y coordinates of the upper left | |
631 | corner of a rectangle, and the second two give the x and y | |
632 | coordinates of the lower right corner. | |
633 | \fIareaProc\fR must return \-1 if the item lies entirely outside | |
634 | the given area, 0 if it lies partially inside and partially | |
635 | outside the area, and 1 if it lies entirely inside the area. | |
636 | ||
637 | .SH POSTSCRIPTPROC | |
638 | .PP | |
639 | \fItypePtr->postscriptProc\fR is invoked by Tk to generate | |
640 | Postcript for an item during the \fBpostscript\fR widget command. | |
641 | If the type manager is not capable of generating Postscript then | |
642 | \fItypePtr->postscriptProc\fR should be NULL. | |
643 | The procedure must match the following prototype: | |
644 | .CS | |
645 | typedef int Tk_ItemPostscriptProc( | |
646 | Tcl_Interp *\fIinterp\fR, | |
647 | Tk_Canvas \fIcanvas\fR, | |
648 | Tk_Item *\fIitemPtr\fR, | |
649 | int \fIprepass\fR); | |
650 | .CE | |
651 | The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have | |
652 | standard meanings; \fIprepass\fR will be described below. | |
653 | If \fIpostscriptProc\fR completes successfully, it should append | |
654 | Postscript for the item to the information in \fIinterp->result\fR | |
655 | (e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) | |
656 | and return TCL_OK. | |
657 | If an error occurs, \fIpostscriptProc\fR should clear the result | |
658 | and replace its contents with an error message; then it should | |
659 | return TCL_ERROR. | |
660 | .PP | |
661 | Tk provides a collection of utility procedures to simplify | |
662 | \fIpostscriptProc\fR. | |
663 | For example, \fBTk_CanvasPsColor\fR will generate Postscript to set | |
664 | the current color to a given Tk color and \fBTk_CanvasPsFont\fR will | |
665 | set up font information. | |
666 | When generating Postscript, the type manager is free to change the | |
667 | graphics state of the Postscript interpreter, since Tk places | |
668 | \fBgsave\fR and \fBgrestore\fR commands around the Postscript for | |
669 | the item. | |
670 | The type manager can use canvas x coordinates directly in its Postscript, | |
671 | but it must call \fBTk_CanvasPsY\fR to convert y coordinates from | |
672 | the space of the canvas (where the origin is at the | |
673 | upper left) to the space of Postscript (where the origin is at the | |
674 | lower left). | |
675 | .PP | |
676 | In order to generate Postscript that complies with the Adobe Document | |
677 | Structuring Conventions, Tk actually generates Postscript in two passes. | |
678 | It calls each item's \fIpostscriptProc\fR in each pass. | |
679 | The only purpose of the first pass is to collect font information | |
680 | (which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is | |
681 | discarded. | |
682 | Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1 | |
683 | during the first pass; the type manager can use \fIprepass\fR to skip | |
684 | all Postscript generation except for calls to \fBTk_CanvasPsFont\fR. | |
685 | During the second pass \fIprepass\fR will be 0, so the type manager | |
686 | must generate complete Postscript. | |
687 | ||
688 | .SH SCALEPROC | |
689 | \fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item | |
690 | during the \fBscale\fR widget command. | |
691 | The procedure must match the following prototype: | |
692 | .CS | |
693 | typedef void Tk_ItemScaleProc( | |
694 | Tk_Canvas \fIcanvas\fR, | |
695 | Tk_Item *\fIitemPtr\fR, | |
696 | double \fIoriginX\fR, | |
697 | double \fIoriginY\fR, | |
698 | double \fIscaleX\fR, | |
699 | double \fIscaleY\fR); | |
700 | .CE | |
701 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. | |
702 | \fIoriginX\fR and \fIoriginY\fR specify an origin relative to which | |
703 | the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the | |
704 | x and y scale factors. | |
705 | The item should adjust its coordinates so that a point in the item | |
706 | that used to have coordinates \fIx\fR and \fIy\fR will have new | |
707 | coordinates \fIx'\fR and \fIy'\fR, where | |
708 | .CS | |
709 | \fIx' = originX + scaleX*(x-originX) | |
710 | y' = originY + scaleY*(y-originY)\fR | |
711 | .CE | |
712 | \fIscaleProc\fR must also update the bounding box in the item's | |
713 | header. | |
714 | ||
715 | .SH TRANSLATEPROC | |
716 | \fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item | |
717 | during the \fBmove\fR widget command. | |
718 | The procedure must match the following prototype: | |
719 | .CS | |
720 | typedef void Tk_ItemTranslateProc( | |
721 | Tk_Canvas \fIcanvas\fR, | |
722 | Tk_Item *\fIitemPtr\fR, | |
723 | double \fIdeltaX\fR, | |
724 | double \fIdeltaY\fR); | |
725 | .CE | |
726 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, | |
727 | and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be | |
728 | added to each x and y coordinate within the item. | |
729 | The type manager should adjust the item's coordinates and | |
730 | update the bounding box in the item's header. | |
731 | ||
732 | .SH INDEXPROC | |
733 | \fItypePtr->indexProc\fR is invoked by Tk to translate a string | |
734 | index specification into a numerical index, for example during the | |
735 | \fBindex\fR widget command. | |
736 | It is only relevant for item types that support indexable text; | |
737 | \fItypePtr->indexProc\fR may be specified as NULL for non-textual | |
738 | item types. | |
739 | The procedure must match the following prototype: | |
740 | .CS | |
741 | typedef int Tk_ItemIndexProc( | |
742 | Tcl_Interp *\fIinterp\fR, | |
743 | Tk_Canvas \fIcanvas\fR, | |
744 | Tk_Item *\fIitemPtr\fR, | |
745 | char \fIindexString\fR, | |
746 | int *\fIindexPtr\fR); | |
747 | .CE | |
748 | The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all | |
749 | have the usual meaning. | |
750 | \fIindexString\fR contains a textual description of an index, | |
751 | and \fIindexPtr\fR points to an integer value that should be | |
752 | filled in with a numerical index. | |
753 | It is up to the type manager to decide what forms of index | |
754 | are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, | |
755 | \fBend\fR, etc.). | |
756 | \fIindexProc\fR should return a Tcl completion code and set | |
757 | \fIinterp->result\fR in the event of an error. | |
758 | ||
759 | .SH ICURSORPROC | |
760 | .PP | |
761 | \fItypePtr->icursorProc\fR is invoked by Tk during | |
762 | the \fBicursor\fR widget command to set the position of the | |
763 | insertion cursor in a textual item. | |
764 | It is only relevant for item types that support an insertion cursor; | |
765 | \fItypePtr->icursorProc\fR may be specified as NULL for item types | |
766 | that don't support an insertion cursor. | |
767 | The procedure must match the following prototype: | |
768 | .CS | |
769 | typedef void Tk_ItemCursorProc( | |
770 | Tk_Canvas \fIcanvas\fR, | |
771 | Tk_Item *\fIitemPtr\fR, | |
772 | int \fIindex\fR); | |
773 | .CE | |
774 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and | |
775 | \fIindex\fR is an index into the item's text, as returned by a | |
776 | previous call to \fItypePtr->insertProc\fR. | |
777 | The type manager should position the insertion cursor in the | |
778 | item just before the character given by \fIindex\fR. | |
779 | Whether or not to actually display the insertion cursor is | |
780 | determined by other information provided by \fBTk_CanvasGetTextInfo\fR. | |
781 | ||
782 | .SH SELECTIONPROC | |
783 | .PP | |
784 | \fItypePtr->selectionProc\fR is invoked by Tk during selection | |
785 | retrievals; it must return part or all of the selected text in | |
786 | the item (if any). | |
787 | It is only relevant for item types that support text; | |
788 | \fItypePtr->selectionProc\fR may be specified as NULL for non-textual | |
789 | item types. | |
790 | The procedure must match the following prototype: | |
791 | .CS | |
792 | typedef int Tk_ItemSelectionProc( | |
793 | Tk_Canvas \fIcanvas\fR, | |
794 | Tk_Item *\fIitemPtr\fR, | |
795 | int \fIoffset\fR, | |
796 | char *\fIbuffer\fR, | |
797 | int \fImaxBytes\fR); | |
798 | .CE | |
799 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. | |
800 | \fIoffset\fR is an offset in bytes into the selection where 0 refers | |
801 | to the first byte of the selection; it identifies | |
802 | the first character that is to be returned in this call. | |
803 | \fIbuffer\fR points to an area of memory in which to store the | |
804 | requested bytes, and \fImaxBytes\fR specifies the maximum number | |
805 | of bytes to return. | |
806 | \fIselectionProc\fR should extract up to \fImaxBytes\fR characters | |
807 | from the selection and copy them to \fImaxBytes\fR; it should | |
808 | return a count of the number of bytes actually copied, which may | |
809 | be less than \fImaxBytes\fR if there aren't \fIoffset+maxBytes\fR bytes | |
810 | in the selection. | |
811 | ||
812 | .SH INSERTPROC | |
813 | .PP | |
814 | \fItypePtr->insertProc\fR is invoked by Tk during | |
815 | the \fBinsert\fR widget command to insert new text into a | |
816 | canvas item. | |
817 | It is only relevant for item types that support text; | |
818 | \fItypePtr->insertProc\fR may be specified as NULL for non-textual | |
819 | item types. | |
820 | The procedure must match the following prototype: | |
821 | .CS | |
822 | typedef void Tk_ItemInsertProc( | |
823 | Tk_Canvas \fIcanvas\fR, | |
824 | Tk_Item *\fIitemPtr\fR, | |
825 | int \fIindex\fR, | |
826 | char *\fIstring\fR); | |
827 | .CE | |
828 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. | |
829 | \fIindex\fR is an index into the item's text, as returned by a | |
830 | previous call to \fItypePtr->insertProc\fR, and \fIstring\fR | |
831 | contains new text to insert just before the character given | |
832 | by \fIindex\fR. | |
833 | The type manager should insert the text and recompute the bounding | |
834 | box in the item's header. | |
835 | ||
836 | .SH DCHARSPROC | |
837 | .PP | |
838 | \fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR | |
839 | widget command to delete a range of text from a canvas item. | |
840 | It is only relevant for item types that support text; | |
841 | \fItypePtr->dCharsProc\fR may be specified as NULL for non-textual | |
842 | item types. | |
843 | The procedure must match the following prototype: | |
844 | .CS | |
845 | typedef void Tk_ItemDCharsProc( | |
846 | Tk_Canvas \fIcanvas\fR, | |
847 | Tk_Item *\fIitemPtr\fR, | |
848 | int \fIfirst\fR, | |
849 | int \fIlast\fR); | |
850 | .CE | |
851 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. | |
852 | \fIfirst\fR and \fIlast\fR give the indices of the first and last bytes | |
853 | to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR. | |
854 | The type manager should delete the specified characters and update | |
855 | the bounding box in the item's header. | |
856 | ||
857 | .SH "SEE ALSO" | |
858 | Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin | |
859 | ||
860 | .SH KEYWORDS | |
861 | canvas, focus, item type, selection, type manager |