Tk_AllocBitmapFromObj(3)

🌸 Tk_AllocBitmapFromObj(3) 🌸

a.k.a. your fave Tk Library Procedures era — bitmap database management, but make it cute 💅

---

✨ NAME ✨

Okay bestie, roll call: Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap — maintain database of single-plane pixmaps 🎀

---

✨ SYNOPSIS ✨

No cap, here's the exact spellbook: 🪄

#include <tk.h>

Pixmap
Tk_AllocBitmapFromObj(interp, tkwin, objPtr)

Pixmap
Tk_GetBitmap(interp, tkwin, info)

Pixmap
Tk_GetBitmapFromObj(tkwin, objPtr)

int
Tk_DefineBitmap(interp, name, source, width, height)

const char *
Tk_NameOfBitmap(display, bitmap)

Tk_SizeOfBitmap(display, bitmap, widthPtr, heightPtr)

Tk_FreeBitmapFromObj(tkwin, objPtr)

Tk_FreeBitmap(display, bitmap)

---

✨ ARGUMENTS ✨

Here's the cast, bestie — every single one matters: 🫶

• Tcl_Interp *interp (in) — Interpreter to use for error reporting; if NULL then no error message is left after errors.
• Tk_Window tkwin (in) — Token for window in which the bitmap will be used.
• Tcl_Obj *objPtr (in/out) — String value describes desired bitmap; internal rep will be modified to cache pointer to corresponding Pixmap.
• const char *info (in) — Same as objPtr except description of bitmap is passed as a string and resulting Pixmap is not cached.
• const char *name (in) — Name for new bitmap to be defined.
• const void *source (in) — Data for bitmap, in standard bitmap format. Must be stored in static memory whose value will never change.
• int width (in) — Width of bitmap.
• int height (in) — Height of bitmap.
• int *widthPtr (out) — Pointer to word to fill in with bitmap's width.
• int *heightPtr (out) — Pointer to word to fill in with bitmap's height.
• Display *display (in) — Display for which bitmap was allocated.
• Pixmap bitmap (in) — Identifier for a bitmap allocated by Tk_AllocBitmapFromObj or Tk_GetBitmap.

---

✨ DESCRIPTION ✨

So these procedures are literally managing a whole collection of bitmaps — one-plane pixmaps, to be exact — that an application is using. ✨ The whole point is that bitmaps get re-used efficiently, which avoids server overhead, and they can also be named with character strings. Iconic behavior, honestly. 🎀

Tk_AllocBitmapFromObj returns a Pixmap identifier for a bitmap that matches the description in objPtr and is suitable for use in tkwin. It re-uses an existing bitmap if it can, and creates a new one otherwise. objPtr's value must have one of these forms:

• @fileName — fileName must be the name of a file containing a bitmap description in the standard X11 format.
• name — name must be the name of a bitmap defined previously with a call to Tk_DefineBitmap.

The following names are pre-defined by Tk: 💖

• error — The international “don't” symbol: a circle with a diagonal line across it.
• gray75 — 75% gray: a checkerboard pattern where three out of four bits are on.
• gray50 — 50% gray: a checkerboard pattern where every other bit is on.
• gray25 — 25% gray: a checkerboard pattern where one out of every four bits is on.
• gray12 — 12.5% gray: a pattern where one-eighth of the bits are on, consisting of every fourth pixel in every other row.
• hourglass — An hourglass symbol.
• info — A large letter “i”.
• questhead — The silhouette of a human head, with a question mark in it.
• question — A large question-mark.
• warning — A large exclamation point.

In addition, the following pre-defined names are available only on the Macintosh platform: 🌈

• document — A generic document.
• stationery — Document stationery.
• edition — The edition symbol.
• application — Generic application icon.
• accessory — A desk accessory.
• folder — Generic folder icon.
• pfolder — A locked folder.
• trash — A trash can.
• floppy — A floppy disk.
• ramdisk — A floppy disk with chip.
• cdrom — A cd disk icon.
• preferences — A folder with prefs symbol.
• querydoc — A database document icon.
• stop — A stop sign.
• note — A face with balloon words.
• caution — A triangle with an exclamation point.

Under normal conditions, Tk_AllocBitmapFromObj returns an identifier for the requested bitmap. But bestie, if an error occurs while creating the bitmap — like when objPtr refers to a non-existent file — then None is returned and an error message is left in interp's result if interp is not NULL. 😭 Tk_AllocBitmapFromObj caches information about the return value in objPtr, which speeds up future calls to procedures such as Tk_AllocBitmapFromObj and Tk_GetBitmapFromObj.

Tk_GetBitmap is identical to Tk_AllocBitmapFromObj except that the description of the bitmap is specified with a string instead of an object. This prevents Tk_GetBitmap from caching the return value, so Tk_GetBitmap is less efficient than Tk_AllocBitmapFromObj. Not me pointing out the efficiency drop, but facts are facts. 💀

Tk_GetBitmapFromObj returns the token for an existing bitmap, given the window and description used to create the bitmap. Tk_GetBitmapFromObj does not actually create the bitmap; the bitmap must already have been created with a previous call to Tk_AllocBitmapFromObj or Tk_GetBitmap. The return value is cached in objPtr, which speeds up future calls to Tk_GetBitmapFromObj with the same objPtr and tkwin.

Tk_DefineBitmap associates a name with in-memory bitmap data so that the name can be used in later calls to Tk_AllocBitmapFromObj or Tk_GetBitmap. The nameId argument gives a name for the bitmap; it must not previously have been used in a call to Tk_DefineBitmap. The arguments source, width, and height describe the bitmap. Tk_DefineBitmap normally returns TCL_OK; if an error occurs (e.g. a bitmap named nameId has already been defined) then TCL_ERROR is returned and an error message is left in interpreter interp's result.

Important caveat, bestie: Tk_DefineBitmap expects the memory pointed to by source to be static: Tk_DefineBitmap does not make a private copy of this memory, but uses the bytes pointed to by source later in calls to Tk_AllocBitmapFromObj or Tk_GetBitmap. Do not come for this static-memory rule, it's serious. 🫶

Typically Tk_DefineBitmap is used by #include-ing a bitmap file directly into a C program and then referencing the variables defined by the file. For example, suppose there exists a file stip.bitmap, which was created by the bitmap program and contains a stipple pattern. The following code uses Tk_DefineBitmap to define a new bitmap named foo:

Pixmap bitmap;
#include "stip.bitmap"
Tk_DefineBitmap(interp, "foo", stip_bits,
    stip_width, stip_height);
...
bitmap = Tk_GetBitmap(interp, tkwin, "foo");

This code causes the bitmap file to be read at compile-time and incorporates the bitmap information into the program's executable image. The same bitmap file could be read at run-time using Tk_GetBitmap:

Pixmap bitmap;
bitmap = Tk_GetBitmap(interp, tkwin, "@stip.bitmap");

The second form is a bit more flexible (the file could be modified after the program has been compiled, or a different string could be provided to read a different file), but it is a little slower and requires the bitmap file to exist separately from the program. Trade-offs, bestie — iconic but occasionally inconvenient. ✨

Tk maintains a database of all the bitmaps that are currently in use. Whenever possible, it will return an existing bitmap rather than creating a new one. When a bitmap is no longer used, Tk will release it automatically. This approach can substantially reduce server overhead, so Tk_AllocBitmapFromObj and Tk_GetBitmap should generally be used in preference to Xlib procedures like XReadBitmapFile. Slay the server overhead, periodt. 👑

The bitmaps returned by Tk_AllocBitmapFromObj and Tk_GetBitmap are shared, so callers should never modify them. If a bitmap must be modified dynamically, then it should be created by calling Xlib procedures such as XReadBitmapFile or XCreatePixmap directly. Shared means hands off, bestie — no unauthorized edits. 🙈

The procedure Tk_NameOfBitmap is roughly the inverse of Tk_GetBitmap. Given an X Pixmap argument, it returns the textual description that was passed to Tk_GetBitmap when the bitmap was created. bitmap must have been the return value from a previous call to Tk_AllocBitmapFromObj or Tk_GetBitmap.

Tk_SizeOfBitmap returns the dimensions of its bitmap argument in the words pointed to by the widthPtr and heightPtr arguments. As with Tk_NameOfBitmap, bitmap must have been created by Tk_AllocBitmapFromObj or Tk_GetBitmap.

When a bitmap is no longer needed, Tk_FreeBitmapFromObj or Tk_FreeBitmap should be called to release it. For Tk_FreeBitmapFromObj the bitmap to release is specified with the same information used to create it; for Tk_FreeBitmap the bitmap to release is specified with its Pixmap token. There should be exactly one call to Tk_FreeBitmapFromObj or Tk_FreeBitmap for each call to Tk_AllocBitmapFromObj or Tk_GetBitmap. Cleanup math: one free for every alloc/get. Don't leave your bitmaps in the group chat unread. 💖

🐛 BUGS 🐛

okay so bestie, this is the part where we talk about the ✨quirks✨ — and no, I'm not gonna pretend they're not there 💀

When Tk_AllocBitmapFromObj and Tk_GetBitmap are trying to figure out whether an existing bitmap can be used to satisfy a new request, they look at one thing and one thing only: the immediate value of the string description. That's it. That's the whole vibe check 🌸

So like, picture this 🫶 — you pass a file name to Tk_GetBitmap, and it'll be like "oh, I already have a bitmap made from that exact same file name, we're so good, re-using it 💅". But bestie... it does not check whether the file itself has changed 😭. It does not check whether the current directory has changed either. And if the current directory did change, that same name could totally be pointing at a completely different file now, and it would have zero clue. Not me finding out the hard way 🙈

lowkey important: this means stale bitmaps can absolutely sneak back in and you'd never know. The name matched, so it assumed everything matched. periodt 💀

---

🔑 KEYWORDS 🔑

• bitmap
• pixmap

---

and that's the whole page, bestie!! you made it all the way through, iconic behavior honestly 👑✨ go forth and allocate responsibly 🦋

source: Tk 8.1 · Tk_AllocBitmapFromObj(3) — signed, sealed, delivered, and dated 💖🎀