summaryrefslogtreecommitdiffstats
path: root/doc/CrtItemType.3
blob: 8d5e35718505658945f3171beba560e4431b78f7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
'\"
'\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: CrtItemType.3,v 1.6 2000/07/25 21:14:34 jenglish Exp $
'\" 
.so man.macros
.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
\fBTk_CreateItemType\fR(\fItypePtr\fR)
.sp
Tk_ItemType *
\fBTk_GetItemTypes\fR()
.SH ARGUMENTS
.AS Tk_ItemType *typePtr
.AP Tk_ItemType *typePtr in
Structure that defines the new type of canvas item.
.BE

.SH INTRODUCTION
.PP
\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item
described by the \fItypePtr\fR argument.
An item type corresponds to a particular value of the \fItype\fR
argument to the \fBcreate\fR widget command for canvases, and
the code that implements a canvas item type is called a \fItype manager\fR.
Tk defines several built-in item types, such as \fBrectangle\fR
and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR
allows additional item types to be defined.
Once \fBTk_CreateItemType\fR returns, the new item type may be used
in new or existing canvas widgets just like the built-in item
types.
.PP
\fBTk_GetItemTypes\fR returns a pointer to the first in the list
of all item types currently defined for canvases.
The entries in the list are linked together through their
\fInextPtr\fR fields, with the end of the list marked by a
NULL \fInextPtr\fR.
.PP
You may find it easier to understand the rest of this manual entry
by looking at the code for an existing canvas item type such as
bitmap (file tkCanvBmap.c) or text (tkCanvText.c).
The easiest way to create a new type manager is to copy the code
for an existing type and modify it for the new type.
.PP
Tk provides a number of utility procedures for the use of canvas
type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR;
these are described in separate manual entries.

.SH "DATA STRUCTURES"
.PP
A type manager consists of a collection of procedures that provide a
standard set of operations on items of that type.
The type manager deals with three kinds of data
structures.
The first data structure is a Tk_ItemType; it contains
information such as the name of the type and pointers to
the standard procedures implemented by the type manager:
.CS
typedef struct Tk_ItemType {
	char *\fIname\fR;
	int \fIitemSize\fR;
	Tk_ItemCreateProc *\fIcreateProc\fR;
	Tk_ConfigSpec *\fIconfigSpecs\fR;
	Tk_ItemConfigureProc *\fIconfigProc\fR;
	Tk_ItemCoordProc *\fIcoordProc\fR;
	Tk_ItemDeleteProc *\fIdeleteProc\fR;
	Tk_ItemDisplayProc *\fIdisplayProc\fR;
	int \fIalwaysRedraw\fR;
	Tk_ItemPointProc *\fIpointProc\fR;
	Tk_ItemAreaProc *\fIareaProc\fR;
	Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
	Tk_ItemScaleProc *\fIscaleProc\fR;
	Tk_ItemTranslateProc *\fItranslateProc\fR;
	Tk_ItemIndexProc *\fIindexProc\fR;
	Tk_ItemCursorProc *\fIicursorProc\fR;
	Tk_ItemSelectionProc *\fIselectionProc\fR;
	Tk_ItemInsertProc *\fIinsertProc\fR;
	Tk_ItemDCharsProc *\fIdCharsProc\fR;
	Tk_ItemType *\fInextPtr\fR;
} Tk_ItemType;
.CE
.PP
The fields of a Tk_ItemType structure are described in more detail
later in this manual entry.
When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR
argument must point to a structure with all of the fields initialized
except \fInextPtr\fR, which Tk sets to link all the types together
into a list.
The structure must be in permanent memory (either statically
allocated or dynamically allocated but never freed);  Tk retains
a pointer to this structure.
.PP
The second data structure manipulated by a type manager is an
\fIitem record\fR.
For each item in a canvas there exists one item record.
All of the items of a given type generally have item records with
the same structure, but different types usually have different
formats for their item records.
The first part of each item record is a header with a standard structure
defined by Tk via the type Tk_Item;  the rest of the item
record is defined by the type manager.
A type manager must define its item records with a Tk_Item as
the first field.
For example, the item record for bitmap items is defined as follows:
.CS
typedef struct BitmapItem {
	Tk_Item \fIheader\fR;
	double \fIx\fR, \fIy\fR;
	Tk_Anchor \fIanchor\fR;
	Pixmap \fIbitmap\fR;
	XColor *\fIfgColor\fR;
	XColor *\fIbgColor\fR;
	GC \fIgc\fR;
} BitmapItem;
.CE
The \fIheader\fR substructure contains information used by Tk
to manage the item, such as its identifier, its tags, its type,
and its bounding box.
The fields starting with \fIx\fR belong to the type manager:
Tk will never read or write them.
The type manager should not need to read or write any of the
fields in the header except for four fields
whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
These fields give a bounding box for the items using integer
canvas coordinates:  the item should not cover any pixels
with x-coordinate lower than \fIx1\fR or y-coordinate
lower than \fIy1\fR, nor should it cover any pixels with
x-coordinate greater than or equal to \fIx2\fR or y-coordinate
greater than or equal to \fIy2\fR.
It is up to the type manager to keep the bounding box up to
date as the item is moved and reconfigured.
.PP
Whenever Tk calls a procedure in a type manager it passes in a pointer
to an item record.
The argument is always passed as a pointer to a Tk_Item;  the type
manager will typically cast this into a pointer to its own specific
type, such as BitmapItem.
.PP
The third data structure used by type managers has type
Tk_Canvas;  it serves as an opaque handle for the canvas widget
as a whole.
Type managers need not know anything about the contents of this
structure.
A Tk_Canvas handle is typically passed in to the
procedures of a type manager, and the type manager can pass the
handle back to library procedures such as Tk_CanvasTkwin
to fetch information about the canvas.

.SH NAME
.PP
This section and the ones that follow describe each of the fields
in a Tk_ItemType structure in detail.
The \fIname\fR field provides a string name for the item type.
Once \fBTk_CreateImageType\fR returns, this name may be used
in \fBcreate\fR widget commands to create items of the new
type.
If there already existed an item type by this name then
the new item type replaces the old one.

.SH ITEMSIZE
\fItypePtr->itemSize\fR gives the size in bytes of item records
of this type, including the Tk_Item header.
Tk uses this size to allocate memory space for items of the type.
All of the item records for a given type must have the same size.
If variable length fields are needed for an item (such as a list
of points for a polygon), the type manager can allocate a separate
object of variable length and keep a pointer to it in the item record.

.SH CREATEPROC
.PP
\fItypePtr->createProc\fR points to a procedure for
Tk to call whenever a new item of this type is created.
\fItypePtr->createProc\fR must match the following prototype:
.CS
typedef int Tk_ItemCreateProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIobjc\fR,
	Tcl_Obj* CONST \fIobjv\fR);
.CE
The \fIinterp\fR argument is the interpreter in which the canvas's
\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a
handle for the canvas widget.
\fIitemPtr\fR is a pointer to a newly-allocated item of
size \fItypePtr->itemSize\fR.
Tk has already initialized the item's header (the first
\fBsizeof(Tk_ItemType)\fR bytes).
The \fIobjc\fR and \fIobjv\fR arguments describe all of the
arguments to the \fBcreate\fR command after the \fItype\fR
argument.
For example, in the widget command
.CS
\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
.CE
\fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the
integer object \fB10\fR.
.PP
\fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize
the type-specific parts of the item record and set an initial value
for the bounding box in the item's header.
It should return a standard Tcl completion code and leave an
error message in \fIinterp->result\fR if an error occurs.
If an error occurs Tk will free the item record, so \fIcreateProc\fR
must be sure to leave the item record in a clean state if it returns an error
(e.g., it must free any additional memory that it allocated for
the item).

.SH CONFIGSPECS
.PP
Each type manager must provide a standard table describing its
configuration options, in a form suitable for use with
\fBTk_ConfigureWidget\fR.
This table will normally be used by \fItypePtr->createProc\fR
and \fItypePtr->configProc\fR, but Tk also uses it directly
to retrieve option information in the \fBitemcget\fR and
\fBitemconfigure\fR widget commands.
\fItypePtr->configSpecs\fR must point to the configuration table
for this type.
Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR
for implementing the \fB\-tags\fR option;  see an existing type
manager for an example of how to use it in \fIconfigSpecs\fR.

.SH CONFIGPROC
.PP
\fItypePtr->configProc\fR is called by Tk whenever the
\fBitemconfigure\fR widget command is invoked to change the
configuration options for a canvas item.
This procedure must match the following prototype:
.CS
typedef int Tk_ItemConfigureProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIobjc\fR,
	Tcl_Obj* CONST \fIobjv\fR,
	int \fIflags\fR);
.CE
The \fIinterp\fR objument identifies the interpreter in which the
widget command was invoked,  \fIcanvas\fR is a handle for the canvas
widget, and \fIitemPtr\fR is a pointer to the item being configured.
\fIobjc\fR and \fIobjv\fR contain the configuration options.  For
example, if the following command is invoked:
.CS
\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
.CE
\fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR
through \fBblack\fR.
\fIobjc\fR will always be an even value.
The  \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
currently this value is always TK_CONFIG_ARGV_ONLY when Tk
invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR
procedure will usually invoke \fIconfigProc\fR with different flag values.
.PP
\fItypePtr->configProc\fR returns a standard Tcl completion code and
leaves an error message in \fIinterp->result\fR if an error occurs.
It must update the item's bounding box to reflect the new configuration
options.

.SH COORDPROC
.PP
\fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
widget command for an item.
It must match the following prototype:
.CS
typedef int Tk_ItemCoordProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIobjc\fR,
	Tcl_Obj* CONST \fIobjv\fR);
.CE
The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
describe the coordinate arguments.
For example, if the following widget command is invoked:
.CS
\fB\&.c coords 2 30 90\fR
.CE
\fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects
\fB30\fR and \fB90\fR.
.PP
The \fIcoordProc\fR procedure should process the new coordinates,
update the item appropriately (e.g., it must reset the bounding
box in the item's header), and return a standard Tcl completion
code.
If an error occurs, \fIcoordProc\fR must leave an error message in
\fIinterp->result\fR.

.SH DELETEPROC
.PP
\fItypePtr->deleteProc\fR is invoked by Tk to delete an item
and free any resources allocated to it.
It must match the following prototype:
.CS
typedef void Tk_ItemDeleteProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	Display *\fIdisplay\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual
interpretations, and \fIdisplay\fR identifies the X display containing
the canvas.
\fIdeleteProc\fR must free up any resources allocated for the item,
so that Tk can free the item record.
\fIdeleteProc\fR should not actually free the item record;  this will
be done by Tk when \fIdeleteProc\fR returns.

.SH "DISPLAYPROC AND ALWAYSREDRAW"
.PP
\fItypePtr->displayProc\fR is invoked by Tk to redraw an item
on the screen.
It must match the following prototype:
.CS
typedef void Tk_ItemDisplayProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	Display *\fIdisplay\fR,
	Drawable \fIdst\fR,
	int \fIx\fR,
	int \fIy\fR,
	int \fIwidth\fR,
	int \fIheight\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
\fIdisplay\fR identifies the display containing the canvas, and
\fIdst\fR specifies a drawable in which the item should be rendered;
typically this is an off-screen pixmap, which Tk will copy into
the canvas's window once all relevant items have been drawn.
\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular
region in canvas coordinates, which is the area to be redrawn;
only information that overlaps this area needs to be redrawn.
Tk will not call \fIdisplayProc\fR unless the item's bounding box
overlaps the redraw area, but the type manager may wish to use
the redraw area to optimize the redisplay of the item.
.PP
Because of scrolling and the use of off-screen pixmaps for
double-buffered redisplay, the item's coordinates in \fIdst\fR
will not necessarily be the same as those in the canvas.
\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
to transform coordinates from those of the canvas to those
of \fIdst\fR.
.PP
Normally an item's \fIdisplayProc\fR is only invoked if the item
overlaps the area being displayed.
However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then
\fIdisplayProc\fR is invoked during every redisplay operation,
even if the item doesn't overlap the area of redisplay.
\fIalwaysRedraw\fR should normally be set to 0;  it is only
set to 1 in special cases such as window items that need to be
unmapped when they are off-screen.

.SH POINTPROC
.PP
\fItypePtr->pointProc\fR is invoked by Tk to find out how close
a given point is to a canvas item.
Tk uses this procedure for purposes such as locating the item
under the mouse or finding the closest item to a given point.
The procedure must match the following prototype:
.CS
typedef double Tk_ItemPointProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double *\fIpointPtr\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
\fIpointPtr\fR points to an array of two numbers giving
the x and y coordinates of a point.
\fIpointProc\fR must return a real value giving the distance
from the point to the item, or 0 if the point lies inside
the item.

.SH AREAPROC
.PP
\fItypePtr->areaProc\fR is invoked by Tk to find out the relationship
between an item and a rectangular area.
It must match the following prototype:
.CS
typedef int Tk_ItemAreaProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double *\fIrectPtr\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
\fIrectPtr\fR points to an array of four real numbers;
the first two give the x and y coordinates of the upper left
corner of a rectangle, and the second two give the x and y
coordinates of the lower right corner.
\fIareaProc\fR must return \-1 if the item lies entirely outside
the given area, 0 if it lies partially inside and partially
outside the area, and 1 if it lies entirely inside the area.

.SH POSTSCRIPTPROC
.PP
\fItypePtr->postscriptProc\fR is invoked by Tk to generate
Postcript for an item during the \fBpostscript\fR widget command.
If the type manager is not capable of generating Postscript then
\fItypePtr->postscriptProc\fR should be NULL.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemPostscriptProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIprepass\fR);
.CE
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have
standard meanings;  \fIprepass\fR will be described below.
If \fIpostscriptProc\fR completes successfully, it should append
Postscript for the item to the information in \fIinterp->result\fR
(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR)
and return TCL_OK.
If an error occurs, \fIpostscriptProc\fR should clear the result
and replace its contents with an error message;  then it should
return TCL_ERROR.
.PP
Tk provides a collection of utility procedures to simplify
\fIpostscriptProc\fR.
For example, \fBTk_CanvasPsColor\fR will generate Postscript to set
the current color to a given Tk color and \fBTk_CanvasPsFont\fR will
set up font information.
When generating Postscript, the type manager is free to change the
graphics state of the Postscript interpreter, since Tk places
\fBgsave\fR and \fBgrestore\fR commands around the Postscript for
the item.
The type manager can use canvas x coordinates directly in its Postscript,
but it must call \fBTk_CanvasPsY\fR to convert y coordinates from
the space of the canvas (where the origin is at the
upper left) to the space of Postscript (where the origin is at the
lower left).
.PP
In order to generate Postscript that complies with the Adobe Document
Structuring Conventions, Tk actually generates Postscript in two passes.
It calls each item's \fIpostscriptProc\fR in each pass.
The only purpose of the first pass is to collect font information
(which is done by \fBTk_CanvasPsFont\fR);  the actual Postscript is
discarded.
Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1
during the first pass;  the type manager can use \fIprepass\fR to skip
all Postscript generation except for calls to \fBTk_CanvasPsFont\fR.
During the second pass \fIprepass\fR will be 0, so the type manager
must generate complete Postscript.

.SH SCALEPROC
\fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item
during the \fBscale\fR widget command.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemScaleProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double \fIoriginX\fR,
	double \fIoriginY\fR,
	double \fIscaleX\fR,
	double \fIscaleY\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which
the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the
x and y scale factors.
The item should adjust its coordinates so that a point in the item
that used to have coordinates \fIx\fR and \fIy\fR will have new
coordinates \fIx'\fR and \fIy'\fR, where
.CS
\fIx' = originX  + scaleX*(x-originX)
y' = originY + scaleY*(y-originY)\fR
.CE
\fIscaleProc\fR must also update the bounding box in the item's
header.

.SH TRANSLATEPROC
\fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item
during the \fBmove\fR widget command.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemTranslateProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	double \fIdeltaX\fR,
	double \fIdeltaY\fR);
.CE
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning,
and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be
added to each x and y coordinate within the item.
The type manager should adjust the item's coordinates and
update the bounding box in the item's header.

.SH INDEXPROC
\fItypePtr->indexProc\fR is invoked by Tk to translate a string
index specification into a numerical index, for example during the
\fBindex\fR widget command.
It is only relevant for item types that support indexable text;
\fItypePtr->indexProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemIndexProc(
	Tcl_Interp *\fIinterp\fR,
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	char \fIindexString\fR,
	int *\fIindexPtr\fR);
.CE
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
have the usual meaning.
\fIindexString\fR contains a textual description of an index,
and \fIindexPtr\fR points to an integer value that should be
filled in with a numerical index.
It is up to the type manager to decide what forms of index
are supported (e.g., numbers, \fBinsert\fR,  \fBsel.first\fR,
\fBend\fR, etc.).
\fIindexProc\fR should return a Tcl completion code and set
\fIinterp->result\fR in the event of an error.

.SH ICURSORPROC
.PP
\fItypePtr->icursorProc\fR is invoked by Tk during
the \fBicursor\fR widget command to set the position of the
insertion cursor in a textual item.
It is only relevant for item types that support an insertion cursor;
\fItypePtr->icursorProc\fR may be specified as NULL for item types
that don't support an insertion cursor.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemCursorProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIindex\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and
\fIindex\fR is an index into the item's text, as returned by a
previous call to \fItypePtr->insertProc\fR.
The type manager should position the insertion cursor in the
item just before the character given by \fIindex\fR.
Whether or not to actually display the insertion cursor is
determined by other information provided by \fBTk_CanvasGetTextInfo\fR.

.SH SELECTIONPROC
.PP
\fItypePtr->selectionProc\fR is invoked by Tk during selection
retrievals;  it must return part or all of the selected text in
the item (if any).
It is only relevant for item types that support text;
\fItypePtr->selectionProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef int Tk_ItemSelectionProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIoffset\fR,
	char *\fIbuffer\fR,
	int \fImaxBytes\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
\fIoffset\fR is an offset in bytes into the selection where 0 refers
to the first byte of the selection;  it identifies
the first character that is to be returned in this call.
\fIbuffer\fR points to an area of memory in which to store the
requested bytes, and \fImaxBytes\fR specifies the maximum number
of bytes to return.
\fIselectionProc\fR should extract up to \fImaxBytes\fR characters
from the selection and copy them to \fImaxBytes\fR;  it should
return a count of the number of bytes actually copied, which may
be less than \fImaxBytes\fR if there aren't \fIoffset+maxBytes\fR bytes
in the selection.

.SH INSERTPROC
.PP
\fItypePtr->insertProc\fR is invoked by Tk during
the \fBinsert\fR widget command to insert new text into a
canvas item.
It is only relevant for item types that support text;
\fItypePtr->insertProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemInsertProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIindex\fR,
	char *\fIstring\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
\fIindex\fR is an index into the item's text, as returned by a
previous call to \fItypePtr->insertProc\fR, and \fIstring\fR
contains new text to insert just before the character given
by \fIindex\fR.
The type manager should insert the text and recompute the bounding
box in the item's header.

.SH DCHARSPROC
.PP
\fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR
widget command to delete a range of text from a canvas item.
It is only relevant for item types that support text;
\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual
item types.
The procedure must match the following prototype:
.CS
typedef void Tk_ItemDCharsProc(
	Tk_Canvas \fIcanvas\fR,
	Tk_Item *\fIitemPtr\fR,
	int \fIfirst\fR,
	int \fIlast\fR);
.CE
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes
to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR.
The type manager should delete the specified characters and update
the bounding box in the item's header.

.SH "SEE ALSO"
Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin

.SH KEYWORDS
canvas, focus, item type, selection, type manager