oracular (3) Blt_TreeCreate.3.gz

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