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
25 Tk_CreateItemType is invoked to define a new kind of canvas item
26 described by the typePtr argument. An item type corresponds to a par‐
27 ticular value of the type argument to the create widget command for
28 canvases, and the code that implements a canvas item type is called a
29 type manager. Tk defines several built-in item types, such as rectan‐
30 gle and text and image, but Tk_CreateItemType allows additional item
31 types to be defined. Once Tk_CreateItemType returns, the new item type
32 may be used in new or existing canvas widgets just like the built-in
33 item types.
34 Tk_GetItemTypes returns a pointer to the first in the list of all item
36 types currently defined for canvases. The entries in the list are
37 linked together through their nextPtr fields, with the end of the list
38 marked by a NULL nextPtr.
39 You may find it easier to understand the rest of this manual entry by
41 looking at the code for an existing canvas item type such as bitmap
42 (file tkCanvBmap.c) or text (tkCanvText.c). The easiest way to create
43 a new type manager is to copy the code for an existing type and modify
44 it for the new type.
45 Tk provides a number of utility procedures for the use of canvas type
47 managers, such as Tk_CanvasCoords and Tk_CanvasPsColor; these are
48 described in separate manual entries.
49
52 A type manager consists of a collection of procedures that provide a
53 standard set of operations on items of that type. The type manager
54 deals with three kinds of data structures. The first data structure is
55 a Tk_ItemType; it contains information such as the name of the type and
56 pointers to the standard procedures implemented by the type manager:
57 typedef struct Tk_ItemType {
58 char *name;
59 int itemSize;
60 Tk_ItemCreateProc *createProc;
61 Tk_ConfigSpec *configSpecs;
62 Tk_ItemConfigureProc *configProc;
63 Tk_ItemCoordProc *coordProc;
64 Tk_ItemDeleteProc *deleteProc;
65 Tk_ItemDisplayProc *displayProc;
66 int alwaysRedraw;
67 Tk_ItemPointProc *pointProc;
68 Tk_ItemAreaProc *areaProc;
69 Tk_ItemPostscriptProc *postscriptProc;
70 Tk_ItemScaleProc *scaleProc;
71 Tk_ItemTranslateProc *translateProc;
72 Tk_ItemIndexProc *indexProc;
73 Tk_ItemCursorProc *icursorProc;
74 Tk_ItemSelectionProc *selectionProc;
75 Tk_ItemInsertProc *insertProc;
76 Tk_ItemDCharsProc *dCharsProc;
77 Tk_ItemType *nextPtr;
78 } Tk_ItemType;
79 The fields of a Tk_ItemType structure are described in more detail
81 later in this manual entry. When Tk_CreateItemType is called, its
82 typePtr argument must point to a structure with all of the fields ini‐
83 tialized except nextPtr, which Tk sets to link all the types together
84 into a list. The structure must be in permanent memory (either stati‐
85 cally allocated or dynamically allocated but never freed); Tk retains
86 a pointer to this structure.
87 The second data structure manipulated by a type manager is an item
89 record. For each item in a canvas there exists one item record. All
90 of the items of a given type generally have item records with the same
91 structure, but different types usually have different formats for their
92 item records. The first part of each item record is a header with a
93 standard structure defined by Tk via the type Tk_Item; the rest of the
94 item record is defined by the type manager. A type manager must define
95 its item records with a Tk_Item as the first field. For example, the
96 item record for bitmap items is defined as follows:
97 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
107 item, such as its identifier, its tags, its type, and its bounding box.
108 The fields starting with x belong to the type manager: Tk will never
109 read or write them. The type manager should not need to read or write
110 any of the fields in the header except for four fields whose names are
111 x1, y1, x2, and y2. These fields give a bounding box for the items
112 using integer canvas coordinates: the item should not cover any pixels
113 with x-coordinate lower than x1 or y-coordinate lower than y1, nor
114 should it cover any pixels with x-coordinate greater than or equal to
115 x2 or y-coordinate greater than or equal to y2. It is up to the type
116 manager to keep the bounding box up to date as the item is moved and
117 reconfigured.
118 Whenever Tk calls a procedure in a type manager it passes in a pointer
120 to an item record. The argument is always passed as a pointer to a
121 Tk_Item; the type manager will typically cast this into a pointer to
122 its own specific type, such as BitmapItem.
123 The third data structure used by type managers has type Tk_Canvas; it
125 serves as an opaque handle for the canvas widget as a whole. Type man‐
126 agers need not know anything about the contents of this structure. A
127 Tk_Canvas handle is typically passed in to the procedures of a type
128 manager, and the type manager can pass the handle back to library pro‐
129 cedures such as Tk_CanvasTkwin to fetch information about the canvas.
130
133 This section and the ones that follow describe each of the fields in a
134 Tk_ItemType structure in detail. The name field provides a string name
135 for the item type. Once Tk_CreateImageType returns, this name may be
136 used in create widget commands to create items of the new type. If
137 there already existed an item type by this name then the new item type
138 replaces the old one.
139
142 typePtr->itemSize gives the size in bytes of item records of this type,
143 including the Tk_Item header. Tk uses this size to allocate memory
144 space for items of the type. All of the item records for a given type
145 must have the same size. If variable length fields are needed for an
146 item (such as a list of points for a polygon), the type manager can
147 allocate a separate object of variable length and keep a pointer to it
148 in the item record.
149
152 typePtr->createProc points to a procedure for Tk to call whenever a new
153 item of this type is created. typePtr->createProc must match the fol‐
154 lowing prototype:
155 typedef int Tk_ItemCreateProc(
156 Tcl_Interp *interp,
157 Tk_Canvas canvas,
158 Tk_Item *itemPtr,
159 int objc,
160 Tcl_Obj* CONST objv);
161 The interp argument is the interpreter in which the canvas's create
162 widget command was invoked, and canvas is a handle for the canvas wid‐
163 get. itemPtr is a pointer to a newly-allocated item of size type‐
164 Ptr->itemSize. Tk has already initialized the item's header (the first
165 sizeof(Tk_ItemType) bytes). The objc and objv arguments describe all
166 of the arguments to the create command after the type argument. For
167 example, in the widget command
168 .c create rectangle 10 20 50 50 -fill black
169 objc will be 6 and objv[0] will contain the integer object 10.
170 createProc should use objc and objv to initialize the type-specific
172 parts of the item record and set an initial value for the bounding box
173 in the item's header. It should return a standard Tcl completion code
174 and leave an error message in interp->result if an error occurs. If an
175 error occurs Tk will free the item record, so createProc must be sure
176 to leave the item record in a clean state if it returns an error (e.g.,
177 it must free any additional memory that it allocated for the item).
178
181 Each type manager must provide a standard table describing its configu‐
182 ration options, in a form suitable for use with Tk_ConfigureWidget.
183 This table will normally be used by typePtr->createProc and type‐
184 Ptr->configProc, but Tk also uses it directly to retrieve option infor‐
185 mation in the itemcget and itemconfigure widget commands. type‐
186 Ptr->configSpecs must point to the configuration table for this type.
187 Note: Tk provides a custom option type tk_CanvasTagsOption for imple‐
188 menting the -tags option; see an existing type manager for an example
189 of how to use it in configSpecs.
190
193 typePtr->configProc is called by Tk whenever the itemconfigure widget
194 command is invoked to change the configuration options for a canvas
195 item. This procedure must match the following prototype:
196 typedef int Tk_ItemConfigureProc(
197 Tcl_Interp *interp,
198 Tk_Canvas canvas,
199 Tk_Item *itemPtr,
200 int objc,
201 Tcl_Obj* CONST objv,
202 int flags);
203 The interp objument identifies the interpreter in which the widget com‐
204 mand was invoked, canvas is a handle for the canvas widget, and
205 itemPtr is a pointer to the item being configured. objc and objv con‐
206 tain the configuration options. For example, if the following command
207 is invoked:
208 .c itemconfigure 2 -fill red -outline black
209 objc is 4 and objv contains the string objects -fill through black.
210 objc will always be an even value. The flags argument contains flags
211 to pass to Tk_ConfigureWidget; currently this value is always TK_CON‐
212 FIG_ARGV_ONLY when Tk invokes typePtr->configProc, but the type man‐
213 ager's createProc procedure will usually invoke configProc with differ‐
214 ent flag values.
215 typePtr->configProc returns a standard Tcl completion code and leaves
217 an error message in interp->result if an error occurs. It must update
218 the item's bounding box to reflect the new configuration options.
219
222 typePtr->coordProc is invoked by Tk to implement the coords widget com‐
223 mand for an item. It must match the following prototype:
224 typedef int Tk_ItemCoordProc(
225 Tcl_Interp *interp,
226 Tk_Canvas canvas,
227 Tk_Item *itemPtr,
228 int objc,
229 Tcl_Obj* CONST objv);
230 The arguments interp, canvas, and itemPtr all have the standard mean‐
231 ings, and objc and objv describe the coordinate arguments. For exam‐
232 ple, if the following widget command is invoked:
233 .c coords 2 30 90
234 objc will be 2 and objv will contain the integer objects 30 and 90.
235 The coordProc procedure should process the new coordinates, update the
237 item appropriately (e.g., it must reset the bounding box in the item's
238 header), and return a standard Tcl completion code. If an error
239 occurs, coordProc must leave an error message in interp->result.
240
243 typePtr->deleteProc is invoked by Tk to delete an item and free any
244 resources allocated to it. It must match the following prototype:
245 typedef void Tk_ItemDeleteProc(
246 Tk_Canvas canvas,
247 Tk_Item *itemPtr,
248 Display *display);
249 The canvas and itemPtr arguments have the usual interpretations, and
250 display identifies the X display containing the canvas. deleteProc
251 must free up any resources allocated for the item, so that Tk can free
252 the item record. deleteProc should not actually free the item record;
253 this will be done by Tk when deleteProc returns.
254
257 typePtr->displayProc is invoked by Tk to redraw an item on the screen.
258 It must match the following prototype:
259 typedef void Tk_ItemDisplayProc(
260 Tk_Canvas canvas,
261 Tk_Item *itemPtr,
262 Display *display,
263 Drawable dst,
264 int x,
265 int y,
266 int width,
267 int height);
268 The canvas and itemPtr arguments have the usual meaning. display iden‐
269 tifies the display containing the canvas, and dst specifies a drawable
270 in which the item should be rendered; typically this is an off-screen
271 pixmap, which Tk will copy into the canvas's window once all relevant
272 items have been drawn. x, y, width, and height specify a rectangular
273 region in canvas coordinates, which is the area to be redrawn; only
274 information that overlaps this area needs to be redrawn. Tk will not
275 call displayProc unless the item's bounding box overlaps the redraw
276 area, but the type manager may wish to use the redraw area to optimize
277 the redisplay of the item.
278 Because of scrolling and the use of off-screen pixmaps for double-
280 buffered redisplay, the item's coordinates in dst will not necessarily
281 be the same as those in the canvas. displayProc should call Tk_Canvas‐
282 DrawableCoords to transform coordinates from those of the canvas to
283 those of dst.
284 Normally an item's displayProc is only invoked if the item overlaps the
286 area being displayed. However, if typePtr->alwaysRedraw has a non-zero
287 value, then displayProc is invoked during every redisplay operation,
288 even if the item doesn't overlap the area of redisplay. alwaysRedraw
289 should normally be set to 0; it is only set to 1 in special cases such
290 as window items that need to be unmapped when they are off-screen.
291
294 typePtr->pointProc is invoked by Tk to find out how close a given point
295 is to a canvas item. Tk uses this procedure for purposes such as
296 locating the item under the mouse or finding the closest item to a
297 given point. The procedure must match the following prototype:
298 typedef double Tk_ItemPointProc(
299 Tk_Canvas canvas,
300 Tk_Item *itemPtr,
301 double *pointPtr);
302 canvas and itemPtr have the usual meaning. pointPtr points to an array
303 of two numbers giving the x and y coordinates of a point. pointProc
304 must return a real value giving the distance from the point to the
305 item, or 0 if the point lies inside the item.
306
309 typePtr->areaProc is invoked by Tk to find out the relationship between
310 an item and a rectangular area. It must match the following prototype:
311 typedef int Tk_ItemAreaProc(
312 Tk_Canvas canvas,
313 Tk_Item *itemPtr,
314 double *rectPtr);
315 canvas and itemPtr have the usual meaning. rectPtr points to an array
316 of four real numbers; the first two give the x and y coordinates of the
317 upper left corner of a rectangle, and the second two give the x and y
318 coordinates of the lower right corner. areaProc must return -1 if the
319 item lies entirely outside the given area, 0 if it lies partially
320 inside and partially outside the area, and 1 if it lies entirely inside
321 the area.
322
325 typePtr->postscriptProc is invoked by Tk to generate Postcript for an
326 item during the postscript widget command. If the type manager is not
327 capable of generating Postscript then typePtr->postscriptProc should be
328 NULL. The procedure must match the following prototype:
329 typedef int Tk_ItemPostscriptProc(
330 Tcl_Interp *interp,
331 Tk_Canvas canvas,
332 Tk_Item *itemPtr,
333 int prepass);
334 The interp, canvas, and itemPtr arguments all have standard meanings;
335 prepass will be described below. If postscriptProc completes success‐
336 fully, it should append Postscript for the item to the information in
337 interp->result (e.g. by calling Tcl_AppendResult, not Tcl_SetResult)
338 and return TCL_OK. If an error occurs, postscriptProc should clear the
339 result and replace its contents with an error message; then it should
340 return TCL_ERROR.
341 Tk provides a collection of utility procedures to simplify postscript‐
343 Proc. For example, Tk_CanvasPsColor will generate Postscript to set
344 the current color to a given Tk color and Tk_CanvasPsFont will set up
345 font information. When generating Postscript, the type manager is free
346 to change the graphics state of the Postscript interpreter, since Tk
347 places gsave and grestore commands around the Postscript for the item.
348 The type manager can use canvas x coordinates directly in its Post‐
349 script, but it must call Tk_CanvasPsY to convert y coordinates from the
350 space of the canvas (where the origin is at the upper left) to the
351 space of Postscript (where the origin is at the lower left).
352 In order to generate Postscript that complies with the Adobe Document
354 Structuring Conventions, Tk actually generates Postscript in two
355 passes. It calls each item's postscriptProc in each pass. The only
356 purpose of the first pass is to collect font information (which is done
357 by Tk_CanvasPsFont); the actual Postscript is discarded. Tk sets the
358 prepass argument to postscriptProc to 1 during the first pass; the
359 type manager can use prepass to skip all Postscript generation except
360 for calls to Tk_CanvasPsFont. During the second pass prepass will be
361 0, so the type manager must generate complete Postscript.
362
365 typePtr->scaleProc is invoked by Tk to rescale a canvas item during the
366 scale widget command. The procedure must match the following proto‐
367 type:
368 typedef void Tk_ItemScaleProc(
369 Tk_Canvas canvas,
370 Tk_Item *itemPtr,
371 double originX,
372 double originY,
373 double scaleX,
374 double scaleY);
375 The canvas and itemPtr arguments have the usual meaning. originX and
376 originY specify an origin relative to which the item is to be scaled,
377 and scaleX and scaleY give the x and y scale factors. The item should
378 adjust its coordinates so that a point in the item that used to have
379 coordinates x and y will have new coordinates x' and y', where
380 x' = originX + scaleX*(x-originX)
381 y' = originY + scaleY*(y-originY)
382 scaleProc must also update the bounding box in the item's header.
383
386 typePtr->translateProc is invoked by Tk to translate a canvas item dur‐
387 ing the move widget command. The procedure must match the following
388 prototype:
389 typedef void Tk_ItemTranslateProc(
390 Tk_Canvas canvas,
391 Tk_Item *itemPtr,
392 double deltaX,
393 double deltaY);
394 The canvas and itemPtr arguments have the usual meaning, and deltaX and
395 deltaY give the amounts that should be added to each x and y coordinate
396 within the item. The type manager should adjust the item's coordinates
397 and update the bounding box in the item's header.
398
401 typePtr->indexProc is invoked by Tk to translate a string index speci‐
402 fication into a numerical index, for example during the index widget
403 command. It is only relevant for item types that support indexable
404 text; typePtr->indexProc may be specified as NULL for non-textual item
405 types. The procedure must match the following prototype:
406 typedef int Tk_ItemIndexProc(
407 Tcl_Interp *interp,
408 Tk_Canvas canvas,
409 Tk_Item *itemPtr,
410 char indexString,
411 int *indexPtr);
412 The interp, canvas, and itemPtr arguments all have the usual meaning.
413 indexString contains a textual description of an index, and indexPtr
414 points to an integer value that should be filled in with a numerical
415 index. It is up to the type manager to decide what forms of index are
416 supported (e.g., numbers, insert, sel.first, end, etc.). indexProc
417 should return a Tcl completion code and set interp->result in the event
418 of an error.
419
422 typePtr->icursorProc is invoked by Tk during the icursor widget command
423 to set the position of the insertion cursor in a textual item. It is
424 only relevant for item types that support an insertion cursor; type‐
425 Ptr->icursorProc may be specified as NULL for item types that don't
426 support an insertion cursor. The procedure must match the following
427 prototype:
428 typedef void Tk_ItemCursorProc(
429 Tk_Canvas canvas,
430 Tk_Item *itemPtr,
431 int index);
432 canvas and itemPtr have the usual meanings, and index is an index into
433 the item's text, as returned by a previous call to typePtr->insertProc.
434 The type manager should position the insertion cursor in the item just
435 before the character given by index. Whether or not to actually dis‐
436 play the insertion cursor is determined by other information provided
437 by Tk_CanvasGetTextInfo.
438
441 typePtr->selectionProc is invoked by Tk during selection retrievals;
442 it must return part or all of the selected text in the item (if any).
443 It is only relevant for item types that support text; typePtr->selec‐
444 tionProc may be specified as NULL for non-textual item types. The pro‐
445 cedure must match the following prototype:
446 typedef int Tk_ItemSelectionProc(
447 Tk_Canvas canvas,
448 Tk_Item *itemPtr,
449 int offset,
450 char *buffer,
451 int maxBytes);
452 canvas and itemPtr have the usual meanings. offset is an offset in
453 bytes into the selection where 0 refers to the first byte of the selec‐
454 tion; it identifies the first character that is to be returned in this
455 call. buffer points to an area of memory in which to store the
456 requested bytes, and maxBytes specifies the maximum number of bytes to
457 return. selectionProc should extract up to maxBytes characters from
458 the selection and copy them to maxBytes; it should return a count of
459 the number of bytes actually copied, which may be less than maxBytes if
460 there aren't offset+maxBytes bytes in the selection.
461
464 typePtr->insertProc is invoked by Tk during the insert widget command
465 to insert new text into a canvas item. It is only relevant for item
466 types that support text; typePtr->insertProc may be specified as NULL
467 for non-textual item types. The procedure must match the following
468 prototype:
469 typedef void Tk_ItemInsertProc(
470 Tk_Canvas canvas,
471 Tk_Item *itemPtr,
472 int index,
473 char *string);
474 canvas and itemPtr have the usual meanings. index is an index into the
475 item's text, as returned by a previous call to typePtr->insertProc, and
476 string contains new text to insert just before the character given by
477 index. The type manager should insert the text and recompute the
478 bounding box in the item's header.
479
482 typePtr->dCharsProc is invoked by Tk during the dchars widget command
483 to delete a range of text from a canvas item. It is only relevant for
484 item types that support text; typePtr->dCharsProc may be specified as
485 NULL for non-textual item types. The procedure must match the follow‐
486 ing prototype:
487 typedef void Tk_ItemDCharsProc(
488 Tk_Canvas canvas,
489 Tk_Item *itemPtr,
490 int first,
491 int last);
492 canvas and itemPtr have the usual meanings. first and last give the
493 indices of the first and last bytes to be deleted, as returned by pre‐
494 vious calls to typePtr->indexProc. The type manager should delete the
495 specified characters and update the bounding box in the item's header.
496
499 Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
500
503 canvas, focus, item type, selection, type manager
504Tk 4.0 Tk_CreateItemType(3)