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