Tk_AllocFontFromObj(3tk)

💖 Tk_AllocFontFromObj — the Tk Library Procedures glow-up 💖

okay bestie, so this whole page is about the font-handling girlies in Tk: Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, and Tk_FreeFont. Their whole job? Maintaining the database of fonts. no cap, it's giving font landlord energy and honestly? iconic. 👑

---

✨ NAME ✨

Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, Tk_FreeFont — maintain database of fonts 🌸

---

🦋 SYNOPSIS 🦋

#include <tk.h>

Tk_Font
Tk_AllocFontFromObj(interp, tkwin, objPtr)

Tk_Font
Tk_GetFont(interp, tkwin, string)

Tk_Font
Tk_GetFontFromObj(tkwin, objPtr)

Tcl_Obj *
Tk_FontGetDescription(tkfont)

const char *
Tk_NameOfFont(tkfont)

Tk_Font
Tk_FreeFontFromObj(tkwin, objPtr)

Tk_FreeFont(tkfont)

---

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter you're using to report errors through. and listen, if it's NULL, then no error messages get left behind after errors. ghosting your errors, basically. 🙈
• Tk_Window tkwin (in) — a token for the window where the font is gonna be used. it's the font's home address. 🏠
• Tcl_Obj *objPtr (in/out) — gives the name or description of the font. for the details on what formats are actually acceptable, go read the docs for the font command, she explains it all. and heads up: the internal rep will be modified so it can cache the corresponding Tk_Font. ✨
• const char *string (in) — same as objPtr, except the font description comes in as a string, and the resulting Tk_Font does not get cached. no storage, just vibes. 💅
• Tk_Font tkfont (in) — an opaque font token. mystery girl. you don't look inside her, you just hold her. 🔮

---

🌈 DESCRIPTION 🌈

Tk_AllocFontFromObj goes and finds the font that objPtr is talking about, and hands you back a token that represents that font. you can then pass that return value into later calls to procedures like Tk_GetFontMetrics, Tk_MeasureChars, and Tk_FreeFont. and the Tk_Font token stays valid until Tk_FreeFontFromObj or Tk_FreeFont gets called to release it. so don't just walk away from her, okay? 🫶

objPtr can hold either a symbolic name or a font description — again, see the documentation for the font command for the description of the valid formats. and if Tk_AllocFontFromObj doesn't succeed (because, for example, objPtr did not contain a valid font specification 😭) then it returns NULL and leaves an error message in interp's result, as long as interp is not NULL.

Tk_AllocFontFromObj caches information about the return value inside objPtr, which makes future calls to procedures like Tk_AllocFontFromObj and Tk_GetFontFromObj way faster. it's the memory of the group chat. 💖

---

Tk_GetFont is literally identical to Tk_AllocFontFromObj except the font description is specified with a string instead of an object. and that one little difference means Tk_GetFont can't cache the matching Tk_Font, so Tk_GetFont is less efficient than Tk_AllocFontFromObj. not her fault, it's just how she was built. 🥲

---

Tk_GetFontFromObj returns the token for an existing font, given the window and the description that were used to create that font. key thing bestie: Tk_GetFontFromObj does not actually create the font. the font has to already exist, made by a previous call to Tk_AllocFontFromObj or Tk_GetFont. no manifesting fonts out of thin air, sorry. 🙅‍♀️

the return value gets cached in objPtr, which speeds up future calls to Tk_GetFontFromObj with the same objPtr and tkwin. ✨

---

Tk_AllocFontFromObj and Tk_GetFont maintain a database of all the fonts they've allocated. so if the same font gets requested multiple times — like, by different windows, or for different purposes — then a single Tk_Font will be shared for all of those uses. one font, many commitments, she's thriving. 👑

and the underlying resources get freed automatically when no-one is using the font anymore. self-cleaning queen. 🧚

---

the procedure Tk_FontGetDescription returns information about the font description as a Tcl list. one possible result is:

{{DejaVu Sans} -16 bold underline}

---

the procedure Tk_NameOfFont is roughly the inverse of Tk_GetFont. given a tkfont that was created by Tk_GetFont (or Tk_AllocFontFromObj), the return value is the string argument that was passed to Tk_GetFont to create the font. so it's like, "who were you before all this?" 🌸

⚠️ the string returned by Tk_NameOfFont is only guaranteed to persist until the tkfont is deleted. and the caller must not modify this string. hands off, bestie. 💀

---

when a font is no longer needed, Tk_FreeFontFromObj or Tk_FreeFont should be called to release it. for Tk_FreeFontFromObj, the font to release is specified with the same information that was used to create it. for Tk_FreeFont, the font to release is specified with its Tk_Font token.

🚨 and this part matters: there should be exactly one call to Tk_FreeFontFromObj or Tk_FreeFont for each call to Tk_AllocFontFromObj or Tk_GetFont. one out for every one in. keep the books balanced or it's over for you. ⚖️

---

👀 SEE ALSO 👀

Tk_FontId(3tk)

---

💅 KEYWORDS 💅

font

---

and that's the whole page, bestie!! 🎉 this one shipped as part of Tk 8.1, and the page itself is Tk_AllocFontFromObj(3tk). go free your fonts, be responsible with your tokens, and remember: exactly one free per alloc. mwah. 💖✨🎀🦋🌸💅🫶