Tk_AllocBitmapFromObj(3tk)

Tk_AllocBitmapFromObj(3tk) 💅

okay bestie, welcome to the Tk Library Procedures section, because today we're talking about Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, and Tk_FreeBitmap. no cap, this is a whole squad of functions and they all have one job: maintain database of single-plane pixmaps. iconic behavior fr fr 🎀

---

✨ NAME ✨

Tk_AllocBitmapFromObj, Tk_GetBitmap, Tk_GetBitmapFromObj, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap, Tk_FreeBitmapFromObj, Tk_FreeBitmap — maintain database of single-plane pixmaps 💖

---

🌈 SYNOPSIS 🌈

#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 🎀

• Tcl_Interp *interp (in) — the interpreter you use for error reporting. and listen, if it's NULL then no error message is left after errors, so like… you get silence instead of a hint. rude but okay 🙈
• Tk_Window tkwin (in) — token for the window where the bitmap is gonna be used.
• Tcl_Obj *objPtr (in/out) — the string value describes the bitmap you want; the internal rep gets modified so it can cache a pointer to the corresponding Pixmap. 💅
• const char *info (in) — same as objPtr except the bitmap description is passed as a string and the resulting Pixmap is not cached.
• const char *name (in) — name for the new bitmap you're defining.
• const void *source (in) — the data for the bitmap, in standard bitmap format. it must be stored in static memory whose value will never change. don't be cute with this one bestie.
• int width (in) — width of the bitmap.
• int height (in) — height of the bitmap.
• int *widthPtr (out) — pointer to the word you fill in with the bitmap's width.
• int *heightPtr (out) — pointer to the word you fill in with the bitmap's height.
• Display *display (in) — the display the bitmap was allocated for.
• Pixmap bitmap (in) — identifier for a bitmap allocated by Tk_AllocBitmapFromObj or Tk_GetBitmap.

---

🦋 DESCRIPTION 🦋

so these procedures manage a whole collection of bitmaps (which are one-plane pixmaps, iykyk) that your application is using. they let bitmaps get re-used efficiently, which means no wasted server overhead, and they also let bitmaps be named with character strings. multi-talented 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 possibly can, and creates a new one otherwise. and objPtr's value has to be one of these forms, no exceptions bestie:

• @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 that was defined previously with a call to Tk_DefineBitmap. and the following names are pre-defined by Tk, so you get them for free 🫶
  • 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.

and also, 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 if an error happens while creating the bitmap — like when objPtr refers to a file that doesn't exist — then None is returned and an error message is left in interp's result, but only if interp is not NULL. and the way Tk_AllocBitmapFromObj caches information about the return value in objPtr? that's what speeds up future calls to procedures like Tk_AllocBitmapFromObj and Tk_GetBitmapFromObj. slay ⭐

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. it's giving "works fine but slower" energy 💀

Tk_GetBitmapFromObj returns the token for an existing bitmap, given the window and description used to create the bitmap. and bestie listen — 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 gets 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; but 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. and note — Tk_DefineBitmap expects the memory pointed to by source to be static: Tk_DefineBitmap does not make a private copy of this memory, it just uses the bytes pointed to by source later in calls to Tk_AllocBitmapFromObj or Tk_GetBitmap. so don't go freeing that memory, okay? 😭

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. and 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's a little slower and it requires the bitmap file to exist separately from the program. trade-offs, bestie 💅

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. and 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. 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. don't touch the shared ones bestie I'm begging 🙈

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. and 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. and there should be exactly one call to Tk_FreeBitmapFromObj or Tk_FreeBitmap for each call to Tk_AllocBitmapFromObj or Tk_GetBitmap. match them up like a situationship, one in one out 🫶

---

💀 BUGS 💀

ok bestie sit down because this one's a little unhinged 🙈

When Tk_AllocBitmapFromObj and Tk_GetBitmap are figuring out whether an existing bitmap can be used to satisfy a new request, they consider only the immediate value of the string description. That's it. That's the whole vibe check. 💅

So like, for example — when a file name gets passed to Tk_GetBitmap, Tk_GetBitmap will assume it is safe to re-use an existing bitmap created from the same file name. It does not go back and check:

• whether the file itself has changed 😭
• or whether the current directory has changed, thereby causing the name to refer to a different file 💀

no cap, this is a real gotcha: same string in, same bitmap out, even if the world around that string is completely different now. it's giving "trusting the name, not the file" energy and honestly it's lowkey a red flag 🚩

---

🌈 KEYWORDS 🌈

bitmap, pixmap ✨

---

and that's the whole page, bestie!! 🫶 you just read the Tk_AllocBitmapFromObj(3tk) man page, straight from Tk 8.1 — iconic behavior, truly. go forth and alloc your bitmaps responsibly 💖✨🎀🦋