Man Linux: Main Page and Category List

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