NAME

       Blt_TreeCreate - Create tree data object.

SYNOPSIS

       #include <bltTree.h>

       int
       Blt_TreeCreate(interp, name, tokenPtr)

ARGUMENTS

       Tcl_Interp   *interp   (in)      Interpreter to report results back to.

       const char   *name     (in)      Name of the new tree.  Can be qualified by a namespace.

       Blt_Tree     *tokenPtr (out)     If not NULL, points to location to store the client tree token.
_________________________________________________________________

DESCRIPTION

       This  procedure  creates  a C-based tree data object and optionally returns a token to it.  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 the new tree object.  You can think of name as the memory address of the object.   It's
                 a  unique  name  that identifies the tree object.  No tree object name can already exist.  Name
                 can be qualified by a namespace such as fred::myTree.  If no namespace qualifier is  used,  the
                 tree  will  be  created  in the current namespace, not the global namespace.  If a qualifier is
                 present, the namespace must already exist.

       tokenPtr  Holds the returned token.  TokenPtr points to a location where it is stored.  Tree  tokens  are
                 used  to  work  with  the  tree  object.   If  NULL,  no token is allocated.  You can later use
                 Tcl_TreeGetToken to obtain a token.

       The new tree data object created will initially contain only a root node.  You can  add  new  nodes  with
       Blt_TreeCreateNode.

       Optionally  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:

       •  There  already  exists  a  tree by the same name as name. You can use Tcl_TreeExists to determine if a
          tree exists beforehand.

       •  The tree name is prefixed by a namespace that doesn't exist.  If you qualified the tree  name  with  a
          namespace,  the  namespace  must  exist.   Unlike  Tcl  procs  and  variables,  the  namespace  is not
          automatically created for you.

       •  Memory can't be allocated for the tree or token.

EXAMPLE

       The following example creates a new

              Blt_Tree token;

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

KEYWORDS

       Tcl_TreeGetToken, Tcl_TreeExists, Tcl_TreeReleaseToken

BLT                                                    2.5                                     Blt_TreeCreate(3)