627 lines
23 KiB
Groff
627 lines
23 KiB
Groff
'\"
|
|
'\" 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
|