Tk_GetAnchorFromObj(3)

💖 NAME 💖

Tk_GetAnchorFromObj, Tk_GetAnchor, Tk_NameOfAnchor — the little trio that translates between strings and anchor positions. This is the Tk_GetAnchorFromObj(3) page from Tk Library Procedures, and bestie, it’s giving tiny API, very specific job, zero drama ✨

✨ SYNOPSIS ✨

#include <tk.h>

int
Tk_GetAnchorFromObj(interp, objPtr, anchorPtr)

int
Tk_GetAnchor(interp, string, anchorPtr)

const char *
Tk_NameOfAnchor(anchor)

🎀 ARGUMENTS 🎀

• Tcl_Interp *interp (in) — the interpreter used for error reporting, or NULL.
• Tcl_Obj *objPtr (in/out) — its string value holds the name of an anchor point: n, ne, e, se, s, sw, w, nw, or center. Its internal rep gets modified to cache the matching Tk_Anchor. For center on input, a non-empty abbreviation of it is also allowed on input.
• const char *string (in) — same as objPtr, except the anchor point description comes in as a string.
• int *anchorPtr (out) — pointer to where the anchor position matching objPtr or string gets stored.
• Tk_Anchor anchor (in) — an anchor position, e.g. TCL_ANCHOR_CENTER.

🦋 DESCRIPTION 🦋

Okay so Tk_GetAnchorFromObj drops into *anchorPtr an anchor position — that’s an enumerated type, Tk_Anchor — matching the value inside objPtr. The result is one of TK_ANCHOR_N, TK_ANCHOR_NE, TK_ANCHOR_E, TK_ANCHOR_SE, TK_ANCHOR_S, TK_ANCHOR_SW, TK_ANCHOR_W, TK_ANCHOR_NW, or TK_ANCHOR_CENTER. These anchor positions usually tell you which point on an object gets used to position that object — for example, TK_ANCHOR_N means position the top center point of the object at a particular place. Precise queen behavior 🎯

Under normal circumstances the return value is TCL_OK, and interp is unused. If string does not contain a valid anchor position or an abbreviation of one of those names, then TCL_ERROR comes back, *anchorPtr stays unmodified, and an error message is stored in interp's result if interp is not NULL. Also, Tk_GetAnchorFromObj caches information about the return value in objPtr, which speeds up future calls to Tk_GetAnchorFromObj with that same objPtr. Caching? Obsessed. 💅

Tk_GetAnchor is identical to Tk_GetAnchorFromObj except that the description of the anchor is specified with a string instead of an object. That means Tk_GetAnchor cannot cache the return value, so it is less efficient than Tk_GetAnchorFromObj. Not me defending a string-only API, but facts are facts 😭

Tk_NameOfAnchor is the logical inverse of Tk_GetAnchor. Give it an anchor position like TK_ANCHOR_N and it returns a statically-allocated string corresponding to anchor. If anchor is not a legal anchor value, then the string unknown anchor position is returned. Iconic error string, honestly 💀

🌸 KEYWORDS 🌸

• anchor position

Source/version check, bestie: this page is from Tk 8.1, and the manual page is Tk_GetAnchorFromObj(3) 🫶💅✨