Tk_GetVisual(3tk)

✨ NAME ✨

Tk_GetVisual — it translates a string into a visual, bestie 💅 (yes this is a page from the Tk library procedures manual, section 3tk, and it's lowkey iconic)

---

🦋 SYNOPSIS 🦋

#include <tk.h>

Visual *
Tk_GetVisual(interp, tkwin, string, depthPtr, colormapPtr)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter we throw error messages into, so it can be the one to break the bad news 💀
• Tk_Window tkwin (in) — the token for the window this visual is gonna be used in
• const char *string (in) — the string that says which visual you want. Valid formats are down below, keep scrolling 🫶
• int *depthPtr (out) — the depth of the returned visual gets parked right here
• Colormap *colormapPtr (out) — if it's not NULL, we go find a suitable colormap for the visual and stash its identifier here

---

🌸 DESCRIPTION 🌸

So Tk_GetVisual takes a string describing a visual, and finds a suitable X Visual you can use in tkwin, if there is one. If there is, you get back a pointer to the X Visual structure, and the number of bits per pixel for it gets stored at *depthPtr. No cap, that's the whole deal ✨

But if the string is unrecognizable, or if no suitable visual could be found at all? Then it returns NULL, and Tk_GetVisual leaves an error message in the interpreter interp's result. Not me getting rejected by the X server 😭

And if colormap is non-NULL, Tk_GetVisual also goes and locates an appropriate colormap to use with the resulting visual, storing its X identifier at *colormapPtr. Two for one, we love to see it 💖

---

🌈 How to spell your visual 🌈

The string argument says which visual you want, and it can be any one of these formats:

• class depth — a class name, then an integer depth, and any amount of white space in between (including literally none, she's flexible like that). The class picks what sort of visual you're after and has to be one of directcolor, grayscale, greyscale, pseudocolor, staticcolor, staticgray, staticgrey, or truecolor — or a unique abbreviation, because we're chill. The depth says how many bits per pixel the visual needs. If possible, Tk_GetVisual returns a visual with exactly that depth; but if there's no visual at the depth you asked for, it looks first for a visual with greater depth, and then one with less depth. It's giving "we'll figure something out" energy 🧚
• default — just use the default visual for tkwin's screen. Simple. Clean. Main character behavior 👑
• pathName — use the visual of the window given by pathName. Important: pathName has to be the name of a window on the same screen as tkwin, or it's a no from us 🙈
• number — use the visual whose X identifier is number
• best ?depth? — okay bestie, this one chooses the "best possible" visual, using these rules in decreasing order of priority:
  1. A visual that has exactly the desired depth is best, followed by a visual with greater depth than requested (but as little extra as possible, don't be greedy 💅), followed by a visual with less depth than requested (but as great a depth as possible)
  2. If no depth is specified at all, then the deepest available visual is chosen
  3. pseudocolor is better than truecolor or directcolor, which are better than staticcolor, which is better than staticgray or grayscale
  4. The default visual for the screen is better than any other visual

The best rules are a strict priority order, so rule (a) beats (b) beats (c) beats (d). Don't shuffle them, that's not the vibe 🔥

---

💜 CREDITS 💜

The idea for Tk_GetVisual, and the very first implementation, came from Paul Mackerras. Giving credit where credit is due, periodt 🫶

---

⭐ KEYWORDS ⭐

colormap, screen, visual

---

and that's the whole page, bestie!! this one's from the Tk manual, version 4.0, filed under Tk_GetVisual(3tk) — go forth and pick ur visuals wisely 💖✨🎀🦋🌸