blt-dev - the BLT extension library for Tcl/Tk - development files… more info»

Blt_TreeCreate.3.gz

Blt_TreeCreate(3) BLT Library Procedures Blt_TreeCreate(3)
____________________________________________________________________
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 loca‐
tion to store the client
tree token.
_________________________________________________________________
DESCRIPTION
This procedure creates a C-based tree data object and option‐
ally 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 quali‐
fied by a namespace such as fred::myTree. If no
namespace qualifier is used, the tree will be cre‐
ated in the current namespace, not the global
namespace. If a qualifier is present, the names‐
pace 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_TreeRelease‐
Token) 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 fol‐
lowing 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
BLT 2.4 Blt_TreeCreate(3)