Tribblix: manual page: Tk

Tk_CreateItemType(3) Tk Library Procedures Tk_CreateItemType(3)

____________________________________________________________________________

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:

.c coords 2 30 90

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 (x - originX)
y' = originY + scaleY x (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.

KEYWORDS

canvas, focus, item type, selection, type manager

Tk 4.0 Tk_CreateItemType(3)

NAME

SYNOPSIS

ARGUMENTS

INTRODUCTION

DATA STRUCTURES

NAME

ITEMSIZE

CREATEPROC

CONFIGSPECS

CONFIGPROC

COORDPROC

DELETEPROC

DISPLAYPROC

POINTPROC

AREAPROC

POSTSCRIPTPROC

SCALEPROC

TRANSLATEPROC

INDEXPROC

ICURSORPROC

SELECTIONPROC

INSERTPROC

DCHARSPROC

SEE ALSO

KEYWORDS