Cleanup and document TK_MOVABLE_POINTS

1 files changed, 167 insertions, 78 deletions

diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3
index 057013d..2549094 100644
--- a/doc/CrtItemType.3
+++ b/doc/CrtItemType.3
@@ -4,7 +4,7 @@
 '\" 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.13 2008/06/30 22:57:01 dkf Exp $
+'\" RCS: @(#) $Id: CrtItemType.3,v 1.14 2008/11/01 17:26:36 dkf Exp $
 '\" 
 .so man.macros
 .TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
@@ -46,7 +46,7 @@ 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).
+bitmap (in the 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
@@ -62,6 +62,7 @@ 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:
+.PP
 .CS
 typedef struct Tk_ItemType {
     char *\fIname\fR;
@@ -94,7 +95,7 @@ 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
+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
@@ -104,11 +105,12 @@ 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
+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:
+.PP
 .CS
 typedef struct BitmapItem {
     Tk_Item \fIheader\fR;
@@ -120,6 +122,7 @@ typedef struct BitmapItem {
     GC \fIgc\fR;
 } \fBBitmapItem\fR;
 .CE
+.PP
 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.
@@ -129,7 +132,7 @@ 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
+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
@@ -139,12 +142,12 @@ 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
+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
+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.
@@ -152,6 +155,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 "TK_ITEMTYPE FIELDS"
 .SS NAME
 .PP
 This section and the ones that follow describe each of the fields
@@ -162,9 +166,37 @@ 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.
+.SS "FLAGS (IN ALWAYSREDRAW)"
+.PP
+The \fItypePtr\->alwaysRedraw\fR field (so named for historic reasons)
+contains a collection of flag bits that modify how the canvas core interacts
+with the item. The following bits are defined:
+.TP
+\fB1\fR
+.
+Indicates that the item should always be redrawn when any part of the canvas
+is redrawn, rather than only when the bounding box of the item overlaps the
+area being redrawn. This is used by window items, for example, which need to
+unmap subwindows that are not on the screen.
+.TP
+\fBTK_CONFIG_OBJS\fR
+.
+Indicates that operations which would otherwise take a string (or array of
+strings) actually take a Tcl_Obj reference (or an array of such references).
+The operations to which this applies are the \fIconfigProc\fR, the
+\fIcoordProc\fR, the \fIcreateProc\fR, the \fIindexProc\fR and the
+\fIinsertProc\fR.
+.TP
+\fBTK_MOVABLE_POINTS\fR
+.VS 8.6
+Indicates that the item supports the \fIdCharsProc\fR, \fIindexProc\fR and
+\fIinsertProc\fR with the same semantics as Tk's built-in line and polygon
+types, and that hence individual coordinate points can be moved. Must not be
+set if any of the above methods is NULL.
+.VE 8.6
 .SS ITEMSIZE
 .PP
-\fItypePtr->itemSize\fR gives the size in bytes of item records
+\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.
@@ -173,31 +205,38 @@ 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.
 .SS CREATEPROC
 .PP
-\fItypePtr->createProc\fR points to a procedure for
+\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:
+\fItypePtr\->createProc\fR must match the following prototype:
+.PP
 .CS
 typedef int \fBTk_ItemCreateProc\fR(
         Tcl_Interp *\fIinterp\fR,
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
         int \fIobjc\fR,
-        Tcl_Obj* const \fIobjv\fR[]);
+        Tcl_Obj *const \fIobjv\fR[]);
 .CE
+.PP
 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.
+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
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
+contain a pointer to an array of constant strings.
+For example, in the widget command:
+.PP
 .CS
 \fB\&.c create rectangle 10 20 50 50 \-fill black\fR
 .CE
+.PP
 \fIobjc\fR will be \fB6\fR and \fIobjv\fR[0] will contain the
 integer object \fB10\fR.
 .PP
@@ -205,7 +244,7 @@ integer object \fB10\fR.
 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.
+error message in the interpreter result 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
@@ -215,70 +254,84 @@ the item).
 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
+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
+\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
+for implementing the \fB\-tags\fR option; see an existing type
 manager for an example of how to use it in \fIconfigSpecs\fR.
 .SS CONFIGPROC
 .PP
-\fItypePtr->configProc\fR is called by Tk whenever the
+\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:
+.PP
 .CS
 typedef int \fBTk_ItemConfigureProc\fR(
         Tcl_Interp *\fIinterp\fR,
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
         int \fIobjc\fR,
-        Tcl_Obj* const \fIobjv\fR[],
+        Tcl_Obj *const \fIobjv\fR[],
         int \fIflags\fR);
 .CE
+.PP
 The \fIinterp\fR objument identifies the interpreter in which the
-widget command was invoked,  \fIcanvas\fR is a handle for the canvas
+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:
+\fIobjc\fR and \fIobjv\fR contain the configuration options.
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
+contain a pointer to an array of constant strings.
+For example, if the following command is invoked:
+.PP
 .CS
 \fB\&.c itemconfigure 2 \-fill red \-outline black\fR
 .CE
+.PP
 \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;
+The \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
 currently this value is always \fBTK_CONFIG_ARGV_ONLY\fR when Tk
-invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR
+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.
+\fItypePtr\->configProc\fR returns a standard Tcl completion code and
+leaves an error message in the interpreter result if an error occurs.
 It must update the item's bounding box to reflect the new configuration
 options.
 .SS COORDPROC
 .PP
-\fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
+\fItypePtr\->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
 widget command for an item.
 It must match the following prototype:
+.PP
 .CS
 typedef int \fBTk_ItemCoordProc\fR(
         Tcl_Interp *\fIinterp\fR,
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
         int \fIobjc\fR,
-        Tcl_Obj* const \fIobjv\fR[]);
+        Tcl_Obj *const \fIobjv\fR[]);
 .CE
+.PP
 The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
 all have the standard meanings, and \fIobjc\fR and \fIobjv\fR
 describe the coordinate arguments.
+Note that if \fBTK_CONFIG_OBJS\fR is not set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIobjv\fR parameter will actually
+contain a pointer to an array of constant strings.
 For example, if the following widget command is invoked:
+.PP
 .CS
 \fB\&.c coords 2 30 90\fR
 .CE
+.PP
 \fIobjc\fR will be \fB2\fR and \fBobjv\fR will contain the integer objects
 \fB30\fR and \fB90\fR.
 .PP
@@ -287,30 +340,33 @@ 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.
+the interpreter result.
 .SS DELETEPROC
 .PP
-\fItypePtr->deleteProc\fR is invoked by Tk to delete an item
+\fItypePtr\->deleteProc\fR is invoked by Tk to delete an item
 and free any resources allocated to it.
 It must match the following prototype:
+.PP
 .CS
 typedef void \fBTk_ItemDeleteProc\fR(
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
         Display *\fIdisplay\fR);
 .CE
+.PP
 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
+\fIdeleteProc\fR should not actually free the item record; this will
 be done by Tk when \fIdeleteProc\fR returns.
-.SS "DISPLAYPROC AND ALWAYSREDRAW"
+.SS "DISPLAYPROC"
 .PP
-\fItypePtr->displayProc\fR is invoked by Tk to redraw an item
+\fItypePtr\->displayProc\fR is invoked by Tk to redraw an item
 on the screen.
 It must match the following prototype:
+.PP
 .CS
 typedef void \fBTk_ItemDisplayProc\fR(
         Tk_Canvas \fIcanvas\fR,
@@ -322,6 +378,7 @@ typedef void \fBTk_ItemDisplayProc\fR(
         int \fIwidth\fR,
         int \fIheight\fR);
 .CE
+.PP
 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;
@@ -343,25 +400,28 @@ 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 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.
+However, if bit zero of \fItypePtr\->alwaysRedraw\fR is 1,
+(i.e.\|
+.QW "\fItypePtr\->alwaysRedraw & 1 == 1\fR" )
+then \fIdisplayProc\fR is invoked during every redisplay operation,
+even if the item does not overlap the area of redisplay; this is useful for
+cases such as window items, where the subwindow needs to be unmapped when it
+is off the screen.
 .SS POINTPROC
 .PP
-\fItypePtr->pointProc\fR is invoked by Tk to find out how close
+\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:
+.PP
 .CS
 typedef double \fBTk_ItemPointProc\fR(
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
         double *\fIpointPtr\fR);
 .CE
+.PP
 \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.
@@ -370,15 +430,17 @@ from the point to the item, or 0 if the point lies inside
 the item.
 .SS AREAPROC
 .PP
-\fItypePtr->areaProc\fR is invoked by Tk to find out the relationship
+\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:
+.PP
 .CS
 typedef int \fBTk_ItemAreaProc\fR(
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
         double *\fIrectPtr\fR);
 .CE
+.PP
 \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
@@ -389,11 +451,12 @@ the given area, 0 if it lies partially inside and partially
 outside the area, and 1 if it lies entirely inside the area.
 .SS POSTSCRIPTPROC
 .PP
-\fItypePtr->postscriptProc\fR is invoked by Tk to generate
+\fItypePtr\->postscriptProc\fR is invoked by Tk to generate
 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.
+\fItypePtr\->postscriptProc\fR should be NULL.
 The procedure must match the following prototype:
+.PP
 .CS
 typedef int \fBTk_ItemPostscriptProc\fR(
         Tcl_Interp *\fIinterp\fR,
@@ -401,14 +464,15 @@ typedef int \fBTk_ItemPostscriptProc\fR(
         Tk_Item *\fIitemPtr\fR,
         int \fIprepass\fR);
 .CE
+.PP
 The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have
-standard meanings;  \fIprepass\fR will be described below.
+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
+Postscript for the item to the information in the interpreter result
 (e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR)
 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
+and replace its contents with an error message; then it should
 return \fBTCL_ERROR\fR.
 .PP
 Tk provides a collection of utility procedures to simplify
@@ -430,18 +494,19 @@ 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
+(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
+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.
 .SS SCALEPROC
 .PP
-\fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item
+\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:
+.PP
 .CS
 typedef void \fBTk_ItemScaleProc\fR(
         Tk_Canvas \fIcanvas\fR,
@@ -451,6 +516,7 @@ typedef void \fBTk_ItemScaleProc\fR(
         double \fIscaleX\fR,
         double \fIscaleY\fR);
 .CE
+.PP
 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
@@ -458,17 +524,20 @@ 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\(fm\fR and \fIy\(fm\fR, where
+.PP
 .CS
-\fIx\(fm = originX  + scaleX*(x-originX)
-y\(fm = originY + scaleY*(y-originY)\fR
+\fIx\(fm\fR = \fIoriginX\fR + \fIscaleX\fR \(mu (\fIx\fR \(mi \fIoriginX\fR)
+\fIy\(fm\fR = \fIoriginY\fR + \fIscaleY\fR \(mu (\fIy\fR \(mi \fIoriginY\fR)
 .CE
+.PP
 \fIscaleProc\fR must also update the bounding box in the item's
 header.
 .SS TRANSLATEPROC
 .PP
-\fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item
+\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:
+.PP
 .CS
 typedef void \fBTk_ItemTranslateProc\fR(
         Tk_Canvas \fIcanvas\fR,
@@ -476,6 +545,7 @@ typedef void \fBTk_ItemTranslateProc\fR(
         double \fIdeltaX\fR,
         double \fIdeltaY\fR);
 .CE
+.PP
 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.
@@ -483,62 +553,70 @@ The type manager should adjust the item's coordinates and
 update the bounding box in the item's header.
 .SS INDEXPROC
 .PP
-\fItypePtr->indexProc\fR is invoked by Tk to translate a string
+\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.
+It is only relevant for item types that support indexable text or coordinates;
+\fItypePtr\->indexProc\fR may be specified as NULL for non-textual
+item types if they do not support detailed coordinate addressing.
 The procedure must match the following prototype:
+.PP
 .CS
 typedef int \fBTk_ItemIndexProc\fR(
         Tcl_Interp *\fIinterp\fR,
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
-        char \fIindexString\fR,
+        char *\fIindexString\fR,
         int *\fIindexPtr\fR);
 .CE
+.PP
 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.
+Note that if \fBTK_CONFIG_OBJS\fR is set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIindexString\fR parameter will
+actually contain a Tcl_Obj reference.
 It is up to the type manager to decide what forms of index
-are supported (e.g., numbers, \fBinsert\fR,  \fBsel.first\fR,
+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.
+the interpreter result in the event of an error.
 .SS ICURSORPROC
 .PP
-\fItypePtr->icursorProc\fR is invoked by Tk during
+\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
+\fItypePtr\->icursorProc\fR may be specified as NULL for item types
 that do not support an insertion cursor.
 The procedure must match the following prototype:
+.PP
 .CS
 typedef void \fBTk_ItemCursorProc\fR(
         Tk_Canvas \fIcanvas\fR,
         Tk_Item *\fIitemPtr\fR,
         int \fIindex\fR);
 .CE
+.PP
 \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.
+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.
 .SS SELECTIONPROC
 .PP
-\fItypePtr->selectionProc\fR is invoked by Tk during selection
-retrievals;  it must return part or all of the selected text in
+\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
+\fItypePtr\->selectionProc\fR may be specified as NULL for non-textual
 item types.
 The procedure must match the following prototype:
+.PP
 .CS
 typedef int \fBTk_ItemSelectionProc\fR(
         Tk_Canvas \fIcanvas\fR,
@@ -547,27 +625,29 @@ typedef int \fBTk_ItemSelectionProc\fR(
         char *\fIbuffer\fR,
         int \fImaxBytes\fR);
 .CE
+.PP
 \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
+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
+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 are not \fIoffset+maxBytes\fR bytes
 in the selection.
 .SS INSERTPROC
 .PP
-\fItypePtr->insertProc\fR is invoked by Tk during
-the \fBinsert\fR widget command to insert new text into a
+\fItypePtr\->insertProc\fR is invoked by Tk during
+the \fBinsert\fR widget command to insert new text or coordinates 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
+It is only relevant for item types that support the \fBinsert\fR method;
+\fItypePtr\->insertProc\fR may be specified as NULL for other
 item types.
 The procedure must match the following prototype:
+.PP
 .CS
 typedef void \fBTk_ItemInsertProc\fR(
         Tk_Canvas \fIcanvas\fR,
@@ -575,21 +655,29 @@ typedef void \fBTk_ItemInsertProc\fR(
         int \fIindex\fR,
         char *\fIstring\fR);
 .CE
+.PP
 \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
+previous call to \fItypePtr\->insertProc\fR, and \fIstring\fR
 contains new text to insert just before the character given
 by \fIindex\fR.
+Note that if \fBTK_CONFIG_OBJS\fR is set in the
+\fItypePtr\->alwaysRedraw\fR field, the \fIstring\fR parameter will
+actually contain a Tcl_Obj reference to the string to insert.
+If the item supports modification of the coordinates list by this
+.PP
 The type manager should insert the text and recompute the bounding
 box in the item's header.
 .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.
+\fItypePtr\->dCharsProc\fR is invoked by Tk during the \fBdchars\fR
+widget command to delete a range of text from a canvas item or a range of
+coordinates from a pathed item.
 It is only relevant for item types that support text;
-\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual
-item types.
+\fItypePtr\->dCharsProc\fR may be specified as NULL for non-textual
+item types that do not want to support coordinate deletion.
 The procedure must match the following prototype:
+.PP
 .CS
 typedef void \fBTk_ItemDCharsProc\fR(
         Tk_Canvas \fIcanvas\fR,
@@ -597,9 +685,10 @@ typedef void \fBTk_ItemDCharsProc\fR(
         int \fIfirst\fR,
         int \fIlast\fR);
 .CE
+.PP
 \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.
+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"