1Tk_CreateItemType(3) Tk Library Procedures Tk_CreateItemType(3)
2______________________________________________________________________________
6
8 Tk_CreateItemType, Tk_GetItemTypes - define new kind of canvas item
9
11 #include <tk.h>
12 Tk_CreateItemType(typePtr)
14 Tk_ItemType *
16 Tk_GetItemTypes()
17
19 Tk_ItemType *typePtr (in) Structure that defines the new type
20 of canvas item.
21______________________________________________________________________________
22
24 Tk_CreateItemType is invoked to define a new kind of canvas item de‐
25 scribed by the typePtr argument. An item type corresponds to a partic‐
26 ular value of the type argument to the create widget command for can‐
27 vases, and the code that implements a canvas item type is called a type
28 manager. Tk defines several built-in item types, such as rectangle and
29 text and image, but Tk_CreateItemType allows additional item types to
30 be defined. Once Tk_CreateItemType returns, the new item type may be
31 used in new or existing canvas widgets just like the built-in item
32 types.
33 Tk_GetItemTypes returns a pointer to the first in the list of all item
35 types currently defined for canvases. The entries in the list are
36 linked together through their nextPtr fields, with the end of the list
37 marked by a NULL nextPtr.
38 You may find it easier to understand the rest of this manual entry by
40 looking at the code for an existing canvas item type such as bitmap (in
41 the file tkCanvBmap.c) or text (tkCanvText.c). The easiest way to cre‐
42 ate a new type manager is to copy the code for an existing type and
43 modify it for the new type.
44 Tk provides a number of utility procedures for the use of canvas type
46 managers, such as Tk_CanvasCoords and Tk_CanvasPsColor; these are de‐
47 scribed in separate manual entries.
48
50 A type manager consists of a collection of procedures that provide a
51 standard set of operations on items of that type. The type manager
52 deals with three kinds of data structures. The first data structure is
53 a Tk_ItemType; it contains information such as the name of the type and
54 pointers to the standard procedures implemented by the type manager:
55 typedef struct Tk_ItemType {
57 const char *name;
58 int itemSize;
59 Tk_ItemCreateProc *createProc;
60 const Tk_ConfigSpec *configSpecs;
61 Tk_ItemConfigureProc *configProc;
62 Tk_ItemCoordProc *coordProc;
63 Tk_ItemDeleteProc *deleteProc;
64 Tk_ItemDisplayProc *displayProc;
65 int alwaysRedraw;
66 Tk_ItemPointProc *pointProc;
67 Tk_ItemAreaProc *areaProc;
68 Tk_ItemPostscriptProc *postscriptProc;
69 Tk_ItemScaleProc *scaleProc;
70 Tk_ItemTranslateProc *translateProc;
71 Tk_ItemIndexProc *indexProc;
72 Tk_ItemCursorProc *icursorProc;
73 Tk_ItemSelectionProc *selectionProc;
74 Tk_ItemInsertProc *insertProc;
75 Tk_ItemDCharsProc *dCharsProc;
76 Tk_ItemType *nextPtr;
77 } Tk_ItemType;
78 The fields of a Tk_ItemType structure are described in more detail
80 later in this manual entry. When Tk_CreateItemType is called, its
81 typePtr argument must point to a structure with all of the fields ini‐
82 tialized except nextPtr, which Tk sets to link all the types together
83 into a list. The structure must be in permanent memory (either stati‐
84 cally allocated or dynamically allocated but never freed); Tk retains a
85 pointer to this structure.
86 The second data structure manipulated by a type manager is an item
88 record. For each item in a canvas there exists one item record. All
89 of the items of a given type generally have item records with the same
90 structure, but different types usually have different formats for their
91 item records. The first part of each item record is a header with a
92 standard structure defined by Tk via the type Tk_Item; the rest of the
93 item record is defined by the type manager. A type manager must define
94 its item records with a Tk_Item as the first field. For example, the
95 item record for bitmap items is defined as follows:
96 typedef struct BitmapItem {
98 Tk_Item header;
99 double x, y;
100 Tk_Anchor anchor;
101 Pixmap bitmap;
102 XColor *fgColor;
103 XColor *bgColor;
104 GC gc;
105 } BitmapItem;
106 The header substructure contains information used by Tk to manage the
108 item, such as its identifier, its tags, its type, and its bounding box.
109 The fields starting with x belong to the type manager: Tk will never
110 read or write them. The type manager should not need to read or write
111 any of the fields in the header except for four fields whose names are
112 x1, y1, x2, and y2. These fields give a bounding box for the items us‐
113 ing integer canvas coordinates: the item should not cover any pixels
114 with x-coordinate lower than x1 or y-coordinate lower than y1, nor
115 should it cover any pixels with x-coordinate greater than or equal to
116 x2 or y-coordinate greater than or equal to y2. It is up to the type
117 manager to keep the bounding box up to date as the item is moved and
118 reconfigured.
119 Whenever Tk calls a procedure in a type manager it passes in a pointer
121 to an item record. The argument is always passed as a pointer to a
122 Tk_Item; the type manager will typically cast this into a pointer to
123 its own specific type, such as BitmapItem.
124 The third data structure used by type managers has type Tk_Canvas; it
126 serves as an opaque handle for the canvas widget as a whole. Type man‐
127 agers need not know anything about the contents of this structure. A
128 Tk_Canvas handle is typically passed in to the procedures of a type
129 manager, and the type manager can pass the handle back to library pro‐
130 cedures such as Tk_CanvasTkwin to fetch information about the canvas.
131
133 NAME
134 This section and the ones that follow describe each of the fields in a
135 Tk_ItemType structure in detail. The name field provides a string name
136 for the item type. Once Tk_CreateImageType returns, this name may be
137 used in create widget commands to create items of the new type. If
138 there already existed an item type by this name then the new item type
139 replaces the old one.
140 FLAGS (IN ALWAYSREDRAW)
142 The typePtr->alwaysRedraw field (so named for historic reasons) con‐
143 tains a collection of flag bits that modify how the canvas core inter‐
144 acts with the item. The following bits are defined:
145 1 Indicates that the item should always be redrawn when any part
147 of the canvas is redrawn, rather than only when the bounding box
148 of the item overlaps the area being redrawn. This is used by
149 window items, for example, which need to unmap subwindows that
150 are not on the screen.
151 TK_CONFIG_OBJS
153 Indicates that operations which would otherwise take a string
154 (or array of strings) actually take a Tcl_Obj reference (or an
155 array of such references). The operations to which this applies
156 are the configProc, the coordProc, the createProc, the indexProc
157 and the insertProc.
158 TK_MOVABLE_POINTS
160 Indicates that the item supports the dCharsProc, indexProc and │
161 insertProc with the same semantics as Tk's built-in line and │
162 polygon types, and that hence individual coordinate points can │
163 be moved. Must not be set if any of the above methods is NULL.
164 ITEMSIZE
166 typePtr->itemSize gives the size in bytes of item records of this type,
167 including the Tk_Item header. Tk uses this size to allocate memory
168 space for items of the type. All of the item records for a given type
169 must have the same size. If variable length fields are needed for an
170 item (such as a list of points for a polygon), the type manager can al‐
171 locate a separate object of variable length and keep a pointer to it in
172 the item record.
173 CREATEPROC
175 typePtr->createProc points to a procedure for Tk to call whenever a new
176 item of this type is created. typePtr->createProc must match the fol‐
177 lowing prototype:
178 typedef int Tk_ItemCreateProc(
180 Tcl_Interp *interp,
181 Tk_Canvas canvas,
182 Tk_Item *itemPtr,
183 int objc,
184 Tcl_Obj *const objv[]);
185 The interp argument is the interpreter in which the canvas's create
187 widget command was invoked, and canvas is a handle for the canvas wid‐
188 get. itemPtr is a pointer to a newly-allocated item of size type‐
189 Ptr->itemSize. Tk has already initialized the item's header (the first
190 sizeof(Tk_ItemType) bytes). The objc and objv arguments describe all
191 of the arguments to the create command after the type argument. Note
192 that if TK_CONFIG_OBJS is not set in the typePtr->alwaysRedraw field,
193 the objv parameter will actually contain a pointer to an array of con‐
194 stant strings. For example, in the widget command:
195 .c create rectangle 10 20 50 50 -fill black
197 objc will be 6 and objv[0] will contain the integer object 10.
199 createProc should use objc and objv to initialize the type-specific
201 parts of the item record and set an initial value for the bounding box
202 in the item's header. It should return a standard Tcl completion code
203 and leave an error message in the interpreter result if an error oc‐
204 curs. If an error occurs Tk will free the item record, so createProc
205 must be sure to leave the item record in a clean state if it returns an
206 error (e.g., it must free any additional memory that it allocated for
207 the item).
208 CONFIGSPECS
210 Each type manager must provide a standard table describing its configu‐
211 ration options, in a form suitable for use with Tk_ConfigureWidget.
212 This table will normally be used by typePtr->createProc and type‐
213 Ptr->configProc, but Tk also uses it directly to retrieve option infor‐
214 mation in the itemcget and itemconfigure widget commands. type‐
215 Ptr->configSpecs must point to the configuration table for this type.
216 Note: Tk provides a custom option type tk_CanvasTagsOption for imple‐
217 menting the -tags option; see an existing type manager for an example
218 of how to use it in configSpecs.
219 CONFIGPROC
221 typePtr->configProc is called by Tk whenever the itemconfigure widget
222 command is invoked to change the configuration options for a canvas
223 item. This procedure must match the following prototype:
224 typedef int Tk_ItemConfigureProc(
226 Tcl_Interp *interp,
227 Tk_Canvas canvas,
228 Tk_Item *itemPtr,
229 int objc,
230 Tcl_Obj *const objv[],
231 int flags);
232 The interp argument identifies the interpreter in which the widget com‐
234 mand was invoked, canvas is a handle for the canvas widget, and itemPtr
235 is a pointer to the item being configured. objc and objv contain the
236 configuration options. Note that if TK_CONFIG_OBJS is not set in the
237 typePtr->alwaysRedraw field, the objv parameter will actually contain a
238 pointer to an array of constant strings. For example, if the following
239 command is invoked:
240 .c itemconfigure 2 -fill red -outline black
242 objc is 4 and objv contains the string objects -fill through black.
244 objc will always be an even value. The flags argument contains flags
245 to pass to Tk_ConfigureWidget; currently this value is always TK_CON‐
246 FIG_ARGV_ONLY when Tk invokes typePtr->configProc, but the type man‐
247 ager's createProc procedure will usually invoke configProc with differ‐
248 ent flag values.
249 typePtr->configProc returns a standard Tcl completion code and leaves
251 an error message in the interpreter result if an error occurs. It must
252 update the item's bounding box to reflect the new configuration op‐
253 tions.
254 COORDPROC
256 typePtr->coordProc is invoked by Tk to implement the coords widget com‐
257 mand for an item. It must match the following prototype:
258 typedef int Tk_ItemCoordProc(
260 Tcl_Interp *interp,
261 Tk_Canvas canvas,
262 Tk_Item *itemPtr,
263 int objc,
264 Tcl_Obj *const objv[]);
265 The arguments interp, canvas, and itemPtr all have the standard mean‐
267 ings, and objc and objv describe the coordinate arguments. Note that
268 if TK_CONFIG_OBJS is not set in the typePtr->alwaysRedraw field, the
269 objv parameter will actually contain a pointer to an array of constant
270 strings. For example, if the following widget command is invoked:
271 .c coords 2 30 90
273 objc will be 2 and objv will contain the integer objects 30 and 90.
275 The coordProc procedure should process the new coordinates, update the
277 item appropriately (e.g., it must reset the bounding box in the item's
278 header), and return a standard Tcl completion code. If an error oc‐
279 curs, coordProc must leave an error message in the interpreter result.
280 DELETEPROC
282 typePtr->deleteProc is invoked by Tk to delete an item and free any re‐
283 sources allocated to it. It must match the following prototype:
284 typedef void Tk_ItemDeleteProc(
286 Tk_Canvas canvas,
287 Tk_Item *itemPtr,
288 Display *display);
289 The canvas and itemPtr arguments have the usual interpretations, and
291 display identifies the X display containing the canvas. deleteProc
292 must free up any resources allocated for the item, so that Tk can free
293 the item record. deleteProc should not actually free the item record;
294 this will be done by Tk when deleteProc returns.
295 DISPLAYPROC
297 typePtr->displayProc is invoked by Tk to redraw an item on the screen.
298 It must match the following prototype:
299 typedef void Tk_ItemDisplayProc(
301 Tk_Canvas canvas,
302 Tk_Item *itemPtr,
303 Display *display,
304 Drawable dst,
305 int x,
306 int y,
307 int width,
308 int height);
309 The canvas and itemPtr arguments have the usual meaning. display iden‐
311 tifies the display containing the canvas, and dst specifies a drawable
312 in which the item should be rendered; typically this is an off-screen
313 pixmap, which Tk will copy into the canvas's window once all relevant
314 items have been drawn. x, y, width, and height specify a rectangular
315 region in canvas coordinates, which is the area to be redrawn; only in‐
316 formation that overlaps this area needs to be redrawn. Tk will not
317 call displayProc unless the item's bounding box overlaps the redraw
318 area, but the type manager may wish to use the redraw area to optimize
319 the redisplay of the item.
320 Because of scrolling and the use of off-screen pixmaps for double-
322 buffered redisplay, the item's coordinates in dst will not necessarily
323 be the same as those in the canvas. displayProc should call Tk_Canvas‐
324 DrawableCoords to transform coordinates from those of the canvas to
325 those of dst.
326 Normally an item's displayProc is only invoked if the item overlaps the
328 area being displayed. However, if bit zero of typePtr->alwaysRedraw is
329 1, (i.e. “typePtr->alwaysRedraw & 1 == 1”) then displayProc is invoked
330 during every redisplay operation, even if the item does not overlap the
331 area of redisplay; this is useful for cases such as window items, where
332 the subwindow needs to be unmapped when it is off the screen.
333 POINTPROC
335 typePtr->pointProc is invoked by Tk to find out how close a given point
336 is to a canvas item. Tk uses this procedure for purposes such as lo‐
337 cating the item under the mouse or finding the closest item to a given
338 point. The procedure must match the following prototype:
339 typedef double Tk_ItemPointProc(
341 Tk_Canvas canvas,
342 Tk_Item *itemPtr,
343 double *pointPtr);
344 canvas and itemPtr have the usual meaning. pointPtr points to an array
346 of two numbers giving the x and y coordinates of a point. pointProc
347 must return a real value giving the distance from the point to the
348 item, or 0 if the point lies inside the item.
349 AREAPROC
351 typePtr->areaProc is invoked by Tk to find out the relationship between
352 an item and a rectangular area. It must match the following prototype:
353 typedef int Tk_ItemAreaProc(
355 Tk_Canvas canvas,
356 Tk_Item *itemPtr,
357 double *rectPtr);
358 canvas and itemPtr have the usual meaning. rectPtr points to an array
360 of four real numbers; the first two give the x and y coordinates of the
361 upper left corner of a rectangle, and the second two give the x and y
362 coordinates of the lower right corner. areaProc must return -1 if the
363 item lies entirely outside the given area, 0 if it lies partially in‐
364 side and partially outside the area, and 1 if it lies entirely inside
365 the area.
366 POSTSCRIPTPROC
368 typePtr->postscriptProc is invoked by Tk to generate Postscript for an
369 item during the postscript widget command. If the type manager is not
370 capable of generating Postscript then typePtr->postscriptProc should be
371 NULL. The procedure must match the following prototype:
372 typedef int Tk_ItemPostscriptProc(
374 Tcl_Interp *interp,
375 Tk_Canvas canvas,
376 Tk_Item *itemPtr,
377 int prepass);
378 The interp, canvas, and itemPtr arguments all have standard meanings;
380 prepass will be described below. If postscriptProc completes success‐
381 fully, it should append Postscript for the item to the information in
382 the interpreter result (e.g. by calling Tcl_AppendResult, not Tcl_Se‐
383 tResult) and return TCL_OK. If an error occurs, postscriptProc should
384 clear the result and replace its contents with an error message; then
385 it should return TCL_ERROR.
386 Tk provides a collection of utility procedures to simplify postscript‐
388 Proc. For example, Tk_CanvasPsColor will generate Postscript to set
389 the current color to a given Tk color and Tk_CanvasPsFont will set up
390 font information. When generating Postscript, the type manager is free
391 to change the graphics state of the Postscript interpreter, since Tk
392 places gsave and grestore commands around the Postscript for the item.
393 The type manager can use canvas x coordinates directly in its Post‐
394 script, but it must call Tk_CanvasPsY to convert y coordinates from the
395 space of the canvas (where the origin is at the upper left) to the
396 space of Postscript (where the origin is at the lower left).
397 In order to generate Postscript that complies with the Adobe Document
399 Structuring Conventions, Tk actually generates Postscript in two
400 passes. It calls each item's postscriptProc in each pass. The only
401 purpose of the first pass is to collect font information (which is done
402 by Tk_CanvasPsFont); the actual Postscript is discarded. Tk sets the
403 prepass argument to postscriptProc to 1 during the first pass; the type
404 manager can use prepass to skip all Postscript generation except for
405 calls to Tk_CanvasPsFont. During the second pass prepass will be 0, so
406 the type manager must generate complete Postscript.
407 SCALEPROC
409 typePtr->scaleProc is invoked by Tk to rescale a canvas item during the
410 scale widget command. The procedure must match the following proto‐
411 type:
412 typedef void Tk_ItemScaleProc(
414 Tk_Canvas canvas,
415 Tk_Item *itemPtr,
416 double originX,
417 double originY,
418 double scaleX,
419 double scaleY);
420 The canvas and itemPtr arguments have the usual meaning. originX and
422 originY specify an origin relative to which the item is to be scaled,
423 and scaleX and scaleY give the x and y scale factors. The item should
424 adjust its coordinates so that a point in the item that used to have
425 coordinates x and y will have new coordinates x′ and y′, where
426 x′ = originX + scaleX × (x − originX)
428 y′ = originY + scaleY × (y − originY)
429 scaleProc must also update the bounding box in the item's header.
431 TRANSLATEPROC
433 typePtr->translateProc is invoked by Tk to translate a canvas item dur‐
434 ing the move widget command. The procedure must match the following
435 prototype:
436 typedef void Tk_ItemTranslateProc(
438 Tk_Canvas canvas,
439 Tk_Item *itemPtr,
440 double deltaX,
441 double deltaY);
442 The canvas and itemPtr arguments have the usual meaning, and deltaX and
444 deltaY give the amounts that should be added to each x and y coordinate
445 within the item. The type manager should adjust the item's coordinates
446 and update the bounding box in the item's header.
447 INDEXPROC
449 typePtr->indexProc is invoked by Tk to translate a string index speci‐
450 fication into a numerical index, for example during the index widget
451 command. It is only relevant for item types that support indexable
452 text or coordinates; typePtr->indexProc may be specified as NULL for
453 non-textual item types if they do not support detailed coordinate ad‐
454 dressing. The procedure must match the following prototype:
455 typedef int Tk_ItemIndexProc(
457 Tcl_Interp *interp,
458 Tk_Canvas canvas,
459 Tk_Item *itemPtr,
460 Tcl_Obj *indexObj,
461 int *indexPtr);
462 The interp, canvas, and itemPtr arguments all have the usual meaning.
464 indexObj contains a textual description of an index, and indexPtr
465 points to an integer value that should be filled in with a numerical
466 index. Note that if TK_CONFIG_OBJS is not set in the typePtr->al‐
467 waysRedraw field, the indexObj parameter will actually contain a
468 pointer to a constant string. It is up to the type manager to decide
469 what forms of index are supported (e.g., numbers, insert, sel.first,
470 end, etc.). indexProc should return a Tcl completion code and set the
471 interpreter result in the event of an error.
472 ICURSORPROC
474 typePtr->icursorProc is invoked by Tk during the icursor widget command
475 to set the position of the insertion cursor in a textual item. It is
476 only relevant for item types that support an insertion cursor; type‐
477 Ptr->icursorProc may be specified as NULL for item types that do not
478 support an insertion cursor. The procedure must match the following
479 prototype:
480 typedef void Tk_ItemCursorProc(
482 Tk_Canvas canvas,
483 Tk_Item *itemPtr,
484 int index);
485 canvas and itemPtr have the usual meanings, and index is an index into
487 the item's text, as returned by a previous call to typePtr->insertProc.
488 The type manager should position the insertion cursor in the item just
489 before the character given by index. Whether or not to actually dis‐
490 play the insertion cursor is determined by other information provided
491 by Tk_CanvasGetTextInfo.
492 SELECTIONPROC
494 typePtr->selectionProc is invoked by Tk during selection retrievals; it
495 must return part or all of the selected text in the item (if any). It
496 is only relevant for item types that support text; typePtr->selection‐
497 Proc may be specified as NULL for non-textual item types. The proce‐
498 dure must match the following prototype:
499 typedef int Tk_ItemSelectionProc(
501 Tk_Canvas canvas,
502 Tk_Item *itemPtr,
503 int offset,
504 char *buffer,
505 int maxBytes);
506 canvas and itemPtr have the usual meanings. offset is an offset in
508 bytes into the selection where 0 refers to the first byte of the selec‐
509 tion; it identifies the first character that is to be returned in this
510 call. buffer points to an area of memory in which to store the re‐
511 quested bytes, and maxBytes specifies the maximum number of bytes to
512 return. selectionProc should extract up to maxBytes characters from
513 the selection and copy them to maxBytes; it should return a count of
514 the number of bytes actually copied, which may be less than maxBytes if
515 there are not offset+maxBytes bytes in the selection.
516 INSERTPROC
518 typePtr->insertProc is invoked by Tk during the insert widget command
519 to insert new text or coordinates into a canvas item. It is only rele‐
520 vant for item types that support the insert method; typePtr->insertProc
521 may be specified as NULL for other item types. The procedure must
522 match the following prototype:
523 typedef void Tk_ItemInsertProc(
525 Tk_Canvas canvas,
526 Tk_Item *itemPtr,
527 int index,
528 Tcl_Obj *obj);
529 canvas and itemPtr have the usual meanings. index is an index into the
531 item's text, as returned by a previous call to typePtr->insertProc, and
532 obj contains new text to insert just before the character given by in‐
533 dex. Note that if TK_CONFIG_OBJS is not set in the typePtr->alwaysRe‐
534 draw field, the obj parameter will actually contain a pointer to a con‐
535 stant string to be inserted. If the item supports modification of the
536 coordinates list by this
537 The type manager should insert the text and recompute the bounding box
539 in the item's header.
540 DCHARSPROC
542 typePtr->dCharsProc is invoked by Tk during the dchars widget command
543 to delete a range of text from a canvas item or a range of coordinates
544 from a pathed item. It is only relevant for item types that support
545 text; typePtr->dCharsProc may be specified as NULL for non-textual item
546 types that do not want to support coordinate deletion. The procedure
547 must match the following prototype:
548 typedef void Tk_ItemDCharsProc(
550 Tk_Canvas canvas,
551 Tk_Item *itemPtr,
552 int first,
553 int last);
554 canvas and itemPtr have the usual meanings. first and last give the
556 indices of the first and last bytes to be deleted, as returned by pre‐
557 vious calls to typePtr->indexProc. The type manager should delete the
558 specified characters and update the bounding box in the item's header.
559
561 Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
562
564 canvas, focus, item type, selection, type manager
565Tk 4.0 Tk_CreateItemType(3)