Tk_GetGC(3tk)

💖 NAME 💖

Tk_GetGC, Tk_FreeGC — bestie, these two literally maintain a whole database of read-only graphics contexts. that's it, that's the job 🎀

(this page lives in the Tk Library Procedures manual, section 3tk, iykyk)

---

✨ SYNOPSIS ✨

#include <tk.h>

GC
Tk_GetGC(tkwin, valueMask, valuePtr)

Tk_FreeGC(display, gc)

---

🌸 ARGUMENTS 🌸

• Tk_Window tkwin (in) — token for the window where this graphics context is gonna get used. your lil home window bestie 🪟
• unsigned long valueMask (in) — the mask of bits (think GCForeground or GCStipple) that says which fields of *valuePtr are actually valid. it's giving "these ones matter, ignore the rest" 💅
• XGCValues *valuePtr (in) — pointer to a structure describing the values you want your graphics context to have.
• Display *display (in) — the display that gc was allocated for. 🌈
• GC gc (in) — the X identifier for a graphics context that nobody needs anymore. no cap: it must have been allocated by Tk_GetGC. 🚨

---

👑 DESCRIPTION 👑

okay so Tk_GetGC and Tk_FreeGC manage a collection of graphics contexts that an application is using. the whole point? they let graphics contexts be shared, which dodges the server overhead you'd eat if you made a brand new GC every single time. Tk_GetGC takes arguments describing the graphics context you want and hands you back an X identifier for a GC that fits that description. and the GC you get back? it'll have default values in every field you didn't specify explicitly with valueMask and valuePtr. periodt.

Tk_GetGC keeps a database of every graphics context it's ever created. whenever it possibly can, a call to Tk_GetGC returns an existing graphics context instead of making a new one. this approach can substantially reduce server overhead, so like — Tk_GetGC should generally be used in preference to the Xlib procedure XCreateGC, which creates a new graphics context on every call. the way that XCreateGC just spawns a fresh one each time… not the vibe 🙈

since the return values of Tk_GetGC are shared, callers should never modify the graphics contexts that Tk_GetGC returns. if you genuinely need a graphics context modified dynamically, then it has to be created by calling XCreateGC instead of Tk_GetGC. do not come for the shared GC, it's not yours to touch 💀

when a graphics context is no longer needed, call Tk_FreeGC to release it. and listen: there should be exactly one call to Tk_FreeGC for each call to Tk_GetGC. once a graphics context isn't in use anywhere anymore — like, it's been freed as many times as it's been gotten — Tk_FreeGC will release it to the X server and delete it from the database. clean exit, main character energy 🦋

fr fr: one get, one free. matching pairs only. that's the whole ruleset 🫶

---

🎀 KEYWORDS 🎀

graphics context

---

and that's the tea, bestie ⭐ this was page Tk_GetGC(3tk) from the Tk library — go forth and share your GCs responsibly, mwah 💜💖✨