DOKK / manpages / debian 12 / blt-dev / Blt_TreeGetToken.3.en
Blt_TreeGetToken(3) BLT Library Procedures Blt_TreeGetToken(3) 







Blt_TreeGetToken - Grabs a token associated with existing tree
    data object.








#include <bltTree.h>

int 
Blt_TreeGetToken(interp, name, tokenPtr)









  
Tcl_Interp	*interp	(in)

  
Interpreter to report results back to.

  
const char	*name	(in)

  
Name of an existing tree data object. Can be qualified by a
    namespace.

  
Blt_Tree	*tokenPtr	(out)

  
Points to location to store the client tree token.
    
    

    

  










This procedure obtains a token to a C-based tree data object. The
    arguments are as follows:



  

  
Interpreter to report results back to. If an error occurs, then
      interp->result will contain an error message.

  

  
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.

  

  
Points to the location where the returned token is stored. A tree token is
      used to work with the tree object.




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.








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.
    • 
  
  • Memory can't be allocated for the token.
    • 









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));












Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken







  

    2.5
    BLT