diff options
Diffstat (limited to 'doc/CrtItemType.3')
| -rw-r--r-- | doc/CrtItemType.3 | 268 |
1 files changed, 123 insertions, 145 deletions
diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3 index f035bc2..4f06438 100644 --- a/doc/CrtItemType.3 +++ b/doc/CrtItemType.3 @@ -22,7 +22,6 @@ Tk_ItemType * .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 @@ -52,7 +51,6 @@ for an existing type and modify it for the new type. 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 @@ -64,26 +62,26 @@ 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; + 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 @@ -111,13 +109,13 @@ 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; + 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 @@ -152,8 +150,7 @@ 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 +.SS NAME .PP This section and the ones that follow describe each of the fields in a Tk_ItemType structure in detail. @@ -163,8 +160,7 @@ 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 +.SS 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. @@ -172,19 +168,18 @@ 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 +.SS 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); + 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 @@ -212,8 +207,7 @@ 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 +.SS CONFIGSPECS .PP Each type manager must provide a standard table describing its configuration options, in a form suitable for use with @@ -227,8 +221,7 @@ 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 +.SS CONFIGPROC .PP \fItypePtr->configProc\fR is called by Tk whenever the \fBitemconfigure\fR widget command is invoked to change the @@ -236,12 +229,12 @@ 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); + 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 @@ -255,7 +248,7 @@ example, if the following command is invoked: 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 +currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR procedure will usually invoke \fIconfigProc\fR with different flag values. .PP @@ -263,19 +256,18 @@ procedure will usually invoke \fIconfigProc\fR with different flag values. 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 +.SS 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); + 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 @@ -293,17 +285,16 @@ 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 +.SS 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); + 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 @@ -312,22 +303,21 @@ the canvas. 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" +.SS "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); + 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 @@ -352,12 +342,11 @@ 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. +even if the item does not 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 +.SS POINTPROC .PP \fItypePtr->pointProc\fR is invoked by Tk to find out how close a given point is to a canvas item. @@ -366,9 +355,9 @@ 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); + 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 @@ -376,17 +365,16 @@ 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 +.SS 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); + 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; @@ -396,30 +384,29 @@ 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 +.SS POSTSCRIPTPROC .PP \fItypePtr->postscriptProc\fR is invoked by Tk to generate -Postcript for an item during the \fBpostscript\fR widget command. +Postscript 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); + 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. +and return \fBTCL_OK\fR. If an error occurs, \fIpostscriptProc\fR should clear the result and replace its contents with an error message; then it should -return TCL_ERROR. +return \fBTCL_ERROR\fR. .PP Tk provides a collection of utility procedures to simplify \fIpostscriptProc\fR. @@ -447,19 +434,18 @@ 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 +.SS 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); + 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 @@ -467,32 +453,30 @@ 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 +coordinates \fIx\(fm\fR and \fIy\(fm\fR, where .CS -\fIx' = originX + scaleX*(x-originX) -y' = originY + scaleY*(y-originY)\fR +\fIx\(fm = originX + scaleX*(x-originX) +y\(fm = originY + scaleY*(y-originY)\fR .CE \fIscaleProc\fR must also update the bounding box in the item's header. - -.SH TRANSLATEPROC +.SS 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); + 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 +.SS 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. @@ -502,11 +486,11 @@ 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); + 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. @@ -518,21 +502,20 @@ 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 +.SS 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. +that do not 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); + 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 @@ -541,8 +524,7 @@ 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 +.SS SELECTIONPROC .PP \fItypePtr->selectionProc\fR is invoked by Tk during selection retrievals; it must return part or all of the selected text in @@ -553,11 +535,11 @@ 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); + 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 @@ -569,10 +551,9 @@ 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 +be less than \fImaxBytes\fR if there are not \fIoffset+maxBytes\fR bytes in the selection. - -.SH INSERTPROC +.SS INSERTPROC .PP \fItypePtr->insertProc\fR is invoked by Tk during the \fBinsert\fR widget command to insert new text into a @@ -583,10 +564,10 @@ 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); + 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 @@ -595,8 +576,7 @@ 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 +.SS 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. @@ -606,19 +586,17 @@ 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); + 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 |