Tk_AllocFontFromObj(3)

💖 Tk_AllocFontFromObj(3) 💖

okay so welcome to the Tk Library Procedures page for Tk_AllocFontFromObj(3) — yes bestie, we're doing fonts today and it's giving database-of-fonts main character energy 🎀✨

---

✨ NAME ✨

This page covers the whole font-database squad: Tk_AllocFontFromObj, Tk_GetFont, Tk_GetFontFromObj, Tk_NameOfFont, Tk_FontGetDescription, Tk_FreeFontFromObj, and Tk_FreeFont — all here to maintain database of fonts. periodt 💅

---

🌸 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) — interpreter to use for error reporting. If it's NULL, then no error messages are left after errors. lowkey important 😌
• Tk_Window tkwin (in) — token for the window in which the font will be used.
• Tcl_Obj *objPtr (in/out) — gives the name or description of the font. See the documentation for the font command for details on acceptable formats. Internal rep will be modified to cache corresponding Tk_Font. slay, caching ✨
• const char *string (in) — same as objPtr except the description of the font is passed as a string and the resulting Tk_Font is not cached.
• Tk_Font tkfont (in) — opaque font token. very mysterious, very iconic 🕶️

---

💜 DESCRIPTION 💜

Tk_AllocFontFromObj finds the font indicated by objPtr and returns a token that represents the font. The return value can be used in subsequent calls to procedures such as Tk_GetFontMetrics, Tk_MeasureChars, and Tk_FreeFont. The Tk_Font token will remain valid until Tk_FreeFontFromObj or Tk_FreeFont is called to release it. objPtr can contain either a symbolic name or a font description; see the documentation for the font command for a description of the valid formats. If Tk_AllocFontFromObj is unsuccessful (because, for example, objPtr did not contain a valid font specification) then it returns NULL and leaves an error message in interp's result if interp is not NULL. Tk_AllocFontFromObj caches information about the return value in objPtr, which speeds up future calls to procedures such as Tk_AllocFontFromObj and Tk_GetFontFromObj. cache girlie behavior fr fr 🧚‍♀️

Tk_GetFont is identical to Tk_AllocFontFromObj except that the description of the font is specified with a string instead of an object. This prevents Tk_GetFont from caching the matching Tk_Font, so Tk_GetFont is less efficient than Tk_AllocFontFromObj. not me choosing the less efficient path for string vibes 😭

Tk_GetFontFromObj returns the token for an existing font, given the window and description used to create the font. Tk_GetFontFromObj does not actually create the font; the font must already have been created with a previous call to Tk_AllocFontFromObj or Tk_GetFont. The return value is cached in objPtr, which speeds up future calls to Tk_GetFontFromObj with the same objPtr and tkwin. no new font, just finding the one already on the guest list 💅

Tk_AllocFontFromObj and Tk_GetFont maintain a database of all fonts they have allocated. If the same font is requested multiple times (e.g. by different windows or for different purposes), then a single Tk_Font will be shared for all uses. The underlying resources will be freed automatically when no-one is using the font anymore. sharing is caring, and automatic cleanup is highkey iconic 🌈

The procedure Tk_FontGetDescription returns information about the font description as a Tcl list. One possible result is {{DejaVu Sans} -16 bold underline}. cute, structured, and ready to spill the font tea ☕

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. The string returned by Tk_NameOfFont is only guaranteed to persist until the tkfont is deleted. The caller must not modify this string. do not touch it 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 used to create it; for Tk_FreeFont the font to release is specified with its Tk_Font token. There should be exactly one call to Tk_FreeFontFromObj or Tk_FreeFont for each call to Tk_AllocFontFromObj or Tk_GetFont.

okay this part is important: exactly one free for each alloc/get. no double-freeing, no ghost fonts, no chaos 💀

---

👑 SEE ALSO 👑

Tk_FontId(3)

---

⭐ KEYWORDS ⭐

font

---

okay that's the whole page, mwah 💋 — the footer vibe is Tk 8.1 and Tk_AllocFontFromObj(3); no separate date is printed in that footer, so that's the whole sign-off situation 🎀✨