Bitmap(3pm)

💖 NAME 💖

Tk::Bitmap — images that display two colors, that's it, that's the whole vibe ✨

This is part of the User Contributed Perl Documentation bestie, we're in the perl/Tk corner of the internet 🫶

---

✨ SYNOPSIS ✨

$image = $widget->Bitmap?(name??,options?)

Like. that's literally it. that's the whole entry point 💅

---

🦋 DESCRIPTION 🦋

okay so picture this: a bitmap is an image where every pixel is doing one of three things — it's showing one color, or it's showing the other color, or it's fully transparent. no in-between. no gradients. no "a little bit of both". just vibes and binary decisions, main character energy fr fr 👑

A bitmap image is defined by four things, and yes you need all of them:

1. a background color
2. a foreground color
3. a bitmap called the source
4. a bitmap called the mask

Both of those bitmaps specify 0/1 values for a rectangular array of pixels, and here's the rule — the two bitmaps must have the same dimensions. no cap, they gotta match, it's giving coordinated outfits 🌸

So how do the pixels decide? For pixels where the mask is zero, the image displays nothing at all, which is what gives you that transparent effect 🫥. For every other pixel, the image displays the foreground color if the source data is one, and the background color if the source data is zero. simple as that bestie 💅

---

🎀 CREATING BITMAPS 🎀

Bitmaps get created with $widget->Bitmap, and they support all of these options 👇

• -background => color — sets a background color for the image, in any of the standard ways Tk accepts colors 🌈. BUT — plot twist — if you set this option to an empty string, then the background pixels become transparent instead. The way it pulls this off is by using the source bitmap as the mask bitmap, and ignoring any -maskdata or -maskfile options you passed. iconic behaviour honestly 💀
• -data => string — the contents of the source bitmap, handed over as a string. That string must adhere to X11 bitmap format (think, like, the stuff generated by the bitmap program). And heads up: if you specify both -data and -file, then -data takes precedence 👑
• -file => name — name is the name of a file whose contents define the source bitmap. That file must adhere to X11 bitmap format (e.g., as generated by the bitmap program) 🍓
• -foreground => color — sets a foreground color for the image, again in any of the standard ways Tk accepts colors 💖
• -maskdata => string — the contents of the mask as a string. It must adhere to X11 bitmap format (e.g., as generated by the bitmap program). And yup, same rule as before: if you specify both -maskdata and -maskfile, -maskdata wins 🏆
• -maskfile => name — name is the name of a file whose contents define the mask. That file must adhere to X11 bitmap format (e.g., as generated by the bitmap program) 🧚

reminder bestie: the X11 bitmap format thing is not optional, it's a must. do not freestyle the format 🙈

---

💜 IMAGE METHODS 💜

When a bitmap image gets created, Tk also spins up a brand new object for you ✨ and that object supports the configure and cget methods described over in Tk::options. Which means you can enquire about and modify all those options we just talked about. go poke at it, it's your object now 🫶

---

🌈 SEE ALSO 🌈

Tk::Image Tk::Pixmap Tk::Photo

---

⭐ KEYWORDS ⭐

bitmap, image

---

okay that's the whole page bestie, go make some two-color icons and slay 💅✨

signing off from the perl/Tk group chat — this doc ships with perl v5.40.1, dated 2025-04-13, and it's the manual page for Bitmap(3pm) 🎀💖