Initial revision

1 files changed, 626 insertions, 0 deletions

diff --git a/doc/CrtItemType.3 b/doc/CrtItemType.3
new file mode 100644
index 0000000..7f26dc5
--- /dev/null
+++ b/doc/CrtItemType.3
@@ -0,0 +1,626 @@
+'\"
+'\" Copyright (c) 1994-1995 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" SCCS: @(#) CrtItemType.3 1.7 96/02/16 10:30:28
+'\" 
+.so man.macros
+.TH Tk_CreateItemType 3 4.0 Tk "Tk Library Procedures"
+.BS
+.SH NAME
+Tk_CreateItemType, Tk_GetItemTypes \- define new kind of canvas item
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateItemType\fR(\fItypePtr\fR)
+.sp
+Tk_ItemType *
+\fBTk_GetItemTypes\fR()
+.SH ARGUMENTS
+.AS Tk_ItemType *typePtr
+.AP Tk_ItemType *typePtr in
+Structure that defines the new type of canvas item.
+.BE
+
+.SH INTRODUCTION
+.PP
+\fBTk_CreateItemType\fR is invoked to define a new kind of canvas item
+described by the \fItypePtr\fR argument.
+An item type corresponds to a particular value of the \fItype\fR
+argument to the \fBcreate\fR widget command for canvases, and
+the code that implements a canvas item type is called a \fItype manager\fR.
+Tk defines several built-in item types, such as \fBrectangle\fR
+and \fBtext\fR and \fBimage\fR, but \fBTk_CreateItemType\fR
+allows additional item types to be defined.
+Once \fBTk_CreateItemType\fR returns, the new item type may be used
+in new or existing canvas widgets just like the built-in item
+types.
+.PP
+\fBTk_GetItemTypes\fR returns a pointer to the first in the list
+of all item types currently defined for canvases.
+The entries in the list are linked together through their
+\fInextPtr\fR fields, with the end of the list marked by a
+NULL \fInextPtr\fR.
+.PP
+You may find it easier to understand the rest of this manual entry
+by looking at the code for an existing canvas item type such as
+bitmap (file tkCanvBmap.c) or text (tkCanvText.c).
+The easiest way to create a new type manager is to copy the code
+for an existing type and modify it for the new type.
+.PP
+Tk provides a number of utility procedures for the use of canvas
+type managers, such as \fBTk_CanvasCoords\fR and \fBTk_CanvasPsColor\fR;
+these are described in separate manual entries.
+
+.SH "DATA STRUCTURES"
+.PP
+A type manager consists of a collection of procedures that provide a
+standard set of operations on items of that type.
+The type manager deals with three kinds of data
+structures.
+The first data structure is a Tk_ItemType; it contains
+information such as the name of the type and pointers to
+the standard procedures implemented by the type manager:
+.CS
+typedef struct Tk_ItemType {
+	char *\fIname\fR;
+	int \fIitemSize\fR;
+	Tk_ItemCreateProc *\fIcreateProc\fR;
+	Tk_ConfigSpec *\fIconfigSpecs\fR;
+	Tk_ItemConfigureProc *\fIconfigProc\fR;
+	Tk_ItemCoordProc *\fIcoordProc\fR;
+	Tk_ItemDeleteProc *\fIdeleteProc\fR;
+	Tk_ItemDisplayProc *\fIdisplayProc\fR;
+	int \fIalwaysRedraw\fR;
+	Tk_ItemPointProc *\fIpointProc\fR;
+	Tk_ItemAreaProc *\fIareaProc\fR;
+	Tk_ItemPostscriptProc *\fIpostscriptProc\fR;
+	Tk_ItemScaleProc *\fIscaleProc\fR;
+	Tk_ItemTranslateProc *\fItranslateProc\fR;
+	Tk_ItemIndexProc *\fIindexProc\fR;
+	Tk_ItemCursorProc *\fIicursorProc\fR;
+	Tk_ItemSelectionProc *\fIselectionProc\fR;
+	Tk_ItemInsertProc *\fIinsertProc\fR;
+	Tk_ItemDCharsProc *\fIdCharsProc\fR;
+	Tk_ItemType *\fInextPtr\fR;
+} Tk_ItemType;
+.CE
+.PP
+The fields of a Tk_ItemType structure are described in more detail
+later in this manual entry.
+When \fBTk_CreateItemType\fR is called, its \fItypePtr\fR
+argument must point to a structure with all of the fields initialized
+except \fInextPtr\fR, which Tk sets to link all the types together
+into a list.
+The structure must be in permanent memory (either statically
+allocated or dynamically allocated but never freed);  Tk retains
+a pointer to this structure.
+.PP
+The second data structure manipulated by a type manager is an
+\fIitem record\fR.
+For each item in a canvas there exists one item record.
+All of the items of a given type generally have item records with
+the same structure, but different types usually have different
+formats for their item records.
+The first part of each item record is a header with a standard structure
+defined by Tk via the type Tk_Item;  the rest of the item
+record is defined by the type manager.
+A type manager must define its item records with a Tk_Item as
+the first field.
+For example, the item record for bitmap items is defined as follows:
+.CS
+typedef struct BitmapItem {
+	Tk_Item \fIheader\fR;
+	double \fIx\fR, \fIy\fR;
+	Tk_Anchor \fIanchor\fR;
+	Pixmap \fIbitmap\fR;
+	XColor *\fIfgColor\fR;
+	XColor *\fIbgColor\fR;
+	GC \fIgc\fR;
+} BitmapItem;
+.CE
+The \fIheader\fR substructure contains information used by Tk
+to manage the item, such as its identifier, its tags, its type,
+and its bounding box.
+The fields starting with \fIx\fR belong to the type manager:
+Tk will never read or write them.
+The type manager should not need to read or write any of the
+fields in the header except for four fields
+whose names are \fIx1\fR, \fIy1\fR, \fIx2\fR, and \fIy2\fR.
+These fields give a bounding box for the items using integer
+canvas coordinates:  the item should not cover any pixels
+with x-coordinate lower than \fIx1\fR or y-coordinate
+lower than \fIy1\fR, nor should it cover any pixels with
+x-coordinate greater than or equal to \fIx2\fR or y-coordinate
+greater than or equal to \fIy2\fR.
+It is up to the type manager to keep the bounding box up to
+date as the item is moved and reconfigured.
+.PP
+Whenever Tk calls a procedure in a type manager it passes in a pointer
+to an item record.
+The argument is always passed as a pointer to a Tk_Item;  the type
+manager will typically cast this into a pointer to its own specific
+type, such as BitmapItem.
+.PP
+The third data structure used by type managers has type
+Tk_Canvas;  it serves as an opaque handle for the canvas widget
+as a whole.
+Type managers need not know anything about the contents of this
+structure.
+A Tk_Canvas handle is typically passed in to the
+procedures of a type manager, and the type manager can pass the
+handle back to library procedures such as Tk_CanvasTkwin
+to fetch information about the canvas.
+
+.SH NAME
+.PP
+This section and the ones that follow describe each of the fields
+in a Tk_ItemType structure in detail.
+The \fIname\fR field provides a string name for the item type.
+Once \fBTk_CreateImageType\fR returns, this name may be used
+in \fBcreate\fR widget commands to create items of the new
+type.
+If there already existed an item type by this name then
+the new item type replaces the old one.
+
+.SH ITEMSIZE
+\fItypePtr->itemSize\fR gives the size in bytes of item records
+of this type, including the Tk_Item header.
+Tk uses this size to allocate memory space for items of the type.
+All of the item records for a given type must have the same size.
+If variable length fields are needed for an item (such as a list
+of points for a polygon), the type manager can allocate a separate
+object of variable length and keep a pointer to it in the item record.
+
+.SH CREATEPROC
+.PP
+\fItypePtr->createProc\fR points to a procedure for
+Tk to call whenever a new item of this type is created.
+\fItypePtr->createProc\fR must match the following prototype:
+.CS
+typedef int Tk_ItemCreateProc(
+	Tcl_Interp *\fIinterp\fR,
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIargc\fR,
+	char **\fIargv\fR);
+.CE
+The \fIinterp\fR argument is the interpreter in which the canvas's
+\fBcreate\fR widget command was invoked, and \fIcanvas\fR is a
+handle for the canvas widget.
+\fIitemPtr\fR is a pointer to a newly-allocated item of
+size \fItypePtr->itemSize\fR.
+Tk has already initialized the item's header (the first
+\fBsizeof(Tk_ItemType)\fR bytes).
+The \fIargc\fR and \fIargv\fR arguments describe all of the
+arguments to the \fBcreate\fR command after the \fItype\fR
+argument.
+For example, in the widget command
+.CS
+\fB\&.c create rectangle 10 20 50 50 \-fill black\fR
+.CE
+\fIargc\fR will be \fB6\fR and \fIargv\fR[0] will contain the
+string \fB10\fR.
+.PP
+\fIcreateProc\fR should use \fIargc\fR and \fIargv\fR to initialize
+the type-specific parts of the item record and set an initial value
+for the bounding box in the item's header.
+It should return a standard Tcl completion code and leave an
+error message in \fIinterp->result\fR if an error occurs.
+If an error occurs Tk will free the item record, so \fIcreateProc\fR
+must be sure to leave the item record in a clean state if it returns an error
+(e.g., it must free any additional memory that it allocated for
+the item).
+
+.SH CONFIGSPECS
+.PP
+Each type manager must provide a standard table describing its
+configuration options, in a form suitable for use with
+\fBTk_ConfigureWidget\fR.
+This table will normally be used by \fItypePtr->createProc\fR
+and \fItypePtr->configProc\fR, but Tk also uses it directly
+to retrieve option information in the \fBitemcget\fR and
+\fBitemconfigure\fR widget commands.
+\fItypePtr->configSpecs\fR must point to the configuration table
+for this type.
+Note: Tk provides a custom option type \fBtk_CanvasTagsOption\fR
+for implementing the \fB\-tags\fR option;  see an existing type
+manager for an example of how to use it in \fIconfigSpecs\fR.
+
+.SH CONFIGPROC
+.PP
+\fItypePtr->configProc\fR is called by Tk whenever the
+\fBitemconfigure\fR widget command is invoked to change the
+configuration options for a canvas item.
+This procedure must match the following prototype:
+.CS
+typedef int Tk_ItemConfigureProc(
+	Tcl_Interp *\fIinterp\fR,
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIargc\fR,
+	char **\fIargv\fR,
+	int \fIflags\fR);
+.CE
+The \fIinterp\fR argument identifies the interpreter in which the
+widget command was invoked,  \fIcanvas\fR is a handle for the canvas
+widget, and \fIitemPtr\fR is a pointer to the item being configured.
+\fIargc\fR and \fIargv\fR contain the configuration options.  For
+example, if the following command is invoked:
+.CS
+\fB\&.c itemconfigure 2 \-fill red \-outline black\fR
+.CE
+\fIargc\fR is \fB4\fR and \fIargv\fR contains the strings \fB\-fill\fR
+through \fBblack\fR.
+\fIargc\fR will always be an even value.
+The  \fIflags\fR argument contains flags to pass to \fBTk_ConfigureWidget\fR;
+currently this value is always TK_CONFIG_ARGV_ONLY when Tk
+invokes \fItypePtr->configProc\fR, but the type manager's \fIcreateProc\fR
+procedure will usually invoke \fIconfigProc\fR with different flag values.
+.PP
+\fItypePtr->configProc\fR returns a standard Tcl completion code and
+leaves an error message in \fIinterp->result\fR if an error occurs.
+It must update the item's bounding box to reflect the new configuration
+options.
+
+.SH COORDPROC
+.PP
+\fItypePtr->coordProc\fR is invoked by Tk to implement the \fBcoords\fR
+widget command for an item.
+It must match the following prototype:
+.CS
+typedef int Tk_ItemCoordProc(
+	Tcl_Interp *\fIinterp\fR,
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIargc\fR,
+	char **\fIargv\fR);
+.CE
+The arguments \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR
+all have the standard meanings, and \fIargc\fR and \fIargv\fR
+describe the coordinate arguments.
+For example, if the following widget command is invoked:
+.CS
+\fB\&.c coords 2 30 90\fR
+.CE
+\fIargc\fR will be \fB2\fR and \fBargv\fR will contain the string values
+\fB30\fR and \fB90\fR.
+.PP
+The \fIcoordProc\fR procedure should process the new coordinates,
+update the item appropriately (e.g., it must reset the bounding
+box in the item's header), and return a standard Tcl completion
+code.
+If an error occurs, \fIcoordProc\fR must leave an error message in
+\fIinterp->result\fR.
+
+.SH DELETEPROC
+.PP
+\fItypePtr->deleteProc\fR is invoked by Tk to delete an item
+and free any resources allocated to it.
+It must match the following prototype:
+.CS
+typedef void Tk_ItemDeleteProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	Display *\fIdisplay\fR);
+.CE
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual
+interpretations, and \fIdisplay\fR identifies the X display containing
+the canvas.
+\fIdeleteProc\fR must free up any resources allocated for the item,
+so that Tk can free the item record.
+\fIdeleteProc\fR should not actually free the item record;  this will
+be done by Tk when \fIdeleteProc\fR returns.
+
+.SH "DISPLAYPROC AND ALWAYSREDRAW"
+.PP
+\fItypePtr->displayProc\fR is invoked by Tk to redraw an item
+on the screen.
+It must match the following prototype:
+.CS
+typedef void Tk_ItemDisplayProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	Display *\fIdisplay\fR,
+	Drawable \fIdst\fR,
+	int \fIx\fR,
+	int \fIy\fR,
+	int \fIwidth\fR,
+	int \fIheight\fR);
+.CE
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
+\fIdisplay\fR identifies the display containing the canvas, and
+\fIdst\fR specifies a drawable in which the item should be rendered;
+typically this is an off-screen pixmap, which Tk will copy into
+the canvas's window once all relevant items have been drawn.
+\fIx\fR, \fIy\fR, \fIwidth\fR, and \fIheight\fR specify a rectangular
+region in canvas coordinates, which is the area to be redrawn;
+only information that overlaps this area needs to be redrawn.
+Tk will not call \fIdisplayProc\fR unless the item's bounding box
+overlaps the redraw area, but the type manager may wish to use
+the redraw area to optimize the redisplay of the item.
+.PP
+Because of scrolling and the use of off-screen pixmaps for
+double-buffered redisplay, the item's coordinates in \fIdst\fR
+will not necessarily be the same as those in the canvas.
+\fIdisplayProc\fR should call \fBTk_CanvasDrawableCoords\fR
+to transform coordinates from those of the canvas to those
+of \fIdst\fR.
+.PP
+Normally an item's \fIdisplayProc\fR is only invoked if the item
+overlaps the area being displayed.
+However, if \fItypePtr->alwaysRedraw\fR has a non-zero value, then
+\fIdisplayProc\fR is invoked during every redisplay operation,
+even if the item doesn't overlap the area of redisplay.
+\fIalwaysRedraw\fR should normally be set to 0;  it is only
+set to 1 in special cases such as window items that need to be
+unmapped when they are off-screen.
+
+.SH POINTPROC
+.PP
+\fItypePtr->pointProc\fR is invoked by Tk to find out how close
+a given point is to a canvas item.
+Tk uses this procedure for purposes such as locating the item
+under the mouse or finding the closest item to a given point.
+The procedure must match the following prototype:
+.CS
+typedef double Tk_ItemPointProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	double *\fIpointPtr\fR);
+.CE
+\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
+\fIpointPtr\fR points to an array of two numbers giving
+the x and y coordinates of a point.
+\fIpointProc\fR must return a real value giving the distance
+from the point to the item, or 0 if the point lies inside
+the item.
+
+.SH AREAPROC
+.PP
+\fItypePtr->areaProc\fR is invoked by Tk to find out the relationship
+between an item and a rectangular area.
+It must match the following prototype:
+.CS
+typedef int Tk_ItemAreaProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	double *\fIrectPtr\fR);
+.CE
+\fIcanvas\fR and \fIitemPtr\fR have the usual meaning.
+\fIrectPtr\fR points to an array of four real numbers;
+the first two give the x and y coordinates of the upper left
+corner of a rectangle, and the second two give the x and y
+coordinates of the lower right corner.
+\fIareaProc\fR must return \-1 if the item lies entirely outside
+the given area, 0 if it lies partially inside and partially
+outside the area, and 1 if it lies entirely inside the area.
+
+.SH POSTSCRIPTPROC
+.PP
+\fItypePtr->postscriptProc\fR is invoked by Tk to generate
+Postcript for an item during the \fBpostscript\fR widget command.
+If the type manager is not capable of generating Postscript then
+\fItypePtr->postscriptProc\fR should be NULL.
+The procedure must match the following prototype:
+.CS
+typedef int Tk_ItemPostscriptProc(
+	Tcl_Interp *\fIinterp\fR,
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIprepass\fR);
+.CE
+The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all have
+standard meanings;  \fIprepass\fR will be described below.
+If \fIpostscriptProc\fR completes successfully, it should append
+Postscript for the item to the information in \fIinterp->result\fR
+(e.g. by calling \fBTcl_AppendResult\fR, not \fBTcl_SetResult\fR)
+and return TCL_OK.
+If an error occurs, \fIpostscriptProc\fR should clear the result
+and replace its contents with an error message;  then it should
+return TCL_ERROR.
+.PP
+Tk provides a collection of utility procedures to simplify
+\fIpostscriptProc\fR.
+For example, \fBTk_CanvasPsColor\fR will generate Postscript to set
+the current color to a given Tk color and \fBTk_CanvasPsFont\fR will
+set up font information.
+When generating Postscript, the type manager is free to change the
+graphics state of the Postscript interpreter, since Tk places
+\fBgsave\fR and \fBgrestore\fR commands around the Postscript for
+the item.
+The type manager can use canvas x coordinates directly in its Postscript,
+but it must call \fBTk_CanvasPsY\fR to convert y coordinates from
+the space of the canvas (where the origin is at the
+upper left) to the space of Postscript (where the origin is at the
+lower left).
+.PP
+In order to generate Postscript that complies with the Adobe Document
+Structuring Conventions, Tk actually generates Postscript in two passes.
+It calls each item's \fIpostscriptProc\fR in each pass.
+The only purpose of the first pass is to collect font information
+(which is done by \fBTk_CanvPsFont\fR);  the actual Postscript is
+discarded.
+Tk sets the \fIprepass\fR argument to \fIpostscriptProc\fR to 1
+during the first pass;  the type manager can use \fIprepass\fR to skip
+all Postscript generation except for calls to \fBTk_CanvasPsFont\fR.
+During the second pass \fIprepass\fR will be 0, so the type manager
+must generate complete Postscript.
+
+.SH SCALEPROC
+\fItypePtr->scaleProc\fR is invoked by Tk to rescale a canvas item
+during the \fBscale\fR widget command.
+The procedure must match the following prototype:
+.CS
+typedef void Tk_ItemScaleProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	double \fIoriginX\fR,
+	double \fIoriginY\fR,
+	double \fIscaleX\fR,
+	double \fIscaleY\fR);
+.CE
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning.
+\fIoriginX\fR and \fIoriginY\fR specify an origin relative to which
+the item is to be scaled, and \fIscaleX\fR and \fIscaleY\fR give the
+x and y scale factors.
+The item should adjust its coordinates so that a point in the item
+that used to have coordinates \fIx\fR and \fIy\fR will have new
+coordinates \fIx'\fR and \fIy'\fR, where
+.CS
+\fIx' = originX  + scaleX*(x-originX)
+y' = originY + scaleY*(y-originY)\fR
+.CE
+\fIscaleProc\fR must also update the bounding box in the item's
+header.
+
+.SH TRANSLATEPROC
+\fItypePtr->translateProc\fR is invoked by Tk to translate a canvas item
+during the \fBmove\fR widget command.
+The procedure must match the following prototype:
+.CS
+typedef void Tk_ItemTranslateProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	double \fIdeltaX\fR,
+	double \fIdeltaY\fR);
+.CE
+The \fIcanvas\fR and \fIitemPtr\fR arguments have the usual meaning,
+and \fIdeltaX\fR and \fIdeltaY\fR give the amounts that should be
+added to each x and y coordinate within the item.
+The type manager should adjust the item's coordinates and
+update the bounding box in the item's header.
+
+.SH INDEXPROC
+\fItypePtr->indexProc\fR is invoked by Tk to translate a string
+index specification into a numerical index, for example during the
+\fBindex\fR widget command.
+It is only relevant for item types that support indexable text;
+\fItypePtr->indexProc\fR may be specified as NULL for non-textual
+item types.
+The procedure must match the following prototype:
+.CS
+typedef int Tk_ItemIndexProc(
+	Tcl_Interp *\fIinterp\fR,
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	char \fIindexString\fR,
+	int *\fIindexPtr\fR);
+.CE
+The \fIinterp\fR, \fIcanvas\fR, and \fIitemPtr\fR arguments all
+have the usual meaning.
+\fIindexString\fR contains a textual description of an index,
+and \fIindexPtr\fR points to an integer value that should be
+filled in with a numerical index.
+It is up to the type manager to decide what forms of index
+are supported (e.g., numbers, \fBinsert\fR,  \fBsel.first\fR,
+\fBend\fR, etc.).
+\fIindexProc\fR should return a Tcl completion code and set
+\fIinterp->result\fR in the event of an error.
+
+.SH ICURSORPROC
+.PP
+\fItypePtr->icursorProc\fR is invoked by Tk during
+the \fBicursor\fR widget command to set the position of the
+insertion cursor in a textual item.
+It is only relevant for item types that support an insertion cursor;
+\fItypePtr->icursorProc\fR may be specified as NULL for item types
+that don't support an insertion cursor.
+The procedure must match the following prototype:
+.CS
+typedef void Tk_ItemIndexProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIindex\fR);
+.CE
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings, and
+\fIindex\fR is an index into the item's text, as returned by a
+previous call to \fItypePtr->insertProc\fR.
+The type manager should position the insertion cursor in the
+item just before the character given by \fIindex\fR.
+Whether or not to actually display the insertion cursor is
+determined by other information provided by \fBTk_CanvasGetTextInfo\fR.
+
+.SH SELECTIONPROC
+.PP
+\fItypePtr->selectionProc\fR is invoked by Tk during selection
+retrievals;  it must return part or all of the selected text in
+the item (if any).
+It is only relevant for item types that support text;
+\fItypePtr->selectionProc\fR may be specified as NULL for non-textual
+item types.
+The procedure must match the following prototype:
+.CS
+typedef int Tk_ItemSelectionProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIoffset\fR,
+	char *\fIbuffer\fR,
+	int \fImaxBytes\fR);
+.CE
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
+\fIoffset\fR is an offset in bytes into the selection where 0 refers
+to the first byte of the selection;  it identifies
+the first character that is to be returned in this call.
+\fIbuffer\fR points to an area of memory in which to store the
+requested bytes, and \fImaxBytes\fR specifies the maximum number
+of bytes to return.
+\fIselectionProc\fR should extract up to \fImaxBytes\fR characters
+from the selection and copy them to \fImaxBytes\fR;  it should
+return a count of the number of bytes actually copied, which may
+be less than \fImaxBytes\fR if there aren't \fIoffset+maxBytes\fR bytes
+in the selection.
+
+.SH INSERTPROC
+.PP
+\fItypePtr->insertProc\fR is invoked by Tk during
+the \fBinsert\fR widget command to insert new text into a
+canvas item.
+It is only relevant for item types that support text;
+\fItypePtr->insertProc\fR may be specified as NULL for non-textual
+item types.
+The procedure must match the following prototype:
+.CS
+typedef void Tk_ItemInsertProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIindex\fR,
+	char *\fIstring\fR);
+.CE
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
+\fIindex\fR is an index into the item's text, as returned by a
+previous call to \fItypePtr->insertProc\fR, and \fIstring\fR
+contains new text to insert just before the character given
+by \fIindex\fR.
+The type manager should insert the text and recompute the bounding
+box in the item's header.
+
+.SH DCHARSPROC
+.PP
+\fItypePtr->dCharsProc\fR is invoked by Tk during the \fBdchars\fR
+widget command to delete a range of text from a canvas item.
+It is only relevant for item types that support text;
+\fItypePtr->dCharsProc\fR may be specified as NULL for non-textual
+item types.
+The procedure must match the following prototype:
+.CS
+typedef void Tk_ItemDCharsProc(
+	Tk_Canvas \fIcanvas\fR,
+	Tk_Item *\fIitemPtr\fR,
+	int \fIfirst\fR,
+	int \fIlast\fR);
+.CE
+\fIcanvas\fR and \fIitemPtr\fR have the usual meanings.
+\fIfirst\fR and \fIlast\fR give the indices of the first and last bytes
+to be deleted, as returned by previous calls to \fItypePtr->indexProc\fR.
+The type manager should delete the specified characters and update
+the bounding box in the item's header.
+
+.SH "SEE ALSO"
+Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
+
+.SH KEYWORDS
+canvas, focus, item type, selection, type manager