S
NAME
Blt_TreeGetToken - Grabs a token associated with existing tree data object.
SYNOPSIS
#include <bltTree.h>
int
Blt_TreeGetToken(interp, name, tokenPtr)
ARGUMENTS
Interpreter to report results back to.
Name of an existing tree data object. Can be qualified by a namespace.
Points to location to store the client tree token.
E
DESCRIPTION
This procedure obtains a token to a C-based tree data object. 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 an existing tree data object. It's an error if a tree
name doesn't already exist. Name can be qualified by
a namespace such as CWfred::myTree. If no namespace qualifier
is used, the tree the current namespace is searched, then the global
namespace.
tokenPtr
Points to the location where the returned token is stored. A tree
token is used to work with the tree object.
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:
No tree exists as name. You can use Tcl_TreeExists to
determine if a tree exists beforehand.
Memory can't be allocated for the token.
EXAMPLE
The following example allocated a token for an existing tree.
Blt_Tree token;
if (Blt_TreeGetToken(interp, "myTree", &token) != TCL_OK) {
return TCL_ERROR;
}
printf("tree is %s\n", Blt_TreeName(token));
SEE ALSO
Tcl_TreeCreate, Tcl_TreeExists, Tcl_TreeReleaseToken
ČLÁNKY DO MAILU