Tk_CreateItemType(3tk)

yo bestie, welcome to the Tk_CreateItemType(3tk) man page from the Tk Library Procedures! this is part 1 of 3, so let's get into it 💖✨

✨ NAME ✨

Tk_CreateItemType, Tk_GetItemTypes — define a new kind of canvas item 💅

🌸 SYNOPSIS 🌸

#include <tk.h>

Tk_CreateItemType(typePtr)

Tk_ItemType *
Tk_GetItemTypes()

🎀 ARGUMENTS 🎀

• Tk_ItemType *typePtr (in) — this is the structure that defines the new type of canvas item. note that this is NOT const; Tk may write to these structures. no cap. 💅

🌈 INTRODUCTION 🌈

okay so Tk_CreateItemType is what you call to define a brand new kind of canvas item, and it's all described by the typePtr argument. an item type is basically the vibe for 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 already has several built-in item types, like rectangle, text, and image, but Tk_CreateItemType lets you add more. once Tk_CreateItemType returns, your new item type can be used in new or existing canvas widgets just like the built-in ones. slay. 💅

Tk_GetItemTypes returns a pointer to the first item type in the list of all item types currently defined for canvases. the entries are linked together through their nextPtr fields, and the end of the list is marked by a NULL nextPtr. periodt.

ngl, you might find it easier to understand the rest of this manual entry by looking at the code for an existing canvas item type, like 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 your new type. it's giving 'work smarter, not harder'. 💅

Tk also provides a bunch of utility procedures for canvas type managers, like Tk_CanvasCoords and Tk_CanvasPsColor; those are described in separate manual entries. iykyk.

💎 DATA STRUCTURES 💎

a type manager is 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 info like the name of the type and pointers to the standard procedures implemented by the type manager:

typedef struct Tk_ItemType {
    const char *name;
    Tcl_Size itemSize;
    Tk_ItemCreateProc *createProc;
    const Tk_ConfigSpec *configSpecs;
    Tk_ItemConfigureProc *configProc;
    Tk_ItemCoordProc *coordProc;
    Tk_ItemDeleteProc *deleteProc;
    Tk_ItemDisplayProc *displayProc;
    int flags;
    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;
    struct Tk_ItemType *nextPtr;
    Tk_ItemRotateProc *rotateProc;                                2
} Tk_ItemType;

the fields of a Tk_ItemType structure are described in more detail later in this manual entry. when you call Tk_CreateItemType, your typePtr argument must point to a structure with all 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. so don't free it, bestie. 💀

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 {
    Tk_Item header;
    double x, y;
    Tk_Anchor anchor;
    Pixmap bitmap;
    XColor *fgColor;
    XColor *bgColor;
    GC gc;
} BitmapItem;

the header substructure has info that Tk uses to manage the item, like 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 shouldn't 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's up to the type manager to keep the bounding box up to date as the item is moved and reconfigured. so stay on top of it, bestie. 💅

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, like BitmapItem. it's giving 'type casting realness'. 💅

the third data structure used by type managers has type Tk_Canvas; it's an opaque handle for the canvas widget as a whole. type managers don't need to know anything about what's inside 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 like Tk_CanvasTkwin to fetch info about the canvas. mystery box vibes. 🎁

👑 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. bye bye old type. 💅

FLAGS (IN ALWAYSREDRAW)

the typePtr->flags field contains a collection of flag bits that modify how the canvas core interacts with the item. the following bits are defined:

• TK_ALWAYS_REDRAW — 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_MOVABLE_POINTS — indicates that the item supports the dCharsProc, indexProc and 2 insertProc with the same semantics as Tk's built-in line and 2 polygon types, and that hence individual coordinate points can be 2 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 (like 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. flexible but consistent, periodt. 💅

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. 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). no pressure, but don't leak memory bestie. 💀

CONFIGSPECS

every 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 info in the itemcget and itemconfigure widget commands. typePtr->configSpecs must point to the configuration table for this type. 💅

note that 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. iykyk. ✨

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. for example, if the following command is invoked:

.c itemconfigure 2 -fill red -outline black

Okay so if you're vibing with .c itemconfigure and the user is all "make it pink bestie," Tk doesn't hand you that for free — it calls your configProc. Here's the tea on what lands in your lap: objc is 4 and objv contains the string objects -fill through black. 💅 And objc will always be an even value — no odd-numbered chaos, ever. 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. And it must update the item's bounding box to reflect the new configuration options — like, no skipping that part, the bounding box is not optional, it's the whole point. 🎀

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. 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 — yes queen, the bounding box again, it's giving main character energy), 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. But here's the critical bit, bestie: deleteProc should not actually free the item record; this will be done by Tk when deleteProc returns. Do not double-free. Do not be that girl. 🙈

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->flags is 1, (i.e. “typePtr->flags & 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. Three possible answers, no vibes-based improvisation, okay? 💀

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 — do not clobber the result, bestie, that's a crime) 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). The y-axis flip is real, y'all. 🙈

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. ✨ Two passes, two moods, both necessary.

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. (Bounding box. Again. She's everywhere. She's iconic. 👑)

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

ROTATEPROC

typePtr->rotateProc is invoked by Tk to rotate a canvas item during the rotate widget command. The procedure must match the following prototype:

typedef void Tk_ItemRotateProc(
        Tk_Canvas canvas,
        Tk_Item *itemPtr,
        double originX,
        double originY,
        double angleRad);

The canvas and itemPtr arguments have the usual meaning. originX and originY specify an origin relative to which the item is to be rotated, and angleRad gives the anticlockwise rotation to be applied in radians. The item should adjust the coordinates of its control points so that where they used to have coordinates x and y, they will have new coordinates x′ and y′, where

relX = x − originX
relY = y − originY
x′ = originX + relX × cos(angleRad) + relY × sin(angleRad)
y′ = originY − relX × sin(angleRad) + relY × cos(angleRad)

Trig girlies stay winning. 🌸 Rotation is anticlockwise, radians not degrees, no cap. ✨

The control points for an item are not necessarily the coordinates that got handed to the item when it was created (or via the typePtr->coordProc) — they could totally be derived from them instead. And rotateProc also has to update the bounding box in the item's header. No skipping that part, bestie. 💖

Item types do not have to provide a typePtr->rotateProc, and that's fine. If typePtr->rotateProc is NULL, then typePtr->coordProc gets used instead to retrieve and update the list of coordinates. Slay, it's a built-in fallback. ✨

🎀 INDEXPROC 🎀

typePtr->indexProc gets invoked by Tk whenever it needs to translate a string index specification into a numerical index — like during the index widget command, iykyk. It's only relevant for item types that support indexable text or coordinates; for non-textual item types, typePtr->indexProc may be specified as NULL if they don't support detailed coordinate addressing. The procedure must match this 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 mean the usual thing. indexObj contains a textual description of an index, and indexPtr points to an integer value that should be filled in with a numerical index. Deciding what forms of index are supported is entirely up to the type manager (e.g. numbers, insert, sel.first, end, etc.). indexProc should return a Tcl completion code and set the interpreter result if there's an error. Periodt. 💅

🌸 ICURSORPROC 🌸

typePtr->icursorProc gets invoked by Tk during the icursor widget command to set the position of the insertion cursor in a textual item. It's only relevant for item types that support an insertion cursor; typePtr->icursorProc may be specified as NULL for item types that don't support an insertion cursor. The procedure must match this prototype:

typedef void Tk_ItemCursorProc(
        Tk_Canvas canvas,
        Tk_Item *itemPtr,
        int index);

canvas and itemPtr mean the usual things, 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 the insertion cursor actually gets displayed is determined by other information provided by Tk_CanvasGetTextInfo. So like, that part is not your problem. 🙈

🦋 SELECTIONPROC 🦋

typePtr->selectionProc gets invoked by Tk during selection retrievals; it must return part or all of the selected text in the item (if there is any). It's only relevant for item types that support text; typePtr->selectionProc may be specified as NULL for non-textual item types. The procedure must match this prototype:

typedef int Tk_ItemSelectionProc(
        Tk_Canvas canvas,
        Tk_Item *itemPtr,
        int offset,
        char *buffer,
        int maxBytes);

canvas and itemPtr mean the usual things. 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. Math check, every time. 🧮✨

💜 INSERTPROC 💜

typePtr->insertProc gets invoked by Tk during the insert widget command to insert new text or coordinates into a canvas item. It's 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 this prototype:

typedef void Tk_ItemInsertProc(
        Tk_Canvas canvas,
        Tk_Item *itemPtr,
        int index,
        Tcl_Obj *obj);

canvas and itemPtr mean the usual things. 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. 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.

Yeah bestie, that sentence above just... ends there. That's literally how it is in the original, no cap. 🫶

🍓 DCHARSPROC 🍓

typePtr->dCharsProc gets 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's 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 this prototype:

typedef void Tk_ItemDCharsProc(
        Tk_Canvas canvas,
        Tk_Item *itemPtr,
        int first,
        int last);

canvas and itemPtr mean the usual things. 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. Bye bye, bytes. 👋💀

---

🌈 SEE ALSO 🌈

• Tk_CanvasPsY
• Tk_CanvasTextInfo
• Tk_CanvasTkwin

---

⭐ KEYWORDS ⭐

• canvas
• focus
• item type
• selection
• type manager

---

And that's a wrap on the whole thing, bestie!! 🎉👑 You just read the entire Tk_CreateItemType(3tk) page from Tk, version 4.0 — main character documentation energy from start to finish. Go forth and build your item types, you absolute icon. 💖🦋✨