Tk_CreateImageType(3tk)

🎀 Tk_CreateImageType — define new kind of image 🎀

okay bestie, gather round, because this is the page for Tk_CreateImageType(3tk) from the Tk Library Procedures crew, and it's literally the how-to for inventing your very own ✨custom image type✨ in Tk. it's giving "build your own barbie" but for image managers. no cap 💅

---

🌸 NAME 🌸

Tk_CreateImageType, Tk_GetImageModelData — define new kind of image

---

⭐ SYNOPSIS ⭐

#include <tk.h>

Tk_CreateImageType(typePtr)

void *
Tk_GetImageModelData(interp, name, typePtrPtr)

---

🦋 ARGUMENTS 🦋

• const Tk_ImageType *typePtr (in) — this is the structure that defines your brand-new image type, bestie. for Tk 8.4 and earlier this must be static: the image code keeps a pointer to this structure, so it has to stay alive forever. in Tk 8.5 that limitation was relaxed (glow-up moment, we love to see it).
• Tcl_Interp *interp (in) — the interpreter where the image got created.
• const char *name (in) — the name of an existing image.
• Tk_ImageType **typePtrPtr (out) — points to a word where we stash a pointer to the type info for the given image, if that image actually exists.
• char ***argvPtr (in/out) — pointer to argument list.

---

💖 DESCRIPTION 💖

so Tk_CreateImageType gets invoked to define a new kind of image. an image type corresponds to a particular value of the type argument for the image create command. and here's the best part: there can exist any number of different image types, and new ones can be defined dynamically just by calling Tk_CreateImageType. like, for example, there might be one type for 2-color bitmaps, another for multi-color images, another for dithered images, another for video, and so on and so on. endless possibilities fr fr 🌈

the code that implements a new image type is called an image manager. it consists of a collection of procedures plus three different kinds of data structures. let's break it down 👑

the first data structure is a Tk_ImageType structure, which contains the name of the image type plus pointers to six procedures the image manager provides to deal with images of this type:

typedef struct {
    const char *name;
    Tk_ImageCreateProc *createProc;
    Tk_ImageGetProc *getProc;
    Tk_ImageDisplayProc *displayProc;
    Tk_ImageFreeProc *freeProc;
    Tk_ImageDeleteProc *deleteProc;
    Tk_ImagePostscriptProc *postscriptProc;
} Tk_ImageType;

the fields of this structure get described in later subsections of this entry, so keep scrolling bestie, don't skip ahead (jk skip ahead, i'm not your mom) 🫶

the second major data structure an image manager plays with is called an image model. it contains the overall info about a particular image, like the values of the configuration options specified in an image create command. usually there's one of these structures for each invocation of the image create command.

the third data structure related to images is an image instance. usually there's one of these for each usage of an image in a particular widget. and here's the wild part: it's possible for a single image to appear simultaneously in multiple widgets, or even multiple times in the same widget. furthermore, different instances may be on different screens or displays. the image instance data structure describes things that can vary from instance to instance, like colors and graphics contexts for redisplay. there's usually one instance structure for each -image option specified for a widget or canvas item.

the following subsections describe the fields of a Tk_ImageType in more detail. let's go 💅

🌟 NAME 🌟

typePtr->name provides a name for the image type. once Tk_CreateImageType returns, this name may be used in image create commands to create images of the new type. and heads up: if an image type by this name already existed, then the new image type replaces the old one. (yeah. it ate the original. iconic behavior honestly.)

🌟 CREATEPROC 🌟

typePtr->createProc provides the address of a procedure for Tk to call whenever image create is invoked to create an image of the new type. typePtr->createProc must match the following prototype:

typedef int Tk_ImageCreateProc(
        Tcl_Interp *interp,
        const char *name,
        int objc,
        Tcl_Obj *const objv[],
        const Tk_ImageType *typePtr,
        Tk_ImageModel model,
        void **modelDataPtr);

the interp argument is the interpreter in which the image command was invoked, and name is the name for the new image, which was either specified explicitly in the image command or generated automatically by the image command. the objc and objv arguments describe all the configuration options for the new image (everything after the name argument to image). the model argument is a token that refers to Tk's information about this image; the image manager must return this token to Tk when invoking the Tk_ImageChanged procedure. typically createProc will parse objc and objv and create an image model data structure for the new image. createProc may store an arbitrary one-word value at *modelDataPtr, which will be passed back to the image manager when other callbacks are invoked. typically that value is a pointer to the model data structure for the image.

if createProc encounters an error, it should leave an error message in the interpreter result and return TCL_ERROR; otherwise it should return TCL_OK.

and don't forget, bestie: createProc should call Tk_ImageChanged in order to set the size of the image and request an initial redisplay. 😤

🌟 GETPROC 🌟

typePtr->getProc is invoked by Tk whenever a widget calls Tk_GetImage to use a particular image. this procedure must match the following prototype:

typedef void *Tk_ImageGetProc(
        Tk_Window tkwin,
        void *modelData);

the tkwin argument identifies the window in which the image will be used, and modelData is the value returned by createProc when the image model was created. getProc will usually create a data structure for the new instance, including such things as the resources needed to display the image in the given window. getProc returns a one-word token for the instance, which is typically the address of the instance data structure. Tk will pass this value back to the image manager when invoking its displayProc and freeProc procedures. 🔁

🌟 DISPLAYPROC 🌟

typePtr->displayProc is invoked by Tk whenever an image needs to be displayed (i.e., whenever a widget calls Tk_RedrawImage). displayProc must match the following prototype:

typedef void Tk_ImageDisplayProc(
        void *instanceData,
        Display *display,
        Drawable drawable,
        int imageX,
        int imageY,
        int width,
        int height,
        int drawableX,
        int drawableY);

the instanceData will be the same as the value returned by getProc when the instance was created. display and drawable indicate where to display the image; drawable may be a pixmap rather than the window specified to getProc (this is usually the case, since most widgets double-buffer their redisplay to get smoother visual effects — the drama, the aesthetic, the smoothness). imageX, imageY, width, and height identify the region of the image that must be redisplayed. this region will always be within the size of the image as specified in the most recent call to Tk_ImageChanged. drawableX and drawableY indicate where in drawable the image should be displayed; displayProc should display the given region of the image so that point (imageX, imageY) in the image appears at (drawableX, drawableY) in drawable. coordinate math but make it cute ✨

🌟 FREEPROC 🌟

typePtr->freeProc contains the address of a procedure that Tk will invoke when an image instance is released (i.e., when Tk_FreeImage is invoked). this can happen, for example, when a widget is deleted, or an image item in a canvas is deleted, or when the image displayed in a widget or canvas item is changed. freeProc must match the following prototype:

typedef void Tk_ImageFreeProc(
        void *instanceData,
        Display *display);

the instanceData will be the same as the value returned by getProc when the instance was created, and display is the display containing the window for the instance. freeProc should release any resources associated with the image instance, since the instance will never be used again. it's over, it's done, no take-backs 💀

🌟 DELETEPROC 🌟

typePtr->deleteProc is a procedure that Tk invokes when an image is being deleted (i.e. when the image delete command is invoked). before invoking deleteProc, Tk will invoke freeProc for each of the image's instances. deleteProc must match the following prototype:

typedef void Tk_ImageDeleteProc(
        void *modelData);

the modelData argument will be the same as the value stored in *modelDataPtr by createProc when the image was created. deleteProc should release any resources associated with the image. tea: clean up after yourself, always 💅

🌟 POSTSCRIPTPROC 🌟

typePtr->postscriptProc is a procedure that Tk invokes for generating postscript for the image content. postscriptProc must match the following prototype:

typedef int Tk_ImagePostscriptProc (
        void *clientData,
        Tcl_Interp *interp,
        Tk_Window tkwin,
        Tk_PostscriptInfo psinfo,
        int x,
        int y,
        int width,
        int height,
        int prepass);

🌟 TK_GETIMAGEMODELDATA 🌟

the procedure Tk_GetImageModelData may be invoked to retrieve information about an image. for example, an image manager can use this procedure to locate its image model data for an image. if there exists an image named name in the interpreter given by interp, then *typePtrPtr is filled in with type information for the image (the typePtr value passed to Tk_CreateImageType when the image type was registered) and the return value is the clientData value returned by the createProc when the image was created (this is typically a pointer to the image model data structure). if no such image exists, then NULL is returned and NULL is stored at *typePtrPtr. simple as that 🫶

---

👑 SEE ALSO 👑

Tk_ImageChanged, Tk_GetImage, Tk_FreeImage, Tk_RedrawImage, Tk_SizeOfImage

---

💜 KEYWORDS 💜

image manager, image type, instance, model

---

and that's the whole page, bestie. this one shipped with Tk 8.5 — go forth and build your custom image type, you absolute main character 🧚‍♀️✨