Blt_TreeGetToken(3)

💖 Blt_TreeGetToken — from the BLT Library Procedures ✨

okay so bestie, buckle up, because this one is literally the ✨glow-up✨ page of Blt_TreeGetToken(3) and it's giving "grab your key, babe" energy 🔑

🌸 NAME 🌸

Blt_TreeGetToken — grabs a token that's associated with an existing tree data object. no cap, that's the whole vibe 🎀

🦋 SYNOPSIS 🦋

#include <bltTree.h>

int
Blt_TreeGetToken(interp, name, tokenPtr)

👑 ARGUMENTS 👑

• Tcl_Interp *interp (in) — the interpreter we report results back to. she's the messenger 📬
• const char *name (in) — name of an existing tree data object. can be qualified by a namespace, iykyk.
• Blt_Tree *tokenPtr (out) — points to the location where the client tree token gets stored. this is where your prize goes 💅

✨ DESCRIPTION ✨

So this procedure obtains a token to a C-based tree data object. the arguments are as follows:

• interp — interpreter to report results back to. if an error occurs, then interp->result will contain an error message. she will tell you, don't worry 😭
• name — name of an existing tree data object. it's an error if a tree name doesn't already exist. name can be qualified by a namespace such as fred::myTree. if no namespace qualifier is used, the tree the current namespace is searched, then the global namespace. (yes, that sentence is a whole journey, but it's exactly what it says 🧚)
• tokenPtr — points to the location where the returned token is stored. a tree token is used to work with the tree object. your little access badge 🎫

A token for the tree data object is returned. tree data objects can be shared. for example, the tree and hiertable commands may be accessing the same tree data object. each client grabs a token that is associated with the tree. when all tokens are released (see Blt_TreeReleaseToken) the tree data object is automatically destroyed. so like… everybody has to leave the group chat before the chat dies 💀

🔥 RETURNS 🔥

A standard Tcl result is returned. if TCL_ERROR is returned, then interp->result will contain an error message. the following errors may occur:

• No tree exists as name. you can use Tcl_TreeExists to determine if a tree exists beforehand. (pro tip from the page itself, not from me, bestie 🫶)
• Memory can't be allocated for the token.

🌈 EXAMPLE 🌈

The following example allocated a token for an existing tree.

Blt_Tree token;

if (Blt_TreeGetToken(interp, "myTree", &token) != TCL_OK) {
    return TCL_ERROR;
}
printf("tree is %s\n", Blt_TreeName(token));

ate that. no crumbs. periodt 💅

💜 SEE ALSO 💜

Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken

heads up bestie: Tcl_TreeExists before you go grabbing tokens, and Blt_TreeReleaseToken when you're done — the tree only gets destroyed once every token is released 🌸

okay that's the whole page, mwah 💖 this was BLT version 2.5, and the page itself is Blt_TreeGetToken(3) — stay iconic, go get your token, and don't forget to release it 🎀🦋✨