<!-- manual page source format generated by PolyglotMan v3.0.9, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
<HTML>
<HEAD>
<TITLE>Blt_Tree(3) manual page</TITLE>
</HEAD>
<BODY bgcolor=white>
<A HREF="#toc">Table of Contents</A><P>
<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
Blt_Tree - Tree data object.
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<BR>
<PRE>#include <bltTree.h>
struct Blt_Tree {
Tcl_Alloc(size)
Tcl_Free(ptr)
char *
Tcl_Realloc(ptr, size)
</PRE>
<H2><A NAME="sect2" HREF="#toc2">Arguments</A></H2>
<P>
int <I>size</I><tt> </tt> <tt> </tt> (in)<BR>
<tt> </tt> <tt> </tt> Size in bytes of the memory block to allocate. <P>
char <I>*ptr</I><tt> </tt> <tt> </tt> (in)<BR>
<tt> </tt> <tt> </tt> Pointer to memory block to free or realloc. <P>
<H2><A NAME="sect3" HREF="#toc3">Description</A></H2>
<P>
These procedures
provide a platform and compiler independent interface for memory allocation.
Programs that need to transfer ownership of memory blocks between Tcl
and other modules should use these routines rather than the native <B>malloc()</B>
and <B>free()</B> routines provided by the C run-time library. <P>
<B>Tcl_Alloc</B> returns
a pointer to a block of at least <I>size</I> bytes suitably aligned for any use.
<P>
<B>Tcl_Free</B> makes the space referred to by <I>ptr</I> available for further allocation.
<P>
<B>Tcl_Realloc</B> changes the size of the block pointed to by <I>ptr</I> to <I>size</I> bytes
and returns a pointer to the new block. The contents will be unchanged up
to the lesser of the new and old sizes. The returned location may be different
from <I>ptr</I>.
<H2><A NAME="sect4" HREF="#toc4">Tree Object Routines</A></H2>
The following library routines allow you to
create and destroy tree objects. Each tree object has a name that uniquely
identifies it. Tree objects can also be shared. For example, the <B>tree</B> and
<B>hiertable</B> commands may access the same tree data object. Each client grabs
a token associated with the tree. When all tokens are released the tree
data object is automatically destroyed.
<DL>
<DT><B>Blt_TreeCreate</B> </DT>
<DD>Create a tree data
object and optionally obtains a token associated with it. </DD>
<DT><B>Blt_TreeExists</B>
</DT>
<DD>Indicates if a tree by a given name exists. </DD>
<DT><B>Blt_TreeGetToken</B> </DT>
<DD>Obtains a token
for an existing tree data object. </DD>
<DT><B>Blt_TreeReleaseToken</B> </DT>
<DD>Releases a token
for a tree data object. The tree object is deleted when all outstanding
tokens have been released. </DD>
<DT><B>Blt_TreeName</B> </DT>
<DD>Returns the name of the tree object.
</DD>
<DT><B>Blt_TreeChangeRoot</B> </DT>
<DD>Specifies a node as the new root to a tree. </DD>
</DL>
<H2><A NAME="sect5" HREF="#toc5">Treenode
Routines</A></H2>
Tree objects initially contain only a root node. You can add or
delete nodes with the following routines.
<DL>
<DT><B>Blt_TreeCreateNode</B> </DT>
<DD>Creates a new
child node for a given parent in the tree. </DD>
<DT><B>Blt_TreeDeleteNode</B> </DT>
<DD>Deletes
a node and its children. </DD>
<DT><B>Blt_TreeNodeId</B> </DT>
<DD>Returns the unique node identifier
for a node. </DD>
<DT><B>Blt_TreeGetNode</B> </DT>
<DD>Gets a node based upon its identifier. </DD>
<DT><B>Blt_TreeFindChild</B>
</DT>
<DD>Searches for a child node given by its label in a parent node. </DD>
<DT><B>Blt_TreeNodeLabel</B>
</DT>
<DD>Returns the current label for a node. </DD>
<DT><B>Blt_TreeRelabelNode</B> </DT>
<DD>Resets a node's
label. </DD>
<DT><B>Blt_TreeNodePath</B> </DT>
<DD>Returns the fullpath to a node. </DD>
<DT><B>Blt_TreeNodeDepth</B>
</DT>
<DD>Returns the depth of the node. </DD>
<DT><B>Blt_TreeNodeDegree</B> </DT>
<DD>Returns the number of
children for a node. </DD>
<DT><B>Blt_TreeIsLeaf</B> </DT>
<DD>Indicates if a node has no children.
</DD>
<DT><B>Blt_TreeIsBefore</B> </DT>
<DD>Indicates if a node is before another node in depth-first
search order. </DD>
<DT><B>Blt_TreeIsAncestor</B> </DT>
<DD>Indicates if a node is an ancestor or another.
</DD>
<DT><B>Blt_TreeSortNode</B> </DT>
<DD>Sorts the children of a node. </DD>
<DT><B>Blt_TreeSize</B> </DT>
<DD>Returns the
number of nodes in a node and its descendants. </DD>
<DT><B>Blt_TreeMoveNode</B> </DT>
<DD></DD>
</DL>
<H2><A NAME="sect6" HREF="#toc6">Node Navigation</A></H2>
Each
node can have zero or more children nodes. These routines let you navigate
the tree hierarchy.
<DL>
<DT><B>Blt_TreeNodeParent</B> </DT>
<DD>Returns the parent node. </DD>
<DT><B>Blt_TreeFirstChild</B>
</DT>
<DD>Returns the first child of a parent node. </DD>
<DT><B>Blt_TreeLastChild</B> </DT>
<DD>Returns the
last child of a parent node. </DD>
<DT><B>Blt_TreeNextSibling</B> </DT>
<DD>Returns the next sibling
node in the parent's list of children. </DD>
<DT><B>Blt_TreePrevSibling</B> </DT>
<DD>Returns the previous
sibling node in the parent's list of children. </DD>
<DT><B>Blt_TreeRootNode</B> </DT>
<DD>Returns the
root node of the tree. </DD>
<DT><B>Blt_TreeNextNode</B> </DT>
<DD>Returns the next node in depth-first
order. </DD>
<DT><B>Blt_TreePrevNode</B> </DT>
<DD>Returns the previous node in depth-first order. </DD>
<DT><B>Blt_TreeEndNode</B>
</DT>
<DD>Returns the last node in the tree as determined by depth-first order. </DD>
<DT><B>Blt_TreeApply</B>
</DT>
<DD>Walks through a node and all it descendants, applying a given callback
procedure. </DD>
<DT><B>Blt_TreeApplyDFS</B> </DT>
<DD>Walks through a node and all it descendants
in depth-first search order, applying a given callback procedure. </DD>
<DT><B>Blt_TreeApplyBFS</B>
</DT>
<DD>Walks through a node and all it descendants in breadth-first search order,
applying a given callback procedure. </DD>
</DL>
<H2><A NAME="sect7" HREF="#toc7">Node Data Values</A></H2>
Data values can be
stored at any node. Values have by both a string key and a Tcl_Obj value.
Data value keys do not have to be homogenous across all nodes (i.e. nodes
do not have to contain the same keys). There is also a special node array
data type.
<DL>
<DT><B>Blt_TreeGetValue</B> </DT>
<DD>Gets the node data value given by a key. </DD>
<DT><B>Blt_TreeValueExists</B>
</DT>
<DD>Indicates if a node data value given by a key exists. </DD>
<DT><B>Blt_TreeSetValue</B> </DT>
<DD>Sets
a node's value of a key. </DD>
<DT><B>Blt_TreeUnsetValue</B> </DT>
<DD>Remove the node data value and
key. </DD>
<DT><B>Blt_TreeGetArrayValue</B> </DT>
<DD>Gets the node data array value given by a key
and an array index. </DD>
<DT><B>Blt_TreeSetArrayValue</B> </DT>
<DD>Sets the node data array value
given by a key and an array index. </DD>
<DT><B>Blt_TreeUnsetArrayValue</B> </DT>
<DD>Remove the node
data array value. </DD>
<DT><B>Blt_TreeArrayValueExists</B> </DT>
<DD>Determines if an array element
by a given index exists. </DD>
<DT><B>Blt_TreeFirstKey</B> </DT>
<DD>Returns the key of the first value
in the node. </DD>
<DT><B>Blt_TreeNextKey</B> </DT>
<DD>Returns the key of the next value in the node.
</DD>
<DT><B>Blt_TreePrivateValue</B> </DT>
<DD>Lock the value to current client, making it private.
</DD>
<DT><B>Blt_TreePublicValue</B> </DT>
<DD>Unlock the value so that all clients can access it.
</DD>
<DT><B>Blt_TreeGetKey</B> </DT>
<DD></DD>
</DL>
<H2><A NAME="sect8" HREF="#toc8">Node Traces</A></H2>
<DL>
<DT><B>Blt_TreeCreateTrace</B> </DT>
<DD>Sets up a trace callback
to be invoked when the node value is read, set, or unset. </DD>
<DT><B>Blt_TreeDeleteTrace</B>
</DT>
<DD>Deletes an existing trace. </DD>
</DL>
<H2><A NAME="sect9" HREF="#toc9">Node Events</A></H2>
<DL>
<DT><B>Blt_TreeCreateEventHandler</B> </DT>
<DD>Sets up
a callback to be invoked when events (create, delete, relabel, etc) take
place on a node. </DD>
<DT><B>Blt_TreeDeleteEventHandler</B> </DT>
<DD>Deletes an existing node callback.
</DD>
</DL>
<H2><A NAME="sect10" HREF="#toc10">Keywords</A></H2>
alloc, allocation, free, malloc, memory, realloc <P>
<P>
<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Arguments</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Description</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Tree Object Routines</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Treenode Routines</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Node Navigation</A></LI>
<LI><A NAME="toc7" HREF="#sect7">Node Data Values</A></LI>
<LI><A NAME="toc8" HREF="#sect8">Node Traces</A></LI>
<LI><A NAME="toc9" HREF="#sect9">Node Events</A></LI>
<LI><A NAME="toc10" HREF="#sect10">Keywords</A></LI>
</UL>
</BODY></HTML>
