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