NAME¶
Tk_CreateItemType, Tk_GetItemTypes - define new kind of canvas item
SYNOPSIS¶
#include <tk.h>
Tk_CreateItemType(typePtr)
Tk_ItemType *
Tk_GetItemTypes()
ARGUMENTS¶
- Tk_ItemType *typePtr (in)
- Structure that defines the new type of canvas item.
INTRODUCTION¶
Tk_CreateItemType is invoked to define a new kind of canvas item
described by the
typePtr argument. An item type corresponds to a
particular value of the
type argument to the
create widget
command for canvases, and the code that implements a canvas item type is
called a
type manager. Tk defines several built-in item types, such as
rectangle and
text and
image, but
Tk_CreateItemType allows additional item types to be defined. Once
Tk_CreateItemType returns, the new item type may be used in new or
existing canvas widgets just like the built-in item types.
Tk_GetItemTypes 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
nextPtr fields, with the end of the list marked
by a NULL
nextPtr.
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 (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.
Tk provides a number of utility procedures for the use of canvas type managers,
such as
Tk_CanvasCoords and
Tk_CanvasPsColor; these are
described in separate manual entries.
DATA STRUCTURES¶
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:
typedef struct Tk_ItemType {
const char * name;
int itemSize;
Tk_ItemCreateProc * createProc;
const Tk_ConfigSpec * configSpecs;
Tk_ItemConfigureProc * configProc;
Tk_ItemCoordProc * coordProc;
Tk_ItemDeleteProc * deleteProc;
Tk_ItemDisplayProc * displayProc;
int alwaysRedraw;
Tk_ItemPointProc * pointProc;
Tk_ItemAreaProc * areaProc;
Tk_ItemPostscriptProc * postscriptProc;
Tk_ItemScaleProc * scaleProc;
Tk_ItemTranslateProc * translateProc;
Tk_ItemIndexProc * indexProc;
Tk_ItemCursorProc * icursorProc;
Tk_ItemSelectionProc * selectionProc;
Tk_ItemInsertProc * insertProc;
Tk_ItemDCharsProc * dCharsProc;
Tk_ItemType * nextPtr;
} Tk_ItemType;
The fields of a Tk_ItemType structure are described in more detail later in this
manual entry. When
Tk_CreateItemType is called, its
typePtr
argument must point to a structure with all of the fields initialized except
nextPtr, 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.
The second data structure manipulated by a type manager is an
item
record. 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:
typedef struct BitmapItem {
Tk_Item header;
double x, y;
Tk_Anchor anchor;
Pixmap bitmap;
XColor * fgColor;
XColor * bgColor;
GC gc;
} BitmapItem;
The
header 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
x 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
x1,
y1,
x2, and
y2. 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
x1 or y-coordinate lower than
y1,
nor should it cover any pixels with x-coordinate greater than or equal to
x2 or y-coordinate greater than or equal to
y2. It is up to the
type manager to keep the bounding box up to date as the item is moved and
reconfigured.
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.
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.
TK_ITEMTYPE FIELDS¶
NAME¶
This section and the ones that follow describe each of the fields in a
Tk_ItemType structure in detail. The
name field provides a string name
for the item type. Once
Tk_CreateImageType returns, this name may be
used in
create 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.
FLAGS (IN ALWAYSREDRAW)¶
The
typePtr->alwaysRedraw 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:
- 1
- 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.
- TK_CONFIG_OBJS
- 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
configProc, the coordProc, the createProc, the
indexProc and the insertProc.
- TK_MOVABLE_POINTS
- Indicates that the item supports the dCharsProc, indexProc
and insertProc 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.
ITEMSIZE¶
typePtr->itemSize 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.
CREATEPROC¶
typePtr->createProc points to a procedure for Tk to call whenever a
new item of this type is created.
typePtr->createProc must match the
following prototype:
typedef int Tk_ItemCreateProc(
Tcl_Interp * interp,
Tk_Canvas canvas,
Tk_Item * itemPtr,
int objc,
Tcl_Obj *const objv[]);
The
interp argument is the interpreter in which the canvas's
create widget command was invoked, and
canvas is a handle for
the canvas widget.
itemPtr is a pointer to a newly-allocated item of
size
typePtr->itemSize. Tk has already initialized the item's header
(the first
sizeof(Tk_ItemType) bytes). The
objc and
objv
arguments describe all of the arguments to the
create command after the
type argument. Note that if
TK_CONFIG_OBJS is not set in the
typePtr->alwaysRedraw field, the
objv parameter will actually
contain a pointer to an array of constant strings. For example, in the widget
command:
.c create rectangle 10 20 50 50 -fill black
objc will be
6 and
objv[0] will contain the integer object
10.
createProc should use
objc and
objv 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 the interpreter result if an error occurs.
If an error occurs Tk will free the item record, so
createProc 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).
CONFIGSPECS¶
Each type manager must provide a standard table describing its configuration
options, in a form suitable for use with
Tk_ConfigureWidget. This table
will normally be used by
typePtr->createProc and
typePtr->configProc, but Tk also uses it directly to retrieve option
information in the
itemcget and
itemconfigure widget commands.
typePtr->configSpecs must point to the configuration table for this
type. Note: Tk provides a custom option type
tk_CanvasTagsOption for
implementing the
-tags option; see an existing type manager for an
example of how to use it in
configSpecs.
CONFIGPROC¶
typePtr->configProc is called by Tk whenever the
itemconfigure
widget command is invoked to change the configuration options for a canvas
item. This procedure must match the following prototype:
typedef int Tk_ItemConfigureProc(
Tcl_Interp * interp,
Tk_Canvas canvas,
Tk_Item * itemPtr,
int objc,
Tcl_Obj *const objv[],
int flags);
The
interp argument identifies the interpreter in which the widget
command was invoked,
canvas is a handle for the canvas widget, and
itemPtr is a pointer to the item being configured.
objc and
objv contain the configuration options. Note that if
TK_CONFIG_OBJS is not set in the
typePtr->alwaysRedraw field,
the
objv parameter will actually contain a pointer to an array of
constant strings. For example, if the following command is invoked:
.c itemconfigure 2 -fill red -outline black
objc is
4 and
objv contains the string objects
-fill
through
black.
objc will always be an even value. The
flags argument contains flags to pass to
Tk_ConfigureWidget;
currently this value is always
TK_CONFIG_ARGV_ONLY when Tk invokes
typePtr->configProc, but the type manager's
createProc
procedure will usually invoke
configProc with different flag values.
typePtr->configProc 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.
COORDPROC¶
typePtr->coordProc is invoked by Tk to implement the
coords
widget command for an item. It must match the following prototype:
typedef int Tk_ItemCoordProc(
Tcl_Interp * interp,
Tk_Canvas canvas,
Tk_Item * itemPtr,
int objc,
Tcl_Obj *const objv[]);
The arguments
interp,
canvas, and
itemPtr all have the
standard meanings, and
objc and
objv describe the coordinate
arguments. Note that if
TK_CONFIG_OBJS is not set in the
typePtr->alwaysRedraw field, the
objv parameter will actually
contain a pointer to an array of constant strings. For example, if the
following widget command is invoked:
objc will be
2 and
objv will contain the integer objects
30 and
90.
The
coordProc 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,
coordProc must leave an error message in the interpreter result.
DELETEPROC¶
typePtr->deleteProc is invoked by Tk to delete an item and free any
resources allocated to it. It must match the following prototype:
typedef void Tk_ItemDeleteProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
Display * display);
The
canvas and
itemPtr arguments have the usual interpretations,
and
display identifies the X display containing the canvas.
deleteProc must free up any resources allocated for the item, so that
Tk can free the item record.
deleteProc should not actually free the
item record; this will be done by Tk when
deleteProc returns.
DISPLAYPROC¶
typePtr->displayProc is invoked by Tk to redraw an item on the screen.
It must match the following prototype:
typedef void Tk_ItemDisplayProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
Display * display,
Drawable dst,
int x,
int y,
int width,
int height);
The
canvas and
itemPtr arguments have the usual meaning.
display identifies the display containing the canvas, and
dst
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.
x,
y,
width, and
height 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
displayProc 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.
Because of scrolling and the use of off-screen pixmaps for double-buffered
redisplay, the item's coordinates in
dst will not necessarily be the
same as those in the canvas.
displayProc should call
Tk_CanvasDrawableCoords to transform coordinates from those of the
canvas to those of
dst.
Normally an item's
displayProc is only invoked if the item overlaps the
area being displayed. However, if bit zero of
typePtr->alwaysRedraw
is 1, (i.e. “
typePtr->alwaysRedraw & 1 == 1”)
then
displayProc 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.
POINTPROC¶
typePtr->pointProc 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:
typedef double Tk_ItemPointProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
double * pointPtr);
canvas and
itemPtr have the usual meaning.
pointPtr points
to an array of two numbers giving the x and y coordinates of a point.
pointProc must return a real value giving the distance from the point
to the item, or 0 if the point lies inside the item.
AREAPROC¶
typePtr->areaProc is invoked by Tk to find out the relationship
between an item and a rectangular area. It must match the following prototype:
typedef int Tk_ItemAreaProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
double * rectPtr);
canvas and
itemPtr have the usual meaning.
rectPtr 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.
areaProc 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.
POSTSCRIPTPROC¶
typePtr->postscriptProc is invoked by Tk to generate Postscript for an
item during the
postscript widget command. If the type manager is not
capable of generating Postscript then
typePtr->postscriptProc should
be NULL. The procedure must match the following prototype:
typedef int Tk_ItemPostscriptProc(
Tcl_Interp * interp,
Tk_Canvas canvas,
Tk_Item * itemPtr,
int prepass);
The
interp,
canvas, and
itemPtr arguments all have standard
meanings;
prepass will be described below. If
postscriptProc
completes successfully, it should append Postscript for the item to the
information in the interpreter result (e.g. by calling
Tcl_AppendResult, not
Tcl_SetResult) and return
TCL_OK.
If an error occurs,
postscriptProc should clear the result and replace
its contents with an error message; then it should return
TCL_ERROR.
Tk provides a collection of utility procedures to simplify
postscriptProc. For example,
Tk_CanvasPsColor will generate
Postscript to set the current color to a given Tk color and
Tk_CanvasPsFont 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
gsave and
grestore
commands around the Postscript for the item. The type manager can use canvas x
coordinates directly in its Postscript, but it must call
Tk_CanvasPsY
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).
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
postscriptProc in each pass. The only purpose of the
first pass is to collect font information (which is done by
Tk_CanvasPsFont); the actual Postscript is discarded. Tk sets the
prepass argument to
postscriptProc to 1 during the first pass;
the type manager can use
prepass to skip all Postscript generation
except for calls to
Tk_CanvasPsFont. During the second pass
prepass will be 0, so the type manager must generate complete
Postscript.
SCALEPROC¶
typePtr->scaleProc is invoked by Tk to rescale a canvas item during
the
scale widget command. The procedure must match the following
prototype:
typedef void Tk_ItemScaleProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
double originX,
double originY,
double scaleX,
double scaleY);
The
canvas and
itemPtr arguments have the usual meaning.
originX and
originY specify an origin relative to which the item
is to be scaled, and
scaleX and
scaleY 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
x and
y will have new coordinates
x′ and
y′, where
x′ = originX + scaleX × (x − originX)
y′ = originY + scaleY × (y − originY)
scaleProc must also update the bounding box in the item's header.
TRANSLATEPROC¶
typePtr->translateProc is invoked by Tk to translate a canvas item
during the
move widget command. The procedure must match the following
prototype:
typedef void Tk_ItemTranslateProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
double deltaX,
double deltaY);
The
canvas and
itemPtr arguments have the usual meaning, and
deltaX and
deltaY 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.
INDEXPROC¶
typePtr->indexProc is invoked by Tk to translate a string index
specification into a numerical index, for example during the
index
widget command. It is only relevant for item types that support indexable text
or coordinates;
typePtr->indexProc 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:
typedef int Tk_ItemIndexProc(
Tcl_Interp * interp,
Tk_Canvas canvas,
Tk_Item * itemPtr,
Tcl_Obj * indexObj,
int * indexPtr);
The
interp,
canvas, and
itemPtr arguments all have the
usual meaning.
indexObj contains a textual description of an index, and
indexPtr points to an integer value that should be filled in with a
numerical index. Note that if
TK_CONFIG_OBJS is not set in the
typePtr->alwaysRedraw field, the
indexObj parameter will
actually contain a pointer to a constant string. It is up to the type manager
to decide what forms of index are supported (e.g., numbers,
insert,
sel.first,
end, etc.).
indexProc should return a Tcl
completion code and set the interpreter result in the event of an error.
ICURSORPROC¶
typePtr->icursorProc is invoked by Tk during the
icursor 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;
typePtr->icursorProc may be specified as NULL for item types that do
not support an insertion cursor. The procedure must match the following
prototype:
typedef void Tk_ItemCursorProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
int index);
canvas and
itemPtr have the usual meanings, and
index is an
index into the item's text, as returned by a previous call to
typePtr->insertProc. The type manager should position the insertion
cursor in the item just before the character given by
index. Whether or
not to actually display the insertion cursor is determined by other
information provided by
Tk_CanvasGetTextInfo.
SELECTIONPROC¶
typePtr->selectionProc 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;
typePtr->selectionProc may be specified as NULL for non-textual item
types. The procedure must match the following prototype:
typedef int Tk_ItemSelectionProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
int offset,
char * buffer,
int maxBytes);
canvas and
itemPtr have the usual meanings.
offset 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.
buffer points to an area of memory in which to store the
requested bytes, and
maxBytes specifies the maximum number of bytes to
return.
selectionProc should extract up to
maxBytes characters
from the selection and copy them to
maxBytes; it should return a count
of the number of bytes actually copied, which may be less than
maxBytes
if there are not
offset+maxBytes bytes in the selection.
INSERTPROC¶
typePtr->insertProc is invoked by Tk during the
insert widget
command to insert new text or coordinates into a canvas item. It is only
relevant for item types that support the
insert method;
typePtr->insertProc may be specified as NULL for other item types.
The procedure must match the following prototype:
typedef void Tk_ItemInsertProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
int index,
Tcl_Obj * obj);
canvas and
itemPtr have the usual meanings.
index is an
index into the item's text, as returned by a previous call to
typePtr->insertProc, and
obj contains new text to insert just
before the character given by
index. Note that if
TK_CONFIG_OBJS
is not set in the
typePtr->alwaysRedraw field, the
obj
parameter will actually contain a pointer to a constant string to be inserted.
If the item supports modification of the coordinates list by this
The type manager should insert the text and recompute the bounding box in the
item's header.
DCHARSPROC¶
typePtr->dCharsProc is invoked by Tk during the
dchars 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;
typePtr->dCharsProc 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:
typedef void Tk_ItemDCharsProc(
Tk_Canvas canvas,
Tk_Item * itemPtr,
int first,
int last);
canvas and
itemPtr have the usual meanings.
first and
last give the indices of the first and last bytes to be deleted, as
returned by previous calls to
typePtr->indexProc. The type manager
should delete the specified characters and update the bounding box in the
item's header.
SEE ALSO¶
Tk_CanvasPsY, Tk_CanvasTextInfo, Tk_CanvasTkwin
KEYWORDS¶
canvas, focus, item type, selection, type manager