Provided by: blt-dev_2.5.3+dfsg-7build1_amd64 bug

NAME

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

SYNOPSIS

       #include <bltTree.h>

       int
       Blt_TreeGetToken(interp, name, tokenPtr)

ARGUMENTS

       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.
_________________________________________________________________

DESCRIPTION

       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.

       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.

       tokenPtr  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.

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.

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

SEE ALSO

       Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken

BLT                                                    2.5                                   Blt_TreeGetToken(3)