#include <tk.h> Tk_CreateItemType(typePtr) Tk_ItemType * Tk_GetItemTypes()
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 (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.
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 { char *name; int itemSize; Tk_ItemCreateProc *createProc; 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;
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.
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.
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[]);
.c create rectangle 10 20 50 50 -fill black
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 interp->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).
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.
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);
.c itemconfigure 2 -fill red -outline black
typePtr->configProc returns a standard Tcl completion code and leaves an error message in interp->result if an error occurs. It must update the item's bounding box to reflect the new configuration options.
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[]);
.c coords 2 30 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 interp->result.
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);
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);
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 typePtr->alwaysRedraw has a non-zero value, then displayProc is invoked during every redisplay operation, even if the item does not overlap the area of redisplay. alwaysRedraw 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.
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);
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);
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);
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.
typedef void Tk_ItemScaleProc( Tk_Canvas canvas, Tk_Item *itemPtr, double originX, double originY, double scaleX, double scaleY);
x´ = originX + scaleX*(x-originX) y´ = originY + scaleY*(y-originY)
typedef void Tk_ItemTranslateProc( Tk_Canvas canvas, Tk_Item *itemPtr, double deltaX, double deltaY);
typedef int Tk_ItemIndexProc( Tcl_Interp *interp, Tk_Canvas canvas, Tk_Item *itemPtr, char indexString, int *indexPtr);
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);
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);
typePtr->insertProc is invoked by Tk during the insert widget command to insert new text into a canvas item. It is only relevant for item types that support text; typePtr->insertProc may be specified as NULL for non-textual item types. The procedure must match the following prototype:
typedef void Tk_ItemInsertProc( Tk_Canvas canvas, Tk_Item *itemPtr, int index, char *string);
typePtr->dCharsProc is invoked by Tk during the dchars widget command to delete a range of text from a canvas item. It is only relevant for item types that support text; typePtr->dCharsProc may be specified as NULL for non-textual item types. The procedure must match the following prototype:
typedef void Tk_ItemDCharsProc( Tk_Canvas canvas, Tk_Item *itemPtr, int first, int last);