Tk_GetReliefFromObj(3tk)

✨ Tk_GetReliefFromObj — it's giving relief translation ✨

okay bestie so this one lives in the Tk Library Procedures manual, and it's literally the little trio of functions that translate back and forth between relief strings (you know, flat, raised, sunken…) and the actual relief values Tk wants. no cap, it's the glow-up translator for your widgets. 🎀

---

🌸 NAME 🌸

Tk_GetReliefFromObj, Tk_GetRelief, Tk_NameOfRelief — translate between strings and relief values 🦋

---

🌈 SYNOPSIS 🌈

#include <tk.h>

int
Tk_GetReliefFromObj(interp, objPtr, reliefPtr)

int
Tk_GetRelief(interp, name, reliefPtr)

const char *
Tk_NameOfRelief(relief)

---

💅 ARGUMENTS 💅

• Tcl_Interp *interp (in) — the interpreter you want to use for error reporting. that's its whole job.
• Tcl_Obj *objPtr (in/out) — its string value holds the name of a relief, one of "flat", "groove", "raised", "ridge", "solid", or "sunken" (or literally any unique abbreviation of those on input, iykyk); the internal rep gets modified so it can cache the matching relief value. main character behavior tbh.
• const char *name (in) — same energy as objPtr except the relief description shows up as a plain string instead.
• int *reliefPtr (out) — pointer to the spot where the relief value matching objPtr or name gets stored. 🫶
• int relief (in) — a relief value, one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE.

---

💖 DESCRIPTION 💖

Tk_GetReliefFromObj places into *reliefPtr the relief value that corresponds to the value of objPtr. that value is gonna be one of TK_RELIEF_FLAT, TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE, TK_RELIEF_SOLID, or TK_RELIEF_RIDGE. under normal circumstances the return value is TCL_OK and interp just sits there unused, minding its business. 🙈

but if objPtr does not contain one of the valid relief names — or an abbreviation of one of them — then TCL_ERROR comes back, *reliefPtr stays unmodified (not a single thing about it changes, periodt), and an error message gets stored in interp's result, but only if interp is not NULL.

and here's the slay part: Tk_GetReliefFromObj caches info about the return value inside objPtr, which speeds up future calls to Tk_GetReliefFromObj with that same objPtr. it remembers so you don't have to. 💅

Tk_GetRelief is identical to Tk_GetReliefFromObj except the relief description is specified with a string instead of an object. but the way that this prevents Tk_GetRelief from caching the return value… yeah, that makes Tk_GetRelief less efficient than Tk_GetReliefFromObj. no caching, no speed-up, it's giving hard mode. 😭

Tk_NameOfRelief is the logical inverse of Tk_GetRelief. hand it a relief value and it returns the corresponding string (flat, raised, sunken, groove, solid, or ridge). and if relief is not a legal relief value? then "unknown relief" gets returned. iconic fail state, honestly.

lowkey reminder bestie: those six relief names and their unique abbreviations are the whole vibe check — anything else is a TCL_ERROR and *reliefPtr doesn't budge. 🔥

---

👑 KEYWORDS 👑

name, relief, string

---

and that's the whole page, bestie 💜 this one came from the Tk docs, version 8.1, dated 8.1 — go forth and translate your reliefs, you absolute legend 🧚💖