OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [tk/] [doc/] [CrtItemType.3] - Blame information for rev 1765

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
'\"
2
'\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
3
'\"
4
'\" See the file "license.terms" for information on usage and redistribution
5
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
6
'\"
7
'\" RCS: @(#) $Id: CrtItemType.3,v 1.1.1.1 2002-01-16 10:25:48 markom Exp $
8
'\"
9
.so man.macros
10
.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
11
.BS
12
.SH NAME
13
Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item
14
.SH SYNOPSIS
15
.nf
16
\fB#include \fR
17
.sp
18
\fBTk_CreateItemType\fR(\fItypePtr\fR)
19
.sp
20
Tk_ItemType *
21
\fBTk_GetItemTypes\fR()
22
.SH ARGUMENTS
23
.AS Tk_ItemType *typePtr
24
.AP Tk_ItemType *typePtr in
25
Structure that defines the new type of canvas item.
26
.BE
27
 
28
.SH INTRODUCTION
29
.PP
30
\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item
31
described by the \fItypePtr\fR argument.
32
An item type corresponds to a particular value of the \fItype\fR
33
argument to the \fBcreate\fR widget command for canvases, and
34
the code that implements a canvas item type is called a \fItype manager\fR.
35
Tk defines several built-in item types, such as \fBrectangle\fR
36
and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR
37
allows additional item types to be defined.
38
Once \fBTk_CreateItemType\fR returns, the new item type may be used
39
in new or existing canvas widgets just like the built-in item
40
types.
41
.PP
42
\fBTk_GetItemTypes\fR returns a pointer to the first in the list
43
of all item types currently defined for canvases.
44
The entries in the list are linked together through their
45
\fInextPtr\fR fields, with the end of the list marked by a
46
NULL \fInextPtr\fR.
47
.PP
48
You may find it easier to understand the rest of this manual entry
49
by looking at the code for an existing canvas item type such as
50
bitmap (file tkCanvBmap.c) or text (tkCanvText.c).
51
The easiest way to create a new type manager is to copy the code
52
for an existing type and modify it for the new type.
53
.PP
54
Tk provides a number of utility procedures for the use of canvas
55
type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR;
56
these are described in separate manual entries.
57
 
58
.SH "DATA STRUCTURES"
59
.PP
60
A type manager consists of a collection of procedures that provide a
61
standard set of operations on items of that type.
62
The type manager deals with three kinds of data
63
structures.
64
The first data structure is a Tk_ItemType; it contains
65
information such as the name of the type and pointers to
66
the standard procedures implemented by the type manager:
67
.CS
68
typedef struct Tk_ItemType {
69
        char *\fIname\fR;
70
        int \fIitemSize\fR;
71
        Tk_ItemCreateProc *\fIcreateProc\fR;
72
        Tk_ConfigSpec *\fIconfigSpecs\fR;
73
        Tk_ItemConfigureProc *\fIconfigProc\fR;
74
        Tk_ItemCoordProc *\fIcoordProc\fR;
75
        Tk_ItemDeleteProc *\fIdeleteProc\fR;
76
        Tk_ItemDisplayProc *\fIdisplayProc\fR;
77
        int \fIalwaysRedraw\fR;
78
        Tk_ItemPointProc *\fIpointProc\fR;
79
        Tk_ItemAreaProc *\fIareaProc\fR;
80
        Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
81
        Tk_ItemScaleProc *\fIscaleProc\fR;
82
        Tk_ItemTranslateProc *\fItranslateProc\fR;
83
        Tk_ItemIndexProc *\fIindexProc\fR;
84
        Tk_ItemCursorProc *\fIicursorProc\fR;
85
        Tk_ItemSelectionProc *\fIselectionProc\fR;
86
        Tk_ItemInsertProc *\fIinsertProc\fR;
87
        Tk_ItemDCharsProc *\fIdCharsProc\fR;
88
        Tk_ItemType *\fInextPtr\fR;
89
} Tk_ItemType;
90
.CE
91
.PP
92
The fields of a Tk_ItemType structure are described in more detail
93
later in this manual entry.
94
When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR
95
argument must point to a structure with all of the fields initialized
96
except \fInextPtr\fR, which Tk sets to link all the types together
97
into a list.
98
The structure must be in permanent memory (either statically
99
allocated or dynamically allocated but never freed);  Tk retains
100
a pointer to this structure.
101
.PP
102
The second data structure manipulated by a type manager is an
103
\fIitem record\fR.
104
For each item in a canvas there exists one item record.
105
All of the items of a given type generally have item records with
106
the same structure, but different types usually have different
107
formats for their item records.
108
The first part of each item record is a header with a standard structure
109
defined by Tk via the type Tk_Item;  the rest of the item
110
record is defined by the type manager.
111
A type manager must define its item records with a Tk_Item as
112
the first field.
113
For example, the item record for bitmap items is defined as follows:
114
.CS
115
typedef struct BitmapItem {
116
        Tk_Item \fIheader\fR;
117
        double \fIx\fR, \fIy\fR;
118
        Tk_Anchor \fIanchor\fR;
119
        Pixmap \fIbitmap\fR;
120
        XColor *\fIfgColor\fR;
121
        XColor *\fIbgColor\fR;
122
        GC \fIgc\fR;
123
} BitmapItem;
124
.CE
125
The \fIheader\fR substructure contains information used by Tk
126
to manage the item, such as its identifier, its tags, its type,
127
and its bounding box.
128
The fields starting with \fIx\fR belong to the type manager:
129
Tk will never read or write them.
130
The type manager should not need to read or write any of the
131
fields in the header except for four fields
132
whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
133
These fields give a bounding box for the items using integer
134
canvas coordinates:  the item should not cover any pixels
135
with x-coordinate lower than \fIx1\fR or y-coordinate
136
lower than \fIy1\fR, nor should it cover any pixels with
137
x-coordinate greater than or equal to \fIx2\fR or y-coordinate
138
greater than or equal to \fIy2\fR.
139
It is up to the type manager to keep the bounding box up to
140
date as the item is moved and reconfigured.
141
.PP
142
Whenever Tk calls a procedure in a type manager it passes in a pointer
143
to an item record.
144
The argument is always passed as a pointer to a Tk_Item;  the type
145
manager will typically cast this into a pointer to its own specific
146
type, such as BitmapItem.
147
.PP
148
The third data structure used by type managers has type
149
Tk_Canvas;  it serves as an opaque handle for the canvas widget
150
as a whole.
151
Type managers need not know anything about the contents of this
152
structure.
153
A Tk_Canvas handle is typically passed in to the
154
procedures of a type manager, and the type manager can pass the
155
handle back to library procedures such as Tk_CanvasTkwin
156
to fetch information about the canvas.
157
 
158
.SH NAME
159
.PP
160
This section and the ones that follow describe each of the fields
161
in a Tk_ItemType structure in detail.
162
The \fIname\fR field provides a string name for the item type.
163
Once \fBTk_CreateImageType\fR returns, this name may be used
164
in \fBcreate\fR widget commands to create items of the new
165
type.
166
If there already existed an item type by this name then
167
the new item type replaces the old one.
168
 
169
.SH ITEMSIZE
170
\fItypePtr->itemSize\fR gives the size in bytes of item records
171
of this type, including the Tk_Item header.
172
Tk uses this size to allocate memory space for items of the type.
173
All of the item records for a given type must have the same size.
174
If variable length fields are needed for an item (such as a list
175
of points for a polygon), the type manager can allocate a separate
176
object of variable length and keep a pointer to it in the item record.
177
 
178
.SH CREATEPROC
179
.PP
180
\fItypePtr->createProc\fR points to a procedure for
181
Tk to call whenever a new item of this type is created.
182
\fItypePtr->createProc\fR must match the following prototype:
183
.CS
184
typedef int Tk_ItemCreateProc(
185
        Tcl_Interp *\fIinterp\fR,
186
        Tk_Canvas \fIcanvas\fR,
187
        Tk_Item *\fIitemPtr\fR,
188
        int \fIargc\fR,
189
        char **\fIargv\fR);
190
.CE
191
The \fIinterp\fR argument is the interpreter in which the canvas's
192
\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a
193
handle for the canvas widget.
194
\fIitemPtr\fR is a pointer to a newly-allocated item of
195
size \fItypePtr->itemSize\fR.
196
Tk has already initialized the item's header (the first
197
\fBsizeof(Tk_ItemType)\fR bytes).
198
The \fIargc\fR and \fIargv\fR arguments describe all of the
199
arguments to the \fBcreate\fR command after the \fItype\fR
200
argument.
201
For example, in the widget command
202
.CS
203
\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
204
.CE
205
\fIargc\fR will be \fB6\fR and \fIargv\fR[0] will contain the
206
string \fB10\fR.
207
.PP
208
\fIcreateProc\fR should use \fIargc\fR and \fIargv\fR to initialize
209
the type-specific parts of the item record and set an initial value
210
for the bounding box in the item's header.
211
It should return a standard Tcl completion code and leave an
212
error message in \fIinterp->result\fR if an error occurs.
213
If an error occurs Tk will free the item record, so \fIcreateProc\fR
214
must be sure to leave the item record in a clean state if it returns an error
215
(e.g., it must free any additional memory that it allocated for
216
the item).
217
 
218
.SH CONFIGSPECS
219
.PP
220
Each type manager must provide a standard table describing its
221
configuration options, in a form suitable for use with
222
\fBTk_ConfigureWidget\fR.
223
This table will normally be used by \fItypePtr->createProc\fR
224
and \fItypePtr->configProc\fR, but Tk also uses it directly
225
to retrieve option information in the \fBitemcget\fR and
226
\fBitemconfigure\fR widget commands.
227
\fItypePtr->configSpecs\fR must point to the configuration table
228
for this type.
229
Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR
230
for implementing the \fB\-tags\fR option;  see an existing type
231
manager for an example of how to use it in \fIconfigSpecs\fR.
232
 
233
.SH CONFIGPROC
234
.PP
235
\fItypePtr->configProc\fR is called by Tk whenever the
236
\fBitemconfigure\fR widget command is invoked to change the
237
configuration options for a canvas item.
238
This procedure must match the following prototype:
239
.CS
240
typedef int Tk_ItemConfigureProc(
241
        Tcl_Interp *\fIinterp\fR,
242
        Tk_Canvas \fIcanvas\fR,
243
        Tk_Item *\fIitemPtr\fR,
244
        int \fIargc\fR,
245
        char **\fIargv\fR,
246
        int \fIflags\fR);
247
.CE
248
The \fIinterp\fR argument identifies the interpreter in which the
249
widget command was invoked,  \fIcanvas\fR is a handle for the canvas
250
widget, and \fIitemPtr\fR is a pointer to the item being configured.
251
\fIargc\fR and \fIargv\fR contain the configuration options.  For
252
example, if the following command is invoked:
253
.CS
254
\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
255
.CE
256
\fIargc\fR is \fB4\fR and \fIargv\fR contains the strings \fB\-fill\fR
257
through \fBblack\fR.
258
\fIargc\fR will always be an even value.
259
The  \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
260
currently this value is always TK_CONFIG_ARGV_ONLY when Tk
261
invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR
262
procedure will usually invoke \fIconfigProc\fR with different flag values.
263
.PP
264
\fItypePtr->configProc\fR returns a standard Tcl completion code and
265
leaves an error message in \fIinterp->result\fR if an error occurs.
266
It must update the item's bounding box to reflect the new configuration
267
options.
268
 
269
.SH COORDPROC
270
.PP
271
\fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
272
widget command for an item.
273
It must match the following prototype:
274
.CS
275
typedef int Tk_ItemCoordProc(
276
        Tcl_Interp *\fIinterp\fR,
277
        Tk_Canvas \fIcanvas\fR,
278
        Tk_Item *\fIitemPtr\fR,
279
        int \fIargc\fR,
280
        char **\fIargv\fR);
281
.CE
282
The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
283
all have the standard meanings, and \fIargc\fR and \fIargv\fR
284
describe the coordinate arguments.
285
For example, if the following widget command is invoked:
286
.CS
287
\fB\&.c coords 2 30 90\fR
288
.CE
289
\fIargc\fR will be \fB2\fR and \fBargv\fR will contain the string values
290
\fB30\fR and \fB90\fR.
291
.PP
292
The \fIcoordProc\fR procedure should process the new coordinates,
293
update the item appropriately (e.g., it must reset the bounding
294
box in the item's header), and return a standard Tcl completion
295
code.
296
If an error occurs, \fIcoordProc\fR must leave an error message in
297
\fIinterp->result\fR.
298
 
299
.SH DELETEPROC
300
.PP
301
\fItypePtr->deleteProc\fR is invoked by Tk to delete an item
302
and free any resources allocated to it.
303
It must match the following prototype:
304
.CS
305
typedef void Tk_ItemDeleteProc(
306
        Tk_Canvas \fIcanvas\fR,
307
        Tk_Item *\fIitemPtr\fR,
308
        Display *\fIdisplay\fR);
309
.CE
310
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual
311
interpretations, and \fIdisplay\fR identifies the X display containing
312
the canvas.
313
\fIdeleteProc\fR must free up any resources allocated for the item,
314
so that Tk can free the item record.
315
\fIdeleteProc\fR should not actually free the item record;  this will
316
be done by Tk when \fIdeleteProc\fR returns.
317
 
318
.SH "DISPLAYPROC AND ALWAYSREDRAW"
319
.PP
320
\fItypePtr->displayProc\fR is invoked by Tk to redraw an item
321
on the screen.
322
It must match the following prototype:
323
.CS
324
typedef void Tk_ItemDisplayProc(
325
        Tk_Canvas \fIcanvas\fR,
326
        Tk_Item *\fIitemPtr\fR,
327
        Display *\fIdisplay\fR,
328
        Drawable \fIdst\fR,
329
        int \fIx\fR,
330
        int \fIy\fR,
331
        int \fIwidth\fR,
332
        int \fIheight\fR);
333
.CE
334
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
335
\fIdisplay\fR identifies the display containing the canvas, and
336
\fIdst\fR specifies a drawable in which the item should be rendered;
337
typically this is an off-screen pixmap, which Tk will copy into
338
the canvas's window once all relevant items have been drawn.
339
\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular
340
region in canvas coordinates, which is the area to be redrawn;
341
only information that overlaps this area needs to be redrawn.
342
Tk will not call \fIdisplayProc\fR unless the item's bounding box
343
overlaps the redraw area, but the type manager may wish to use
344
the redraw area to optimize the redisplay of the item.
345
.PP
346
Because of scrolling and the use of off-screen pixmaps for
347
double-buffered redisplay, the item's coordinates in \fIdst\fR
348
will not necessarily be the same as those in the canvas.
349
\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
350
to transform coordinates from those of the canvas to those
351
of \fIdst\fR.
352
.PP
353
Normally an item's \fIdisplayProc\fR is only invoked if the item
354
overlaps the area being displayed.
355
However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then
356
\fIdisplayProc\fR is invoked during every redisplay operation,
357
even if the item doesn't overlap the area of redisplay.
358
\fIalwaysRedraw\fR should normally be set to 0;  it is only
359
set to 1 in special cases such as window items that need to be
360
unmapped when they are off-screen.
361
 
362
.SH POINTPROC
363
.PP
364
\fItypePtr->pointProc\fR is invoked by Tk to find out how close
365
a given point is to a canvas item.
366
Tk uses this procedure for purposes such as locating the item
367
under the mouse or finding the closest item to a given point.
368
The procedure must match the following prototype:
369
.CS
370
typedef double Tk_ItemPointProc(
371
        Tk_Canvas \fIcanvas\fR,
372
        Tk_Item *\fIitemPtr\fR,
373
        double *\fIpointPtr\fR);
374
.CE
375
\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
376
\fIpointPtr\fR points to an array of two numbers giving
377
the x and y coordinates of a point.
378
\fIpointProc\fR must return a real value giving the distance
379
from the point to the item, or 0 if the point lies inside
380
the item.
381
 
382
.SH AREAPROC
383
.PP
384
\fItypePtr->areaProc\fR is invoked by Tk to find out the relationship
385
between an item and a rectangular area.
386
It must match the following prototype:
387
.CS
388
typedef int Tk_ItemAreaProc(
389
        Tk_Canvas \fIcanvas\fR,
390
        Tk_Item *\fIitemPtr\fR,
391
        double *\fIrectPtr\fR);
392
.CE
393
\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
394
\fIrectPtr\fR points to an array of four real numbers;
395
the first two give the x and y coordinates of the upper left
396
corner of a rectangle, and the second two give the x and y
397
coordinates of the lower right corner.
398
\fIareaProc\fR must return \-1 if the item lies entirely outside
399
the given area, 0 if it lies partially inside and partially
400
outside the area, and 1 if it lies entirely inside the area.
401
 
402
.SH POSTSCRIPTPROC
403
.PP
404
\fItypePtr->postscriptProc\fR is invoked by Tk to generate
405
Postcript for an item during the \fBpostscript\fR widget command.
406
If the type manager is not capable of generating Postscript then
407
\fItypePtr->postscriptProc\fR should be NULL.
408
The procedure must match the following prototype:
409
.CS
410
typedef int Tk_ItemPostscriptProc(
411
        Tcl_Interp *\fIinterp\fR,
412
        Tk_Canvas \fIcanvas\fR,
413
        Tk_Item *\fIitemPtr\fR,
414
        int \fIprepass\fR);
415
.CE
416
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have
417
standard meanings;  \fIprepass\fR will be described below.
418
If \fIpostscriptProc\fR completes successfully, it should append
419
Postscript for the item to the information in \fIinterp->result\fR
420
(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR)
421
and return TCL_OK.
422
If an error occurs, \fIpostscriptProc\fR should clear the result
423
and replace its contents with an error message;  then it should
424
return TCL_ERROR.
425
.PP
426
Tk provides a collection of utility procedures to simplify
427
\fIpostscriptProc\fR.
428
For example, \fBTk_CanvasPsColor\fR will generate Postscript to set
429
the current color to a given Tk color and \fBTk_CanvasPsFont\fR will
430
set up font information.
431
When generating Postscript, the type manager is free to change the
432
graphics state of the Postscript interpreter, since Tk places
433
\fBgsave\fR and \fBgrestore\fR commands around the Postscript for
434
the item.
435
The type manager can use canvas x coordinates directly in its Postscript,
436
but it must call \fBTk_CanvasPsY\fR to convert y coordinates from
437
the space of the canvas (where the origin is at the
438
upper left) to the space of Postscript (where the origin is at the
439
lower left).
440
.PP
441
In order to generate Postscript that complies with the Adobe Document
442
Structuring Conventions, Tk actually generates Postscript in two passes.
443
It calls each item's \fIpostscriptProc\fR in each pass.
444
The only purpose of the first pass is to collect font information
445
(which is done by \fBTk_CanvPsFont\fR);  the actual Postscript is
446
discarded.
447
Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1
448
during the first pass;  the type manager can use \fIprepass\fR to skip
449
all Postscript generation except for calls to \fBTk_CanvasPsFont\fR.
450
During the second pass \fIprepass\fR will be 0, so the type manager
451
must generate complete Postscript.
452
 
453
.SH SCALEPROC
454
\fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item
455
during the \fBscale\fR widget command.
456
The procedure must match the following prototype:
457
.CS
458
typedef void Tk_ItemScaleProc(
459
        Tk_Canvas \fIcanvas\fR,
460
        Tk_Item *\fIitemPtr\fR,
461
        double \fIoriginX\fR,
462
        double \fIoriginY\fR,
463
        double \fIscaleX\fR,
464
        double \fIscaleY\fR);
465
.CE
466
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
467
\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which
468
the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the
469
x and y scale factors.
470
The item should adjust its coordinates so that a point in the item
471
that used to have coordinates \fIx\fR and \fIy\fR will have new
472
coordinates \fIx'\fR and \fIy'\fR, where
473
.CS
474
\fIx' = originX  + scaleX*(x-originX)
475
y' = originY + scaleY*(y-originY)\fR
476
.CE
477
\fIscaleProc\fR must also update the bounding box in the item's
478
header.
479
 
480
.SH TRANSLATEPROC
481
\fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item
482
during the \fBmove\fR widget command.
483
The procedure must match the following prototype:
484
.CS
485
typedef void Tk_ItemTranslateProc(
486
        Tk_Canvas \fIcanvas\fR,
487
        Tk_Item *\fIitemPtr\fR,
488
        double \fIdeltaX\fR,
489
        double \fIdeltaY\fR);
490
.CE
491
The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning,
492
and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be
493
added to each x and y coordinate within the item.
494
The type manager should adjust the item's coordinates and
495
update the bounding box in the item's header.
496
 
497
.SH INDEXPROC
498
\fItypePtr->indexProc\fR is invoked by Tk to translate a string
499
index specification into a numerical index, for example during the
500
\fBindex\fR widget command.
501
It is only relevant for item types that support indexable text;
502
\fItypePtr->indexProc\fR may be specified as NULL for non-textual
503
item types.
504
The procedure must match the following prototype:
505
.CS
506
typedef int Tk_ItemIndexProc(
507
        Tcl_Interp *\fIinterp\fR,
508
        Tk_Canvas \fIcanvas\fR,
509
        Tk_Item *\fIitemPtr\fR,
510
        char \fIindexString\fR,
511
        int *\fIindexPtr\fR);
512
.CE
513
The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
514
have the usual meaning.
515
\fIindexString\fR contains a textual description of an index,
516
and \fIindexPtr\fR points to an integer value that should be
517
filled in with a numerical index.
518
It is up to the type manager to decide what forms of index
519
are supported (e.g., numbers, \fBinsert\fR,  \fBsel.first\fR,
520
\fBend\fR, etc.).
521
\fIindexProc\fR should return a Tcl completion code and set
522
\fIinterp->result\fR in the event of an error.
523
 
524
.SH ICURSORPROC
525
.PP
526
\fItypePtr->icursorProc\fR is invoked by Tk during
527
the \fBicursor\fR widget command to set the position of the
528
insertion cursor in a textual item.
529
It is only relevant for item types that support an insertion cursor;
530
\fItypePtr->icursorProc\fR may be specified as NULL for item types
531
that don't support an insertion cursor.
532
The procedure must match the following prototype:
533
.CS
534
typedef void Tk_ItemIndexProc(
535
        Tk_Canvas \fIcanvas\fR,
536
        Tk_Item *\fIitemPtr\fR,
537
        int \fIindex\fR);
538
.CE
539
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and
540
\fIindex\fR is an index into the item's text, as returned by a
541
previous call to \fItypePtr->insertProc\fR.
542
The type manager should position the insertion cursor in the
543
item just before the character given by \fIindex\fR.
544
Whether or not to actually display the insertion cursor is
545
determined by other information provided by \fBTk_CanvasGetTextInfo\fR.
546
 
547
.SH SELECTIONPROC
548
.PP
549
\fItypePtr->selectionProc\fR is invoked by Tk during selection
550
retrievals;  it must return part or all of the selected text in
551
the item (if any).
552
It is only relevant for item types that support text;
553
\fItypePtr->selectionProc\fR may be specified as NULL for non-textual
554
item types.
555
The procedure must match the following prototype:
556
.CS
557
typedef int Tk_ItemSelectionProc(
558
        Tk_Canvas \fIcanvas\fR,
559
        Tk_Item *\fIitemPtr\fR,
560
        int \fIoffset\fR,
561
        char *\fIbuffer\fR,
562
        int \fImaxBytes\fR);
563
.CE
564
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
565
\fIoffset\fR is an offset in bytes into the selection where 0 refers
566
to the first byte of the selection;  it identifies
567
the first character that is to be returned in this call.
568
\fIbuffer\fR points to an area of memory in which to store the
569
requested bytes, and \fImaxBytes\fR specifies the maximum number
570
of bytes to return.
571
\fIselectionProc\fR should extract up to \fImaxBytes\fR characters
572
from the selection and copy them to \fImaxBytes\fR;  it should
573
return a count of the number of bytes actually copied, which may
574
be less than \fImaxBytes\fR if there aren't \fIoffset+maxBytes\fR bytes
575
in the selection.
576
 
577
.SH INSERTPROC
578
.PP
579
\fItypePtr->insertProc\fR is invoked by Tk during
580
the \fBinsert\fR widget command to insert new text into a
581
canvas item.
582
It is only relevant for item types that support text;
583
\fItypePtr->insertProc\fR may be specified as NULL for non-textual
584
item types.
585
The procedure must match the following prototype:
586
.CS
587
typedef void Tk_ItemInsertProc(
588
        Tk_Canvas \fIcanvas\fR,
589
        Tk_Item *\fIitemPtr\fR,
590
        int \fIindex\fR,
591
        char *\fIstring\fR);
592
.CE
593
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
594
\fIindex\fR is an index into the item's text, as returned by a
595
previous call to \fItypePtr->insertProc\fR, and \fIstring\fR
596
contains new text to insert just before the character given
597
by \fIindex\fR.
598
The type manager should insert the text and recompute the bounding
599
box in the item's header.
600
 
601
.SH DCHARSPROC
602
.PP
603
\fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR
604
widget command to delete a range of text from a canvas item.
605
It is only relevant for item types that support text;
606
\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual
607
item types.
608
The procedure must match the following prototype:
609
.CS
610
typedef void Tk_ItemDCharsProc(
611
        Tk_Canvas \fIcanvas\fR,
612
        Tk_Item *\fIitemPtr\fR,
613
        int \fIfirst\fR,
614
        int \fIlast\fR);
615
.CE
616
\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
617
\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes
618
to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR.
619
The type manager should delete the specified characters and update
620
the bounding box in the item's header.
621
 
622
.SH "SEE ALSO"
623
Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
624
 
625
.SH KEYWORDS
626
canvas, focus, item type, selection, type manager

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.