Tk_GetImage(3tk)

💖 NAME 💖

Tk_GetImage, Tk_RedrawImage, Tk_SizeOfImage, Tk_FreeImage — bestie, this is how a widget shows an image. That's the whole vibe. ✨

This page lives in the Tk Library Procedures section of the manual, section 3tk, and it's your backstage pass to the image pipeline. 🎀

---

🌸 SYNOPSIS 🌸

#include <tk.h>

Tk_Image
Tk_GetImage(interp, tkwin, name, changeProc, clientData)

Tk_RedrawImage(image, imageX, imageY, width, height, drawable, drawableX, drawableY)

Tk_SizeOfImage(image, widthPtr, heightPtr)

Tk_FreeImage(image)

---

🦋 ARGUMENTS 🦋

okay so here's every single one, no skips, no shortcuts, we're doing this properly 💅

• Tcl_Interp *interp (in) — where the error message gets dropped off. That's its whole job.
• Tk_Window tkwin (in) — the window this image is gonna be used in.
• const char *name (in) — the name of the image. yep, just the name.
• Tk_ImageChangedProc *changeProc (in) — the procedure Tk invokes whenever the image's content or size changes. Tk calls it, you write it, that's the deal.
• void *clientData (in) — a one-word value that Tk hands straight over to changeProc. one word. that's all you get. 🫶
• Tk_Image image (in) — a token for an image instance. it must have come back from a previous call to Tk_GetImage, no improvising.
• int imageX (in) — x-coordinate of the upper-left corner of the region of the image you wanna redisplay, measured in pixels from the image's upper-left corner.
• int imageY (in) — y-coordinate of the upper-left corner of the region of the image you wanna redisplay, also measured in pixels from the image's upper-left corner.
• int width ((in)) — width of the region of the image to redisplay.
• int height ((in)) — height of the region of the image to redisplay.
• Drawable drawable (in) — where to display the image. it has to either be the window you specified to Tk_GetImage, or a pixmap that's compatible with that window. no random drawables, bestie.
• int drawableX (in) — where to display the image inside drawable: this is the x-coordinate in drawable where x-coordinate imageX of the image should be displayed.
• int drawableY (in) — where to display the image inside drawable: this is the y-coordinate in drawable where y-coordinate imageY of the image should be displayed.
• int widthPtr (out) — store the width of the image, in pixels, right here. 📏
• int heightPtr (out) — store the height of the image, in pixels, right here. 📐

---

✨ DESCRIPTION ✨

These procedures get invoked by widgets that wish to display images. So like, if you're building a widget and you want it to show a pic? this is the group chat you join. 💖

Tk_GetImage gets invoked by a widget when it first decides it's gonna display an image. name gives the name of the desired image, and tkwin identifies the window where the image will be displayed. Tk_GetImage looks the image up in the table of existing images and returns a token for a new instance of the image. And if the image doesn't exist? it returns NULL and leaves an error message in interpreter interp's result. iconic behaviour honestly.

When a widget wishes to actually display an image, it must call Tk_RedrawImage, identifying the image (image), a region within the image to redisplay (imageX, imageY, width, and height), and a place to display the image (drawable, drawableX, and drawableY). Tk will then invoke the appropriate image manager, which will display the requested portion of the image before returning. yes, before returning. that's the whole thing. 🎀

A widget can find out the dimensions of an image by calling Tk_SizeOfImage: the width and height will be stored in the locations given by widthPtr and heightPtr, respectively.

When a widget is finished with an image — like, the widget is being deleted, or it's going to use a different image instead of the current one — it must call Tk_FreeImage to release the image instance.

⚠️ bestie listen. the widget should never again use the image token after passing it to Tk_FreeImage. and there must be exactly one call to Tk_FreeImage for each call to Tk_GetImage. one in, one out. that's the rule. 💀

If the contents or size of an image changes, then any widgets using the image will need to find out about the changes so they can redisplay themselves. The changeProc and clientData arguments to Tk_GetImage exist for exactly this purpose. changeProc will be called by Tk whenever a change occurs in the image; it must match the following prototype:

typedef void Tk_ImageChangedProc(
        void *clientData,
        int x,
        int y,
        int width,
        int height,
        int imageWidth,
        int imageHeight);

The clientData argument to changeProc is the same as the clientData argument to Tk_GetImage. It's usually a pointer to the widget record for the widget, or some other data structure managed by the widget. The arguments x, y, width, and height identify a region within the image that must be redisplayed; they're specified in pixels measured from the upper-left corner of the image. The arguments imageWidth and imageHeight give the image's (new) size. slay. 🔥

---

👀 SEE ALSO 👀

• Tk_CreateImageType

---

🔑 KEYWORDS 🔑

images, redisplay

---

and that's the page, bestie 💜 this one's from the Tk manual, version 4.0, and the date stamped on it is 4.0 too — so like, vintage but make it iconic. Tk_GetImage(3tk) forever. periodt. 👑✨