--- /dev/null
+'\"
+'\" 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
OSDN Git Service
