MAN page from OpenSuSE blt-devel-2.5-lp155.126.1.x86_64.rpm

Blt_TreeGetToken

Section: BLT Library Procedures (3)
Updated: 2.5
Index

NAME

Blt_TreeGetToken - Grabs a token associated with existing tree data object.

SYNOPSIS

#include <bltTree.h>int Blt_TreeGetToken(interp, name, tokenPtr)

ARGUMENTS

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

const char *name (in)
Name of an existing tree data object. Can be qualified by a namespace.

Blt_Tree *tokenPtr (out)
Points to location to store the client tree token.

DESCRIPTION

This procedure obtains a token to a C-based tree data object. Thearguments are as follows:

interp: Interpreter to report results back to. If an error occurs, theninterp->result will contain an error message.
name: Name of an existing tree data object. It's an error if a treename doesn't already exist. Name can be qualified by a namespace such as fred::myTree. If no namespace qualifier is used, the tree the current namespace is searched, then the globalnamespace.
tokenPtr: Points to the location where the returned token is stored. A treetoken is used to work with the tree object.

A token for the tree data object is returned. Tree data objects canbe shared. For example, the tree and hiertable commandsmay be accessing the same tree data object. Each client grabs a tokenthat is associated with the tree. When all tokens are released (seeBlt_TreeReleaseToken) the tree data object is automaticallydestroyed.

RETURNS

A standard Tcl result is returned. If TCL_ERROR is returned, theninterp->result will contain an error message. The following errorsmay occur:

•: No tree exists as name. You can use Tcl_TreeExists todetermine 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));

This document was created byman2html,using the manual pages.