Manual Pages for UNIX Darwin command on man Tk

Manual Pages for UNIX Darwin command on man Tk_GetItemTypes

TkCreateItemType(3) Tk Library Procedures TkCreateItemType(3)

NAME

TkCreateItemType, TkGetItemTypes - define new kind of canvas item

SYNOPSIS

##iinncclluuddee <>

TTkkCCrreeaatteeIItteemmTTyyppee(typePtr) TkItemType * TTkkGGeettIItteemmTTyyppeess() AARRGGUUMMEENNTTSS TkItemType *typePtr (in) Structure that defines the new type of canvas item. IINNTTRROODDUUCCTTIIOONN TTkkCCrreeaatteeIItteemmTTyyppee is invoked to define a new kind of canvas item

described by the typePtr argument. An item type corresponds to a par-

ticular value of the type argument to the ccrreeaattee 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 rreeccttaann-

ggllee and tteexxtt and iimmaaggee, but TTkkCCrreeaatteeIItteemmTTyyppee allows additional item types to be defined. Once TTkkCCrreeaatteeIItteemmTTyyppee returns, the new item type

may be used in new or existing canvas widgets just like the built-in

item types. TTkkGGeettIItteemmTTyyppeess 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 TTkkCCaannvvaassCCoooorrddss and TTkkCCaannvvaassPPssCCoolloorr; these are described in separate manual entries. DDAATTAA SSTTRRUUCCTTUURREESS 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 TkItemType; it contains information such as the name of the type and pointers to the standard procedures implemented by the type manager: typedef struct TkItemType { char *name; int itemSize; TkItemCreateProc *createProc; TkConfigSpec *configSpecs; TkItemConfigureProc *configProc; TkItemCoordProc *coordProc; TkItemDeleteProc *deleteProc; TkItemDisplayProc *displayProc; int alwaysRedraw; TkItemPointProc *pointProc; TkItemAreaProc *areaProc; TkItemPostscriptProc *postscriptProc; TkItemScaleProc *scaleProc; TkItemTranslateProc *translateProc; TkItemIndexProc *indexProc; TkItemCursorProc *icursorProc; TkItemSelectionProc *selectionProc; TkItemInsertProc *insertProc; TkItemDCharsProc *dCharsProc; TkItemType *nextPtr; } TkItemType; The fields of a TkItemType structure are described in more detail later in this manual entry. When TTkkCCrreeaatteeIItteemmTTyyppee is called, its

typePtr argument must point to a structure with all of the fields ini-

tialized except nextPtr, which Tk sets to link all the types together

into a list. The structure must be in permanent memory (either stati-

cally 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 TkItem; the rest of the item record is defined by the type manager. A type manager must define its item records with a TkItem as the first field. For example, the item record for bitmap items is defined as follows: typedef struct BitmapItem { TkItem header; double x, y; TkAnchor 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 TkItem; 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 TkCanvas; it

serves as an opaque handle for the canvas widget as a whole. Type man-

agers need not know anything about the contents of this structure. A TkCanvas handle is typically passed in to the procedures of a type

manager, and the type manager can pass the handle back to library pro-

cedures such as TkCanvasTkwin to fetch information about the canvas.

NAME

This section and the ones that follow describe each of the fields in a TkItemType structure in detail. The name field provides a string name for the item type. Once TTkkCCrreeaatteeIImmaaggeeTTyyppee returns, this name may be used in ccrreeaattee 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. IITTEEMMSSIIZZEE

typePtr->itemSize gives the size in bytes of item records of this type,

including the TkItem 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. CCRREEAATTEEPPRROOCC

typePtr->createProc points to a procedure for Tk to call whenever a new

item of this type is created. typePtr->createProc must match the fol-

lowing prototype: typedef int TkItemCreateProc( TclInterp *interp, TkCanvas canvas, TkItem *itemPtr, int objc, TclObj* CONST objv); The interp argument is the interpreter in which the canvas's ccrreeaattee

widget command was invoked, and canvas is a handle for the canvas wid-

get. itemPtr is a pointer to a newly-allocated item of size type-

Ptr->itemSize. Tk has already initialized the item's header (the first

ssiizzeeooff((TTkkIItteemmTTyyppee)) bytes). The objc and objv arguments describe all of the arguments to the ccrreeaattee command after the type argument. For example, in the widget command

..cc ccrreeaattee rreeccttaannggllee 1100 2200 5500 5500 -ffiillll bbllaacckk

objc will be 66 and objv[0] will contain the integer object 1100.

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). CCOONNFFIIGGSSPPEECCSS

Each type manager must provide a standard table describing its configu-

ration options, in a form suitable for use with TTkkCCoonnffiigguurreeWWiiddggeett.

This table will normally be used by typePtr->createProc and type-

Ptr->configProc, but Tk also uses it directly to retrieve option infor-

mation in the iitteemmccggeett and iitteemmccoonnffiigguurree widget commands. type-

Ptr->configSpecs must point to the configuration table for this type.

oe T poie a utm pin ye tkCanvasTagsOption o ipe

menting the -ttaaggss option; see an existing type manager for an example

of how to use it in configSpecs. CCOONNFFIIGGPPRROOCC

typePtr->configProc is called by Tk whenever the iitteemmccoonnffiigguurree widget

command is invoked to change the configuration options for a canvas item. This procedure must match the following prototype: typedef int TkItemConfigureProc( TclInterp *interp, TkCanvas canvas, TkItem *itemPtr, int objc, TclObj* CONST objv, int flags);

The interp objument identifies the interpreter in which the widget com-

mand was invoked, canvas is a handle for the canvas widget, and

itemPtr is a pointer to the item being configured. objc and objv con-

tain the configuration options. For example, if the following command is invoked:

..cc iitteemmccoonnffiigguurree 22 -ffiillll rreedd -oouuttlliinnee bbllaacckk

objc is 44 and objv contains the string objects -ffiillll through bbllaacckk.

objc will always be an even value. The flags argument contains flags

to pass to TTkkCCoonnffiigguurreeWWiiddggeett; currently this value is always TKCON-

FIGARGVONLY when Tk invokes typePtr->configProc, but the type man-

ager's createProc procedure will usually invoke configProc with differ-

ent flag values.

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. CCOOOORRDDPPRROOCC

typePtr->coordProc is invoked by Tk to implement the ccoooorrddss widget com-

mand for an item. It must match the following prototype: typedef int TkItemCoordProc( TclInterp *interp, TkCanvas canvas, TkItem *itemPtr, int objc, TclObj* CONST objv);

The arguments interp, canvas, and itemPtr all have the standard mean-

ings, and objc and objv describe the coordinate arguments. For exam-

ple, if the following widget command is invoked: ..cc ccoooorrddss 22 3300 9900 objc will be 22 and oobbjjvv will contain the integer objects 3300 and 9900. 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.

DDEELLEETTEEPPRROOCC

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 TkItemDeleteProc( TkCanvas canvas, TkItem *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. DDIISSPPLLAAYYPPRROOCC AANNDD AALLWWAAYYSSRREEDDRRAAWW

typePtr->displayProc is invoked by Tk to redraw an item on the screen.

It must match the following prototype: typedef void TkItemDisplayProc( TkCanvas canvas, TkItem *itemPtr, Display *display, Drawable dst, int x, int y, int width, int height);

The canvas and itemPtr arguments have the usual meaning. display iden-

tifies 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 TTkkCCaannvvaass-

DDrraawwaabblleeCCoooorrddss 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 doesn't 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.

PPOOIINNTTPPRROOCC

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 TkItemPointProc( TkCanvas canvas, TkItem *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. AARREEAAPPRROOCC

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 TkItemAreaProc( TkCanvas canvas, TkItem *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. PPOOSSTTSSCCRRIIPPTTPPRROOCC

typePtr->postscriptProc is invoked by Tk to generate Postcript for an

item during the ppoossttssccrriipptt 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 TkItemPostscriptProc( TclInterp *interp, TkCanvas canvas, TkItem *itemPtr, int prepass); The interp, canvas, and itemPtr arguments all have standard meanings;

prepass will be described below. If postscriptProc completes success-

fully, it should append Postscript for the item to the information in

interp->result (e.g. by calling TTccllAAppppeennddRReessuulltt, not TTccllSSeettRReessuulltt)

and return TCLOK. If an error occurs, postscriptProc should clear the result and replace its contents with an error message; then it should

return TCLERROR.

Tk provides a collection of utility procedures to simplify postscript-

Proc. For example, TTkkCCaannvvaassPPssCCoolloorr will generate Postscript to set the current color to a given Tk color and TTkkCCaannvvaassPPssFFoonntt 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 ggssaavvee and ggrreessttoorree commands around the Postscript for the item.

The type manager can use canvas x coordinates directly in its Post-

script, but it must call TTkkCCaannvvaassPPssYY 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 TTkkCCaannvvaassPPssFFoonntt); 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 TTkkCCaannvvaassPPssFFoonntt. During the second pass prepass will be 0, so the type manager must generate complete Postscript. SSCCAALLEEPPRROOCC

typePtr->scaleProc is invoked by Tk to rescale a canvas item during the

ssccaallee widget command. The procedure must match the following proto-

type: typedef void TkItemScaleProc( TkCanvas canvas, TkItem *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. TTRRAANNSSLLAATTEEPPRROOCC

typePtr->translateProc is invoked by Tk to translate a canvas item dur-

ing the mmoovvee widget command. The procedure must match the following prototype: typedef void TkItemTranslateProc( TkCanvas canvas, TkItem *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. IINNDDEEXXPPRROOCC

typePtr->indexProc is invoked by Tk to translate a string index speci-

fication into a numerical index, for example during the iinnddeexx widget command. It is only relevant for item types that support indexable

text; typePtr->indexProc may be specified as NULL for non-textual item

types. The procedure must match the following prototype: typedef int TkItemIndexProc( TclInterp *interp, TkCanvas canvas, TkItem *itemPtr, char indexString, int *indexPtr); The interp, canvas, and itemPtr arguments all have the usual meaning. indexString contains a textual description of an index, and indexPtr 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, iinnsseerrtt, sseell..ffiirrsstt, eenndd, etc.). indexProc

should return a Tcl completion code and set interp->result in the event

of an error. IICCUURRSSOORRPPRROOCC

typePtr->icursorProc is invoked by Tk during the iiccuurrssoorr 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; type-

Ptr->icursorProc may be specified as NULL for item types that don't

support an insertion cursor. The procedure must match the following prototype: typedef void TkItemCursorProc( TkCanvas canvas, TkItem *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 dis-

play the insertion cursor is determined by other information provided by TTkkCCaannvvaassGGeettTTeexxttIInnffoo. SSEELLEECCTTIIOONNPPRROOCC

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->selec-

tionProc may be specified as NULL for non-textual item types. The pro-

cedure must match the following prototype: typedef int TkItemSelectionProc( TkCanvas canvas, TkItem *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 selec-

tion; 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 aren't offset+maxBytes bytes in the selection. IINNSSEERRTTPPRROOCC

typePtr->insertProc is invoked by Tk during the iinnsseerrtt 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 TkItemInsertProc( TkCanvas canvas, TkItem *itemPtr, int index, char *string); 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

string contains new text to insert just before the character given by index. The type manager should insert the text and recompute the bounding box in the item's header. DDCCHHAARRSSPPRROOCC

typePtr->dCharsProc is invoked by Tk during the ddcchhaarrss 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 follow-

ing prototype: typedef void TkItemDCharsProc( TkCanvas canvas, TkItem *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 pre-

vious calls to typePtr->indexProc. The type manager should delete the

specified characters and update the bounding box in the item's header.