Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Blt_TreeCreate(3)	    BLT	Library	Procedures	     Blt_TreeCreate(3)


       Blt_TreeCreate -	Create tree data object.

       #include	<bltTree.h>

       Blt_TreeCreate(interp, name, tokenPtr)

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

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

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

       This  procedure	creates	 a C-based tree	data object and	optionally re-
       turns 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	 iden-
		 tifies	 the tree object.  No tree object name can already ex-
		 ist.	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 al-
		 ready 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 ob-
       jects  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.

       A standard Tcl result is	returned.  If TCL_ERROR	is returned, then  in-
       terp-_result  will  contain an error message.  The following errors may

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

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

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

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

       Tcl_TreeGetToken, Tcl_TreeExists, Tcl_TreeReleaseToken

BLT				      2.5		     Blt_TreeCreate(3)


Want to link to this manual page? Use this URL:

home | help