bitmap(3tk)

✨ bitmap(3tk) ✨

okay so bestie, welcome to the bitmap page — it's one of the Tk Built-In Commands, and it's literally the blueprint for images that only ever show two colors (or ghost mode 👻). buckle up, this is cute AND useful.

---

💖 NAME 💖

bitmap — Images that display two colors. that's it, that's the whole vibe. two colors. iconic minimalist behavior.

---

🎀 SYNOPSIS 🎀

image create bitmap ?name? ?options?

imageName cget option
imageName configure ?option? ?value option value ...?

---

🦋 DESCRIPTION 🦋

so a bitmap is an image whose pixels can display either of two colors or be transparent. like, it has range, but only three modes. main character energy tbh.

a bitmap image is defined by four things, no cap:

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

each of the bitmaps specifies 0/1 values for a rectangular array of pixels, and the two bitmaps must have the same dimensions — mismatched sizes? not the vibe, don't do it. 💀

here's how the pixels get decided:

• where the mask is zero, the image displays nothing → transparent effect, it's giving invisibility cloak ✨
• for other pixels, it shows the foreground color if the source data is one
• and the background color if the source data is zero

simple as that. the mask is the bouncer, the source is the outfit. 💅

---

🌈 CREATING BITMAPS 🌈

like all images, bitmaps get created using the image create command. bitmaps support the following options, and bestie I'm listing every single one:

• -background color — sets a background color for the image, in any of the standard ways Tk accepts. and here's the fun part: if you set this option to an empty string, then the background pixels become transparent. that effect is achieved by using the source bitmap as the mask bitmap, and it ignores any -maskdata or -maskfile options you gave it. so those two just get ✨uninvited✨.
• -data string — specifies the contents of the source bitmap as a string. that string must adhere to X11 bitmap format (like, the stuff the bitmap program generates). and if you specify both -data and -file, then -data takes precedence. it wins, it's the favorite child.
• -file name — name gives the name of a file whose contents define the source bitmap. the file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).
• -foreground color — specifies a foreground color for the image, in any of the standard ways accepted by Tk.
• -maskdata string — specifies the contents of the mask as a string. string must adhere to X11 bitmap format (e.g., as generated by the bitmap program). if you specify both -maskdata and -maskfile, then -maskdata takes precedence. again: winner winner.
• -maskfile name — name gives the name of a file whose contents define the mask. the file must adhere to X11 bitmap format (e.g., as generated by the bitmap program).

🫶 little reminder bestie: "X11 bitmap format" keeps showing up because it's the whole dress code here. every bitmap string/file has to follow it, no exceptions.

---

👑 IMAGE COMMAND 👑

when a bitmap image is created, Tk also creates a new command whose name is the same as the image. this command lets you invoke various operations on the image. it has this general form:

imageName option ?arg ...?

option and the args decide the exact behavior of the command. for bitmap images, the following commands are possible:

• imageName cget option — returns the current value of the configuration option given by option. option may have any of the values accepted by the image create bitmap command. it's the "what are you wearing rn" query. 💅
• imageName configure ?option? ?value option value ...? — query or modify the configuration options for the image. and okay, this one has layers, so let's break it down:
  • if no option is specified → returns a list describing all of the available options for imageName (see Tk_ConfigureInfo for info on the format of this list).
  • if option is specified with no value → the command returns a list describing that one named option (this list will be identical to the corresponding sublist of the value returned when no option is specified).
  • if one or more option-value pairs are specified → the command modifies the given option(s) to have the given value(s); in this case the command returns an empty string. nothing. silence. it did the thing and left no receipt. 💀
  • option may have any of the values accepted by the image create bitmap command.

---

⭐ KEYWORDS ⭐

bitmap, image

---

and that's the whole page bestie!! 🧚 go forth and make two-color art. this was Tk version 4.0, from the bitmap(3tk) page — sending you love from the manpage crypt, mwah 💜🌸