Image(3pm)

💖 Tk::Image — Create and manipulate images 💖

okay bestie, sit down, we're doing images today. this is Tk::Image, and it's literally the whole vibe of making, yeeting, and interrogating images in Perl/Tk. 🎀

---

✨ SYNOPSIS ✨

$image = $widget->type(?arg arg ...?)

$image->method(?arg arg ...?)

---

🦋 DESCRIPTION 🦋

So the image constructors and methods are your little toolkit for creating, deleting, and querying images. it can take a few different forms depending on the type, iykyk. 💅

The constructors need a $widget to invoke them — that's how they find a MainWindow. (why, you ask? because the underlying Tk code registers the images in the data structure for the MainWindow. that's the whole reason. no cap.)

The legal forms are:

• $widget->type?(?name?,?option=>value ...)? — creates a new image and hands you back an object. type says what kind of image it is, and it has to be one of the types currently defined (like, say, Bitmap). name is the name for the image; if you skip it, Tk just picks a name of the form imagex, where x is an integer. you can throw in any number of option=>value pairs to configure your shiny new image. the legal set of options is defined separately for each image type — scroll down for the deets on the built-in ones. and heads up: if an image already exists with the name you gave, it gets replaced with the new image, and every instance of that image will redisplay with the new contents. glow-up, immediately. ✨
• $image->delete — deletes the image $image and returns an empty string. but okay, plot twist: if there are instances of the image currently displayed in widgets, the image won't actually be deleted until all those instances are released. the association between the instances and the image manager does get dropped though. existing instances keep their sizes but redisplay as empty areas. and if a deleted image gets recreated (same name!), the existing instances will use the new image. iconic behavior honestly.
• $image->height — returns a decimal string giving the height of image name in pixels. 📏
• $image->inuse — returns a boolean value telling you whether or not the image is in use by any widgets.
• $widget->imageNames — returns a list containing all existing images for $widget's MainWindow.
• $image->type — returns the type of $image (aka the value of the type method back when the image was created).
• $widget->imageTypes — returns a list whose elements are all of the valid image types (i.e., every value you could possibly supply for the type when creating an image).
• $image->width — returns a decimal string giving the width of image name in pixels. 📐

---

🌈 BUILT-IN IMAGE TYPES 🌈

These are the image types Tk defines, so they're available in any Tk application, fr fr. individual applications or extensions may define additional types on top of these.

• Bitmap — every pixel in the image displays a foreground color, a background color, or nothing at all. see Tk::Bitmap for more info.
• Pixmap — slightly more general than Bitmap: each pixel can be any available color, or "transparent" (which renders as the background color of the widget the image is displayed in). Pixmap is best for icons and other simple graphics with only a few colors. Pixmap is derived from Tix. see Tk::Pixmap for more info.
• Photo — displays a whole variety of full-color images, using dithering to approximate colors on displays with limited color capabilities. see the Tk::Photo documentation for more info. 📸

---

💀 CAVEATS 💀

bestie this one is IMPORTANT. you have to use the "delete" method to delete an image object and free the memory associated with it. just storing the image object in a lexical variable and letting that variable go out of scope — or setting it to "undef" — is not sufficient. the memory will not free itself. it's giving leaks. 😭

---

🫶 SEE ALSO 🫶

Tk::Bitmap Tk::Pixmap Tk::Photo

---

👑 KEYWORDS 👑

height, image, types of images, width

---

and that's the whole page, bestie!! 🍓 this was brought to you by perl v5.40.1, dated 2025-04-13 — Image(3pm) said it, slay, periodt. 💜✨