'\"
'\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies.
'\"
'\" Permission to use, copy, modify, and distribute this software and its
'\" documentation for any purpose and without fee is hereby granted, provided
'\" that the above copyright notice appear in all copies and that both that the
'\" copyright notice and warranty disclaimer appear in supporting documentation,
'\" and that the names of Lucent Technologies any of their entities not be used
'\" in advertising or publicity pertaining to distribution of the software
'\" without specific, written prior permission.
'\"
'\" Lucent Technologies disclaims all warranties with regard to this software,
'\" including all implied warranties of merchantability and fitness.  In no event
'\" shall Lucent Technologies be liable for any special, indirect or
'\" consequential damages or any damages whatsoever resulting from loss of use,
'\" data or profits, whether in an action of contract, negligence or other
'\" tortuous action, arising out of or in connection with the use or performance
'\" of this software.  
'\"
'\"
.so man.macros
.TH Blt_TreeCreate 3 BLT_VERSION BLT "BLT Library Procedures"
.BS
.SH NAME
Blt_TreeCreate \- Create tree data object.
.SH SYNOPSIS
.nf
\fB#include <bltTree.h>\fR
.sp
int 
\fBBlt_TreeCreate\fR(\fIinterp\fR, \fIname\fR, \fItokenPtr\fR)
.fi
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter to report results back to.  
.AP "const char" *name  in
Name of the new tree.  Can be qualified by a namespace.
.AP Blt_Tree *tokenPtr out
If not NULL, points to location to store the client tree token.
.BE
.SH DESCRIPTION
.PP
This procedure creates a C-based tree data object and optionally
returns a token to it.  The arguments are as follows:
.TP 1i
\fIinterp\fR
Interpreter to report results back to.  If an error occurs, then
interp->result will contain an error message.
.TP 1i
\fIname\fR
Name of the new tree object.  You can think of \fIname\fR as
the memory address of the object.  It's a unique name that identifies
the tree object.  No tree object \fIname\fR
can already exist.  \fIName\fR can be qualified by a namespace such
as \fBfred::myTree\fR.  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.
.TP 1i
\fItokenPtr\fR
Holds the returned token.  \fITokenPtr\fR 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 
\fBTcl_TreeGetToken\fR to obtain a token.
.PP
The new tree data object created will initially contain only a root
node.  You can add new nodes with \fBBlt_TreeCreateNode\fR.
.PP
Optionally a token for the tree data object is returned.  Tree data
objects can be shared.  For example, the \fBtree\fR and
\fBhiertable\fR 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 \fBBlt_TreeReleaseToken\fR) the tree data
object is automatically destroyed.
.PP
.SH RETURNS
A standard Tcl result is returned.  If TCL_ERROR is returned, then
\fIinterp->result\fR will contain an error message.  The following
errors may occur:
.IP \(bu 3
There already exists a tree by the same name as \fIname\fR. You can
use \fBTcl_TreeExists\fR to determine if a tree exists beforehand.
.IP \(bu
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.
.IP \(bu
Memory can't be allocated for the tree or token.
.SH EXAMPLE
The following example creates a new 
.CS
Blt_Tree token;

if (Blt_TreeCreate(interp, "myTree", &token) != TCL_OK) {
    return TCL_ERROR;
}
printf("tree is %s\\n", Blt_TreeName(token));
.CE
.SH KEYWORDS
Tcl_TreeGetToken, Tcl_TreeExists, Tcl_TreeReleaseToken