| 1 | '\" |
| 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.6 2000/07/25 21:14:34 jenglish Exp $ |
| 8 | '\" |
| 9 | '\" The definitions below are for supplemental macros used in Tcl/Tk |
| 10 | '\" manual entries. |
| 11 | '\" |
| 12 | '\" .AP type name in/out ?indent? |
| 13 | '\" Start paragraph describing an argument to a library procedure. |
| 14 | '\" type is type of argument (int, etc.), in/out is either "in", "out", |
| 15 | '\" or "in/out" to describe whether procedure reads or modifies arg, |
| 16 | '\" and indent is equivalent to second arg of .IP (shouldn't ever be |
| 17 | '\" needed; use .AS below instead) |
| 18 | '\" |
| 19 | '\" .AS ?type? ?name? |
| 20 | '\" Give maximum sizes of arguments for setting tab stops. Type and |
| 21 | '\" name are examples of largest possible arguments that will be passed |
| 22 | '\" to .AP later. If args are omitted, default tab stops are used. |
| 23 | '\" |
| 24 | '\" .BS |
| 25 | '\" Start box enclosure. From here until next .BE, everything will be |
| 26 | '\" enclosed in one large box. |
| 27 | '\" |
| 28 | '\" .BE |
| 29 | '\" End of box enclosure. |
| 30 | '\" |
| 31 | '\" .CS |
| 32 | '\" Begin code excerpt. |
| 33 | '\" |
| 34 | '\" .CE |
| 35 | '\" End code excerpt. |
| 36 | '\" |
| 37 | '\" .VS ?version? ?br? |
| 38 | '\" Begin vertical sidebar, for use in marking newly-changed parts |
| 39 | '\" of man pages. The first argument is ignored and used for recording |
| 40 | '\" the version when the .VS was added, so that the sidebars can be |
| 41 | '\" found and removed when they reach a certain age. If another argument |
| 42 | '\" is present, then a line break is forced before starting the sidebar. |
| 43 | '\" |
| 44 | '\" .VE |
| 45 | '\" End of vertical sidebar. |
| 46 | '\" |
| 47 | '\" .DS |
| 48 | '\" Begin an indented unfilled display. |
| 49 | '\" |
| 50 | '\" .DE |
| 51 | '\" End of indented unfilled display. |
| 52 | '\" |
| 53 | '\" .SO |
| 54 | '\" Start of list of standard options for a Tk widget. The |
| 55 | '\" options follow on successive lines, in four columns separated |
| 56 | '\" by tabs. |
| 57 | '\" |
| 58 | '\" .SE |
| 59 | '\" End of list of standard options for a Tk widget. |
| 60 | '\" |
| 61 | '\" .OP cmdName dbName dbClass |
| 62 | '\" Start of description of a specific option. cmdName gives the |
| 63 | '\" option's name as specified in the class command, dbName gives |
| 64 | '\" the option's name in the option database, and dbClass gives |
| 65 | '\" the option's class in the option database. |
| 66 | '\" |
| 67 | '\" .UL arg1 arg2 |
| 68 | '\" Print arg1 underlined, then print arg2 normally. |
| 69 | '\" |
| 70 | '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $ |
| 71 | '\" |
| 72 | '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. |
| 73 | .if t .wh -1.3i ^B |
| 74 | .nr ^l \n(.l |
| 75 | .ad b |
| 76 | '\" # Start an argument description |
| 77 | .de AP |
| 78 | .ie !"\\$4"" .TP \\$4 |
| 79 | .el \{\ |
| 80 | . ie !"\\$2"" .TP \\n()Cu |
| 81 | . el .TP 15 |
| 82 | .\} |
| 83 | .ta \\n()Au \\n()Bu |
| 84 | .ie !"\\$3"" \{\ |
| 85 | \&\\$1 \\fI\\$2\\fP (\\$3) |
| 86 | .\".b |
| 87 | .\} |
| 88 | .el \{\ |
| 89 | .br |
| 90 | .ie !"\\$2"" \{\ |
| 91 | \&\\$1 \\fI\\$2\\fP |
| 92 | .\} |
| 93 | .el \{\ |
| 94 | \&\\fI\\$1\\fP |
| 95 | .\} |
| 96 | .\} |
| 97 | .. |
| 98 | '\" # define tabbing values for .AP |
| 99 | .de AS |
| 100 | .nr )A 10n |
| 101 | .if !"\\$1"" .nr )A \\w'\\$1'u+3n |
| 102 | .nr )B \\n()Au+15n |
| 103 | .\" |
| 104 | .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n |
| 105 | .nr )C \\n()Bu+\\w'(in/out)'u+2n |
| 106 | .. |
| 107 | .AS Tcl_Interp Tcl_CreateInterp in/out |
| 108 | '\" # BS - start boxed text |
| 109 | '\" # ^y = starting y location |
| 110 | '\" # ^b = 1 |
| 111 | .de BS |
| 112 | .br |
| 113 | .mk ^y |
| 114 | .nr ^b 1u |
| 115 | .if n .nf |
| 116 | .if n .ti 0 |
| 117 | .if n \l'\\n(.lu\(ul' |
| 118 | .if n .fi |
| 119 | .. |
| 120 | '\" # BE - end boxed text (draw box now) |
| 121 | .de BE |
| 122 | .nf |
| 123 | .ti 0 |
| 124 | .mk ^t |
| 125 | .ie n \l'\\n(^lu\(ul' |
| 126 | .el \{\ |
| 127 | .\" Draw four-sided box normally, but don't draw top of |
| 128 | .\" box if the box started on an earlier page. |
| 129 | .ie !\\n(^b-1 \{\ |
| 130 | \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 131 | .\} |
| 132 | .el \}\ |
| 133 | \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul' |
| 134 | .\} |
| 135 | .\} |
| 136 | .fi |
| 137 | .br |
| 138 | .nr ^b 0 |
| 139 | .. |
| 140 | '\" # VS - start vertical sidebar |
| 141 | '\" # ^Y = starting y location |
| 142 | '\" # ^v = 1 (for troff; for nroff this doesn't matter) |
| 143 | .de VS |
| 144 | .if !"\\$2"" .br |
| 145 | .mk ^Y |
| 146 | .ie n 'mc \s12\(br\s0 |
| 147 | .el .nr ^v 1u |
| 148 | .. |
| 149 | '\" # VE - end of vertical sidebar |
| 150 | .de VE |
| 151 | .ie n 'mc |
| 152 | .el \{\ |
| 153 | .ev 2 |
| 154 | .nf |
| 155 | .ti 0 |
| 156 | .mk ^t |
| 157 | \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n' |
| 158 | .sp -1 |
| 159 | .fi |
| 160 | .ev |
| 161 | .\} |
| 162 | .nr ^v 0 |
| 163 | .. |
| 164 | '\" # Special macro to handle page bottom: finish off current |
| 165 | '\" # box/sidebar if in box/sidebar mode, then invoked standard |
| 166 | '\" # page bottom macro. |
| 167 | .de ^B |
| 168 | .ev 2 |
| 169 | 'ti 0 |
| 170 | 'nf |
| 171 | .mk ^t |
| 172 | .if \\n(^b \{\ |
| 173 | .\" Draw three-sided box if this is the box's first page, |
| 174 | .\" draw two sides but no top otherwise. |
| 175 | .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 176 | .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c |
| 177 | .\} |
| 178 | .if \\n(^v \{\ |
| 179 | .nr ^x \\n(^tu+1v-\\n(^Yu |
| 180 | \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c |
| 181 | .\} |
| 182 | .bp |
| 183 | 'fi |
| 184 | .ev |
| 185 | .if \\n(^b \{\ |
| 186 | .mk ^y |
| 187 | .nr ^b 2 |
| 188 | .\} |
| 189 | .if \\n(^v \{\ |
| 190 | .mk ^Y |
| 191 | .\} |
| 192 | .. |
| 193 | '\" # DS - begin display |
| 194 | .de DS |
| 195 | .RS |
| 196 | .nf |
| 197 | .sp |
| 198 | .. |
| 199 | '\" # DE - end display |
| 200 | .de DE |
| 201 | .fi |
| 202 | .RE |
| 203 | .sp |
| 204 | .. |
| 205 | '\" # SO - start of list of standard options |
| 206 | .de SO |
| 207 | .SH "STANDARD OPTIONS" |
| 208 | .LP |
| 209 | .nf |
| 210 | .ta 5.5c 11c |
| 211 | .ft B |
| 212 | .. |
| 213 | '\" # SE - end of list of standard options |
| 214 | .de SE |
| 215 | .fi |
| 216 | .ft R |
| 217 | .LP |
| 218 | See the \\fBoptions\\fR manual entry for details on the standard options. |
| 219 | .. |
| 220 | '\" # OP - start of full description for a single option |
| 221 | .de OP |
| 222 | .LP |
| 223 | .nf |
| 224 | .ta 4c |
| 225 | Command-Line Name: \\fB\\$1\\fR |
| 226 | Database Name: \\fB\\$2\\fR |
| 227 | Database Class: \\fB\\$3\\fR |
| 228 | .fi |
| 229 | .IP |
| 230 | .. |
| 231 | '\" # CS - begin code excerpt |
| 232 | .de CS |
| 233 | .RS |
| 234 | .nf |
| 235 | .ta .25i .5i .75i 1i |
| 236 | .. |
| 237 | '\" # CE - end code excerpt |
| 238 | .de CE |
| 239 | .fi |
| 240 | .RE |
| 241 | .. |
| 242 | .de UL |
| 243 | \\$1\l'|0\(ul'\\$2 |
| 244 | .. |
| 245 | .TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures" |
| 246 | .BS |
| 247 | .SH NAME |
| 248 | Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item |
| 249 | .SH SYNOPSIS |
| 250 | .nf |
| 251 | \fB#include <tk.h>\fR |
| 252 | .sp |
| 253 | \fBTk_CreateItemType\fR(\fItypePtr\fR) |
| 254 | .sp |
| 255 | Tk_ItemType * |
| 256 | \fBTk_GetItemTypes\fR() |
| 257 | .SH ARGUMENTS |
| 258 | .AS Tk_ItemType *typePtr |
| 259 | .AP Tk_ItemType *typePtr in |
| 260 | Structure that defines the new type of canvas item. |
| 261 | .BE |
| 262 | |
| 263 | .SH INTRODUCTION |
| 264 | .PP |
| 265 | \fBTk_CreateItemType\fR is invoked to define a new kind of canvas item |
| 266 | described by the \fItypePtr\fR argument. |
| 267 | An item type corresponds to a particular value of the \fItype\fR |
| 268 | argument to the \fBcreate\fR widget command for canvases, and |
| 269 | the code that implements a canvas item type is called a \fItype manager\fR. |
| 270 | Tk defines several built-in item types, such as \fBrectangle\fR |
| 271 | and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR |
| 272 | allows additional item types to be defined. |
| 273 | Once \fBTk_CreateItemType\fR returns, the new item type may be used |
| 274 | in new or existing canvas widgets just like the built-in item |
| 275 | types. |
| 276 | .PP |
| 277 | \fBTk_GetItemTypes\fR returns a pointer to the first in the list |
| 278 | of all item types currently defined for canvases. |
| 279 | The entries in the list are linked together through their |
| 280 | \fInextPtr\fR fields, with the end of the list marked by a |
| 281 | NULL \fInextPtr\fR. |
| 282 | .PP |
| 283 | You may find it easier to understand the rest of this manual entry |
| 284 | by looking at the code for an existing canvas item type such as |
| 285 | bitmap (file tkCanvBmap.c) or text (tkCanvText.c). |
| 286 | The easiest way to create a new type manager is to copy the code |
| 287 | for an existing type and modify it for the new type. |
| 288 | .PP |
| 289 | Tk provides a number of utility procedures for the use of canvas |
| 290 | type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR; |
| 291 | these are described in separate manual entries. |
| 292 | |
| 293 | .SH "DATA STRUCTURES" |
| 294 | .PP |
| 295 | A type manager consists of a collection of procedures that provide a |
| 296 | standard set of operations on items of that type. |
| 297 | The type manager deals with three kinds of data |
| 298 | structures. |
| 299 | The first data structure is a Tk_ItemType; it contains |
| 300 | information such as the name of the type and pointers to |
| 301 | the standard procedures implemented by the type manager: |
| 302 | .CS |
| 303 | typedef struct Tk_ItemType { |
| 304 | char *\fIname\fR; |
| 305 | int \fIitemSize\fR; |
| 306 | Tk_ItemCreateProc *\fIcreateProc\fR; |
| 307 | Tk_ConfigSpec *\fIconfigSpecs\fR; |
| 308 | Tk_ItemConfigureProc *\fIconfigProc\fR; |
| 309 | Tk_ItemCoordProc *\fIcoordProc\fR; |
| 310 | Tk_ItemDeleteProc *\fIdeleteProc\fR; |
| 311 | Tk_ItemDisplayProc *\fIdisplayProc\fR; |
| 312 | int \fIalwaysRedraw\fR; |
| 313 | Tk_ItemPointProc *\fIpointProc\fR; |
| 314 | Tk_ItemAreaProc *\fIareaProc\fR; |
| 315 | Tk_ItemPostscriptProc *\fIpostscriptProc\fR; |
| 316 | Tk_ItemScaleProc *\fIscaleProc\fR; |
| 317 | Tk_ItemTranslateProc *\fItranslateProc\fR; |
| 318 | Tk_ItemIndexProc *\fIindexProc\fR; |
| 319 | Tk_ItemCursorProc *\fIicursorProc\fR; |
| 320 | Tk_ItemSelectionProc *\fIselectionProc\fR; |
| 321 | Tk_ItemInsertProc *\fIinsertProc\fR; |
| 322 | Tk_ItemDCharsProc *\fIdCharsProc\fR; |
| 323 | Tk_ItemType *\fInextPtr\fR; |
| 324 | } Tk_ItemType; |
| 325 | .CE |
| 326 | .PP |
| 327 | The fields of a Tk_ItemType structure are described in more detail |
| 328 | later in this manual entry. |
| 329 | When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR |
| 330 | argument must point to a structure with all of the fields initialized |
| 331 | except \fInextPtr\fR, which Tk sets to link all the types together |
| 332 | into a list. |
| 333 | The structure must be in permanent memory (either statically |
| 334 | allocated or dynamically allocated but never freed); Tk retains |
| 335 | a pointer to this structure. |
| 336 | .PP |
| 337 | The second data structure manipulated by a type manager is an |
| 338 | \fIitem record\fR. |
| 339 | For each item in a canvas there exists one item record. |
| 340 | All of the items of a given type generally have item records with |
| 341 | the same structure, but different types usually have different |
| 342 | formats for their item records. |
| 343 | The first part of each item record is a header with a standard structure |
| 344 | defined by Tk via the type Tk_Item; the rest of the item |
| 345 | record is defined by the type manager. |
| 346 | A type manager must define its item records with a Tk_Item as |
| 347 | the first field. |
| 348 | For example, the item record for bitmap items is defined as follows: |
| 349 | .CS |
| 350 | typedef struct BitmapItem { |
| 351 | Tk_Item \fIheader\fR; |
| 352 | double \fIx\fR, \fIy\fR; |
| 353 | Tk_Anchor \fIanchor\fR; |
| 354 | Pixmap \fIbitmap\fR; |
| 355 | XColor *\fIfgColor\fR; |
| 356 | XColor *\fIbgColor\fR; |
| 357 | GC \fIgc\fR; |
| 358 | } BitmapItem; |
| 359 | .CE |
| 360 | The \fIheader\fR substructure contains information used by Tk |
| 361 | to manage the item, such as its identifier, its tags, its type, |
| 362 | and its bounding box. |
| 363 | The fields starting with \fIx\fR belong to the type manager: |
| 364 | Tk will never read or write them. |
| 365 | The type manager should not need to read or write any of the |
| 366 | fields in the header except for four fields |
| 367 | whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR. |
| 368 | These fields give a bounding box for the items using integer |
| 369 | canvas coordinates: the item should not cover any pixels |
| 370 | with x-coordinate lower than \fIx1\fR or y-coordinate |
| 371 | lower than \fIy1\fR, nor should it cover any pixels with |
| 372 | x-coordinate greater than or equal to \fIx2\fR or y-coordinate |
| 373 | greater than or equal to \fIy2\fR. |
| 374 | It is up to the type manager to keep the bounding box up to |
| 375 | date as the item is moved and reconfigured. |
| 376 | .PP |
| 377 | Whenever Tk calls a procedure in a type manager it passes in a pointer |
| 378 | to an item record. |
| 379 | The argument is always passed as a pointer to a Tk_Item; the type |
| 380 | manager will typically cast this into a pointer to its own specific |
| 381 | type, such as BitmapItem. |
| 382 | .PP |
| 383 | The third data structure used by type managers has type |
| 384 | Tk_Canvas; it serves as an opaque handle for the canvas widget |
| 385 | as a whole. |
| 386 | Type managers need not know anything about the contents of this |
| 387 | structure. |
| 388 | A Tk_Canvas handle is typically passed in to the |
| 389 | procedures of a type manager, and the type manager can pass the |
| 390 | handle back to library procedures such as Tk_CanvasTkwin |
| 391 | to fetch information about the canvas. |
| 392 | |
| 393 | .SH NAME |
| 394 | .PP |
| 395 | This section and the ones that follow describe each of the fields |
| 396 | in a Tk_ItemType structure in detail. |
| 397 | The \fIname\fR field provides a string name for the item type. |
| 398 | Once \fBTk_CreateImageType\fR returns, this name may be used |
| 399 | in \fBcreate\fR widget commands to create items of the new |
| 400 | type. |
| 401 | If there already existed an item type by this name then |
| 402 | the new item type replaces the old one. |
| 403 | |
| 404 | .SH ITEMSIZE |
| 405 | \fItypePtr->itemSize\fR gives the size in bytes of item records |
| 406 | of this type, including the Tk_Item header. |
| 407 | Tk uses this size to allocate memory space for items of the type. |
| 408 | All of the item records for a given type must have the same size. |
| 409 | If variable length fields are needed for an item (such as a list |
| 410 | of points for a polygon), the type manager can allocate a separate |
| 411 | object of variable length and keep a pointer to it in the item record. |
| 412 | |
| 413 | .SH CREATEPROC |
| 414 | .PP |
| 415 | \fItypePtr->createProc\fR points to a procedure for |
| 416 | Tk to call whenever a new item of this type is created. |
| 417 | \fItypePtr->createProc\fR must match the following prototype: |
| 418 | .CS |
| 419 | typedef int Tk_ItemCreateProc( |
| 420 | Tcl_Interp *\fIinterp\fR, |
| 421 | Tk_Canvas \fIcanvas\fR, |
| 422 | Tk_Item *\fIitemPtr\fR, |
| 423 | int \fIobjc\fR, |
| 424 | Tcl_Obj* CONST \fIobjv\fR); |
| 425 | .CE |
| 426 | The \fIinterp\fR argument is the interpreter in which the canvas's |
| 427 | \fBcreate\fR widget command was invoked, and \fIcanvas\fR is a |
| 428 | handle for the canvas widget. |
| 429 | \fIitemPtr\fR is a pointer to a newly-allocated item of |
| 430 | size \fItypePtr->itemSize\fR. |
| 431 | Tk has already initialized the item's header (the first |
| 432 | \fBsizeof(Tk_ItemType)\fR bytes). |
| 433 | The \fIobjc\fR and \fIobjv\fR arguments describe all of the |
| 434 | arguments to the \fBcreate\fR command after the \fItype\fR |
| 435 | argument. |
| 436 | For example, in the widget command |
| 437 | .CS |
| 438 | \fB\&.c create rectangle 10 20 50 50 \-fill black\fR |
| 439 | .CE |
| 440 | \fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the |
| 441 | integer object \fB10\fR. |
| 442 | .PP |
| 443 | \fIcreateProc\fR should use \fIobjc\fR and \fIobjv\fR to initialize |
| 444 | the type-specific parts of the item record and set an initial value |
| 445 | for the bounding box in the item's header. |
| 446 | It should return a standard Tcl completion code and leave an |
| 447 | error message in \fIinterp->result\fR if an error occurs. |
| 448 | If an error occurs Tk will free the item record, so \fIcreateProc\fR |
| 449 | must be sure to leave the item record in a clean state if it returns an error |
| 450 | (e.g., it must free any additional memory that it allocated for |
| 451 | the item). |
| 452 | |
| 453 | .SH CONFIGSPECS |
| 454 | .PP |
| 455 | Each type manager must provide a standard table describing its |
| 456 | configuration options, in a form suitable for use with |
| 457 | \fBTk_ConfigureWidget\fR. |
| 458 | This table will normally be used by \fItypePtr->createProc\fR |
| 459 | and \fItypePtr->configProc\fR, but Tk also uses it directly |
| 460 | to retrieve option information in the \fBitemcget\fR and |
| 461 | \fBitemconfigure\fR widget commands. |
| 462 | \fItypePtr->configSpecs\fR must point to the configuration table |
| 463 | for this type. |
| 464 | Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR |
| 465 | for implementing the \fB\-tags\fR option; see an existing type |
| 466 | manager for an example of how to use it in \fIconfigSpecs\fR. |
| 467 | |
| 468 | .SH CONFIGPROC |
| 469 | .PP |
| 470 | \fItypePtr->configProc\fR is called by Tk whenever the |
| 471 | \fBitemconfigure\fR widget command is invoked to change the |
| 472 | configuration options for a canvas item. |
| 473 | This procedure must match the following prototype: |
| 474 | .CS |
| 475 | typedef int Tk_ItemConfigureProc( |
| 476 | Tcl_Interp *\fIinterp\fR, |
| 477 | Tk_Canvas \fIcanvas\fR, |
| 478 | Tk_Item *\fIitemPtr\fR, |
| 479 | int \fIobjc\fR, |
| 480 | Tcl_Obj* CONST \fIobjv\fR, |
| 481 | int \fIflags\fR); |
| 482 | .CE |
| 483 | The \fIinterp\fR objument identifies the interpreter in which the |
| 484 | widget command was invoked, \fIcanvas\fR is a handle for the canvas |
| 485 | widget, and \fIitemPtr\fR is a pointer to the item being configured. |
| 486 | \fIobjc\fR and \fIobjv\fR contain the configuration options. For |
| 487 | example, if the following command is invoked: |
| 488 | .CS |
| 489 | \fB\&.c itemconfigure 2 \-fill red \-outline black\fR |
| 490 | .CE |
| 491 | \fIobjc\fR is \fB4\fR and \fIobjv\fR contains the string objects \fB\-fill\fR |
| 492 | through \fBblack\fR. |
| 493 | \fIobjc\fR will always be an even value. |
| 494 | The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR; |
| 495 | currently this value is always TK_CONFIG_ARGV_ONLY when Tk |
| 496 | invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR |
| 497 | procedure will usually invoke \fIconfigProc\fR with different flag values. |
| 498 | .PP |
| 499 | \fItypePtr->configProc\fR returns a standard Tcl completion code and |
| 500 | leaves an error message in \fIinterp->result\fR if an error occurs. |
| 501 | It must update the item's bounding box to reflect the new configuration |
| 502 | options. |
| 503 | |
| 504 | .SH COORDPROC |
| 505 | .PP |
| 506 | \fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR |
| 507 | widget command for an item. |
| 508 | It must match the following prototype: |
| 509 | .CS |
| 510 | typedef int Tk_ItemCoordProc( |
| 511 | Tcl_Interp *\fIinterp\fR, |
| 512 | Tk_Canvas \fIcanvas\fR, |
| 513 | Tk_Item *\fIitemPtr\fR, |
| 514 | int \fIobjc\fR, |
| 515 | Tcl_Obj* CONST \fIobjv\fR); |
| 516 | .CE |
| 517 | The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR |
| 518 | all have the standard meanings, and \fIobjc\fR and \fIobjv\fR |
| 519 | describe the coordinate arguments. |
| 520 | For example, if the following widget command is invoked: |
| 521 | .CS |
| 522 | \fB\&.c coords 2 30 90\fR |
| 523 | .CE |
| 524 | \fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects |
| 525 | \fB30\fR and \fB90\fR. |
| 526 | .PP |
| 527 | The \fIcoordProc\fR procedure should process the new coordinates, |
| 528 | update the item appropriately (e.g., it must reset the bounding |
| 529 | box in the item's header), and return a standard Tcl completion |
| 530 | code. |
| 531 | If an error occurs, \fIcoordProc\fR must leave an error message in |
| 532 | \fIinterp->result\fR. |
| 533 | |
| 534 | .SH DELETEPROC |
| 535 | .PP |
| 536 | \fItypePtr->deleteProc\fR is invoked by Tk to delete an item |
| 537 | and free any resources allocated to it. |
| 538 | It must match the following prototype: |
| 539 | .CS |
| 540 | typedef void Tk_ItemDeleteProc( |
| 541 | Tk_Canvas \fIcanvas\fR, |
| 542 | Tk_Item *\fIitemPtr\fR, |
| 543 | Display *\fIdisplay\fR); |
| 544 | .CE |
| 545 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual |
| 546 | interpretations, and \fIdisplay\fR identifies the X display containing |
| 547 | the canvas. |
| 548 | \fIdeleteProc\fR must free up any resources allocated for the item, |
| 549 | so that Tk can free the item record. |
| 550 | \fIdeleteProc\fR should not actually free the item record; this will |
| 551 | be done by Tk when \fIdeleteProc\fR returns. |
| 552 | |
| 553 | .SH "DISPLAYPROC AND ALWAYSREDRAW" |
| 554 | .PP |
| 555 | \fItypePtr->displayProc\fR is invoked by Tk to redraw an item |
| 556 | on the screen. |
| 557 | It must match the following prototype: |
| 558 | .CS |
| 559 | typedef void Tk_ItemDisplayProc( |
| 560 | Tk_Canvas \fIcanvas\fR, |
| 561 | Tk_Item *\fIitemPtr\fR, |
| 562 | Display *\fIdisplay\fR, |
| 563 | Drawable \fIdst\fR, |
| 564 | int \fIx\fR, |
| 565 | int \fIy\fR, |
| 566 | int \fIwidth\fR, |
| 567 | int \fIheight\fR); |
| 568 | .CE |
| 569 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. |
| 570 | \fIdisplay\fR identifies the display containing the canvas, and |
| 571 | \fIdst\fR specifies a drawable in which the item should be rendered; |
| 572 | typically this is an off-screen pixmap, which Tk will copy into |
| 573 | the canvas's window once all relevant items have been drawn. |
| 574 | \fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular |
| 575 | region in canvas coordinates, which is the area to be redrawn; |
| 576 | only information that overlaps this area needs to be redrawn. |
| 577 | Tk will not call \fIdisplayProc\fR unless the item's bounding box |
| 578 | overlaps the redraw area, but the type manager may wish to use |
| 579 | the redraw area to optimize the redisplay of the item. |
| 580 | .PP |
| 581 | Because of scrolling and the use of off-screen pixmaps for |
| 582 | double-buffered redisplay, the item's coordinates in \fIdst\fR |
| 583 | will not necessarily be the same as those in the canvas. |
| 584 | \fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR |
| 585 | to transform coordinates from those of the canvas to those |
| 586 | of \fIdst\fR. |
| 587 | .PP |
| 588 | Normally an item's \fIdisplayProc\fR is only invoked if the item |
| 589 | overlaps the area being displayed. |
| 590 | However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then |
| 591 | \fIdisplayProc\fR is invoked during every redisplay operation, |
| 592 | even if the item doesn't overlap the area of redisplay. |
| 593 | \fIalwaysRedraw\fR should normally be set to 0; it is only |
| 594 | set to 1 in special cases such as window items that need to be |
| 595 | unmapped when they are off-screen. |
| 596 | |
| 597 | .SH POINTPROC |
| 598 | .PP |
| 599 | \fItypePtr->pointProc\fR is invoked by Tk to find out how close |
| 600 | a given point is to a canvas item. |
| 601 | Tk uses this procedure for purposes such as locating the item |
| 602 | under the mouse or finding the closest item to a given point. |
| 603 | The procedure must match the following prototype: |
| 604 | .CS |
| 605 | typedef double Tk_ItemPointProc( |
| 606 | Tk_Canvas \fIcanvas\fR, |
| 607 | Tk_Item *\fIitemPtr\fR, |
| 608 | double *\fIpointPtr\fR); |
| 609 | .CE |
| 610 | \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. |
| 611 | \fIpointPtr\fR points to an array of two numbers giving |
| 612 | the x and y coordinates of a point. |
| 613 | \fIpointProc\fR must return a real value giving the distance |
| 614 | from the point to the item, or 0 if the point lies inside |
| 615 | the item. |
| 616 | |
| 617 | .SH AREAPROC |
| 618 | .PP |
| 619 | \fItypePtr->areaProc\fR is invoked by Tk to find out the relationship |
| 620 | between an item and a rectangular area. |
| 621 | It must match the following prototype: |
| 622 | .CS |
| 623 | typedef int Tk_ItemAreaProc( |
| 624 | Tk_Canvas \fIcanvas\fR, |
| 625 | Tk_Item *\fIitemPtr\fR, |
| 626 | double *\fIrectPtr\fR); |
| 627 | .CE |
| 628 | \fIcanvas\fR and \fIitemPtr\fR have the usual meaning. |
| 629 | \fIrectPtr\fR points to an array of four real numbers; |
| 630 | the first two give the x and y coordinates of the upper left |
| 631 | corner of a rectangle, and the second two give the x and y |
| 632 | coordinates of the lower right corner. |
| 633 | \fIareaProc\fR must return \-1 if the item lies entirely outside |
| 634 | the given area, 0 if it lies partially inside and partially |
| 635 | outside the area, and 1 if it lies entirely inside the area. |
| 636 | |
| 637 | .SH POSTSCRIPTPROC |
| 638 | .PP |
| 639 | \fItypePtr->postscriptProc\fR is invoked by Tk to generate |
| 640 | Postcript for an item during the \fBpostscript\fR widget command. |
| 641 | If the type manager is not capable of generating Postscript then |
| 642 | \fItypePtr->postscriptProc\fR should be NULL. |
| 643 | The procedure must match the following prototype: |
| 644 | .CS |
| 645 | typedef int Tk_ItemPostscriptProc( |
| 646 | Tcl_Interp *\fIinterp\fR, |
| 647 | Tk_Canvas \fIcanvas\fR, |
| 648 | Tk_Item *\fIitemPtr\fR, |
| 649 | int \fIprepass\fR); |
| 650 | .CE |
| 651 | The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have |
| 652 | standard meanings; \fIprepass\fR will be described below. |
| 653 | If \fIpostscriptProc\fR completes successfully, it should append |
| 654 | Postscript for the item to the information in \fIinterp->result\fR |
| 655 | (e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR) |
| 656 | and return TCL_OK. |
| 657 | If an error occurs, \fIpostscriptProc\fR should clear the result |
| 658 | and replace its contents with an error message; then it should |
| 659 | return TCL_ERROR. |
| 660 | .PP |
| 661 | Tk provides a collection of utility procedures to simplify |
| 662 | \fIpostscriptProc\fR. |
| 663 | For example, \fBTk_CanvasPsColor\fR will generate Postscript to set |
| 664 | the current color to a given Tk color and \fBTk_CanvasPsFont\fR will |
| 665 | set up font information. |
| 666 | When generating Postscript, the type manager is free to change the |
| 667 | graphics state of the Postscript interpreter, since Tk places |
| 668 | \fBgsave\fR and \fBgrestore\fR commands around the Postscript for |
| 669 | the item. |
| 670 | The type manager can use canvas x coordinates directly in its Postscript, |
| 671 | but it must call \fBTk_CanvasPsY\fR to convert y coordinates from |
| 672 | the space of the canvas (where the origin is at the |
| 673 | upper left) to the space of Postscript (where the origin is at the |
| 674 | lower left). |
| 675 | .PP |
| 676 | In order to generate Postscript that complies with the Adobe Document |
| 677 | Structuring Conventions, Tk actually generates Postscript in two passes. |
| 678 | It calls each item's \fIpostscriptProc\fR in each pass. |
| 679 | The only purpose of the first pass is to collect font information |
| 680 | (which is done by \fBTk_CanvasPsFont\fR); the actual Postscript is |
| 681 | discarded. |
| 682 | Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1 |
| 683 | during the first pass; the type manager can use \fIprepass\fR to skip |
| 684 | all Postscript generation except for calls to \fBTk_CanvasPsFont\fR. |
| 685 | During the second pass \fIprepass\fR will be 0, so the type manager |
| 686 | must generate complete Postscript. |
| 687 | |
| 688 | .SH SCALEPROC |
| 689 | \fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item |
| 690 | during the \fBscale\fR widget command. |
| 691 | The procedure must match the following prototype: |
| 692 | .CS |
| 693 | typedef void Tk_ItemScaleProc( |
| 694 | Tk_Canvas \fIcanvas\fR, |
| 695 | Tk_Item *\fIitemPtr\fR, |
| 696 | double \fIoriginX\fR, |
| 697 | double \fIoriginY\fR, |
| 698 | double \fIscaleX\fR, |
| 699 | double \fIscaleY\fR); |
| 700 | .CE |
| 701 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning. |
| 702 | \fIoriginX\fR and \fIoriginY\fR specify an origin relative to which |
| 703 | the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the |
| 704 | x and y scale factors. |
| 705 | The item should adjust its coordinates so that a point in the item |
| 706 | that used to have coordinates \fIx\fR and \fIy\fR will have new |
| 707 | coordinates \fIx'\fR and \fIy'\fR, where |
| 708 | .CS |
| 709 | \fIx' = originX + scaleX*(x-originX) |
| 710 | y' = originY + scaleY*(y-originY)\fR |
| 711 | .CE |
| 712 | \fIscaleProc\fR must also update the bounding box in the item's |
| 713 | header. |
| 714 | |
| 715 | .SH TRANSLATEPROC |
| 716 | \fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item |
| 717 | during the \fBmove\fR widget command. |
| 718 | The procedure must match the following prototype: |
| 719 | .CS |
| 720 | typedef void Tk_ItemTranslateProc( |
| 721 | Tk_Canvas \fIcanvas\fR, |
| 722 | Tk_Item *\fIitemPtr\fR, |
| 723 | double \fIdeltaX\fR, |
| 724 | double \fIdeltaY\fR); |
| 725 | .CE |
| 726 | The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning, |
| 727 | and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be |
| 728 | added to each x and y coordinate within the item. |
| 729 | The type manager should adjust the item's coordinates and |
| 730 | update the bounding box in the item's header. |
| 731 | |
| 732 | .SH INDEXPROC |
| 733 | \fItypePtr->indexProc\fR is invoked by Tk to translate a string |
| 734 | index specification into a numerical index, for example during the |
| 735 | \fBindex\fR widget command. |
| 736 | It is only relevant for item types that support indexable text; |
| 737 | \fItypePtr->indexProc\fR may be specified as NULL for non-textual |
| 738 | item types. |
| 739 | The procedure must match the following prototype: |
| 740 | .CS |
| 741 | typedef int Tk_ItemIndexProc( |
| 742 | Tcl_Interp *\fIinterp\fR, |
| 743 | Tk_Canvas \fIcanvas\fR, |
| 744 | Tk_Item *\fIitemPtr\fR, |
| 745 | char \fIindexString\fR, |
| 746 | int *\fIindexPtr\fR); |
| 747 | .CE |
| 748 | The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all |
| 749 | have the usual meaning. |
| 750 | \fIindexString\fR contains a textual description of an index, |
| 751 | and \fIindexPtr\fR points to an integer value that should be |
| 752 | filled in with a numerical index. |
| 753 | It is up to the type manager to decide what forms of index |
| 754 | are supported (e.g., numbers, \fBinsert\fR, \fBsel.first\fR, |
| 755 | \fBend\fR, etc.). |
| 756 | \fIindexProc\fR should return a Tcl completion code and set |
| 757 | \fIinterp->result\fR in the event of an error. |
| 758 | |
| 759 | .SH ICURSORPROC |
| 760 | .PP |
| 761 | \fItypePtr->icursorProc\fR is invoked by Tk during |
| 762 | the \fBicursor\fR widget command to set the position of the |
| 763 | insertion cursor in a textual item. |
| 764 | It is only relevant for item types that support an insertion cursor; |
| 765 | \fItypePtr->icursorProc\fR may be specified as NULL for item types |
| 766 | that don't support an insertion cursor. |
| 767 | The procedure must match the following prototype: |
| 768 | .CS |
| 769 | typedef void Tk_ItemCursorProc( |
| 770 | Tk_Canvas \fIcanvas\fR, |
| 771 | Tk_Item *\fIitemPtr\fR, |
| 772 | int \fIindex\fR); |
| 773 | .CE |
| 774 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and |
| 775 | \fIindex\fR is an index into the item's text, as returned by a |
| 776 | previous call to \fItypePtr->insertProc\fR. |
| 777 | The type manager should position the insertion cursor in the |
| 778 | item just before the character given by \fIindex\fR. |
| 779 | Whether or not to actually display the insertion cursor is |
| 780 | determined by other information provided by \fBTk_CanvasGetTextInfo\fR. |
| 781 | |
| 782 | .SH SELECTIONPROC |
| 783 | .PP |
| 784 | \fItypePtr->selectionProc\fR is invoked by Tk during selection |
| 785 | retrievals; it must return part or all of the selected text in |
| 786 | the item (if any). |
| 787 | It is only relevant for item types that support text; |
| 788 | \fItypePtr->selectionProc\fR may be specified as NULL for non-textual |
| 789 | item types. |
| 790 | The procedure must match the following prototype: |
| 791 | .CS |
| 792 | typedef int Tk_ItemSelectionProc( |
| 793 | Tk_Canvas \fIcanvas\fR, |
| 794 | Tk_Item *\fIitemPtr\fR, |
| 795 | int \fIoffset\fR, |
| 796 | char *\fIbuffer\fR, |
| 797 | int \fImaxBytes\fR); |
| 798 | .CE |
| 799 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. |
| 800 | \fIoffset\fR is an offset in bytes into the selection where 0 refers |
| 801 | to the first byte of the selection; it identifies |
| 802 | the first character that is to be returned in this call. |
| 803 | \fIbuffer\fR points to an area of memory in which to store the |
| 804 | requested bytes, and \fImaxBytes\fR specifies the maximum number |
| 805 | of bytes to return. |
| 806 | \fIselectionProc\fR should extract up to \fImaxBytes\fR characters |
| 807 | from the selection and copy them to \fImaxBytes\fR; it should |
| 808 | return a count of the number of bytes actually copied, which may |
| 809 | be less than \fImaxBytes\fR if there aren't \fIoffset+maxBytes\fR bytes |
| 810 | in the selection. |
| 811 | |
| 812 | .SH INSERTPROC |
| 813 | .PP |
| 814 | \fItypePtr->insertProc\fR is invoked by Tk during |
| 815 | the \fBinsert\fR widget command to insert new text into a |
| 816 | canvas item. |
| 817 | It is only relevant for item types that support text; |
| 818 | \fItypePtr->insertProc\fR may be specified as NULL for non-textual |
| 819 | item types. |
| 820 | The procedure must match the following prototype: |
| 821 | .CS |
| 822 | typedef void Tk_ItemInsertProc( |
| 823 | Tk_Canvas \fIcanvas\fR, |
| 824 | Tk_Item *\fIitemPtr\fR, |
| 825 | int \fIindex\fR, |
| 826 | char *\fIstring\fR); |
| 827 | .CE |
| 828 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. |
| 829 | \fIindex\fR is an index into the item's text, as returned by a |
| 830 | previous call to \fItypePtr->insertProc\fR, and \fIstring\fR |
| 831 | contains new text to insert just before the character given |
| 832 | by \fIindex\fR. |
| 833 | The type manager should insert the text and recompute the bounding |
| 834 | box in the item's header. |
| 835 | |
| 836 | .SH DCHARSPROC |
| 837 | .PP |
| 838 | \fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR |
| 839 | widget command to delete a range of text from a canvas item. |
| 840 | It is only relevant for item types that support text; |
| 841 | \fItypePtr->dCharsProc\fR may be specified as NULL for non-textual |
| 842 | item types. |
| 843 | The procedure must match the following prototype: |
| 844 | .CS |
| 845 | typedef void Tk_ItemDCharsProc( |
| 846 | Tk_Canvas \fIcanvas\fR, |
| 847 | Tk_Item *\fIitemPtr\fR, |
| 848 | int \fIfirst\fR, |
| 849 | int \fIlast\fR); |
| 850 | .CE |
| 851 | \fIcanvas\fR and \fIitemPtr\fR have the usual meanings. |
| 852 | \fIfirst\fR and \fIlast\fR give the indices of the first and last bytes |
| 853 | to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR. |
| 854 | The type manager should delete the specified characters and update |
| 855 | the bounding box in the item's header. |
| 856 | |
| 857 | .SH "SEE ALSO" |
| 858 | Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin |
| 859 | |
| 860 | .SH KEYWORDS |
| 861 | canvas, focus, item type, selection, type manager |