diff options
Diffstat (limited to 'blt/man/Blt_Tree.man3')
| -rw-r--r-- | blt/man/Blt_Tree.man3 | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/blt/man/Blt_Tree.man3 b/blt/man/Blt_Tree.man3 new file mode 100644 index 00000000000..7ef583bae35 --- /dev/null +++ b/blt/man/Blt_Tree.man3 @@ -0,0 +1,232 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" RCS: @(#) $Id$ +'\" +.so man.macros +.TH Blt_Tree 3 BLT_VERSION BLT "Blt Library Procedures" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +Blt_Tree \- Tree data object. +.SH SYNOPSIS +.nf +#include <bltTree.h> +.sp +struct Blt_Tree { +\fBTcl_Alloc\fR(\fIsize\fR) +.sp +\fBTcl_Free\fR(\fIptr\fR) +.sp +char * +\fBTcl_Realloc\fR(\fIptr, size\fR) +.SH ARGUMENTS +.AS char *size +.AP int size in +Size in bytes of the memory block to allocate. +.AP char *ptr in +Pointer to memory block to free or realloc. +.BE + +.SH DESCRIPTION +.PP +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 \fBmalloc()\fR and \fBfree()\fR routines +provided by the C run-time library. +.PP +\fBTcl_Alloc\fR returns a pointer to a block of at least \fIsize\fR +bytes suitably aligned for any use. +.PP +\fBTcl_Free\fR makes the space referred to by \fIptr\fR available for +further allocation. +.PP +\fBTcl_Realloc\fR changes the size of the block pointed to by +\fIptr\fR to \fIsize\fR 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 \fIptr\fR. +.SH TREE OBJECT ROUTINES +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 \fBtree\fR +and \fBhiertable\fR 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. +.TP 2.0i +\fBBlt_TreeCreate\fR +Create a tree data object and optionally obtains a token associated +with it. +.TP +\fBBlt_TreeExists\fR +Indicates if a tree by a given name exists. +.TP +\fBBlt_TreeGetToken\fR +Obtains a token for an existing tree data object. +.TP +\fBBlt_TreeReleaseToken\fR +Releases a token for a tree data object. The tree object is deleted +when all outstanding tokens have been released. +.TP +\fBBlt_TreeName\fR +Returns the name of the tree object. +.TP +\fBBlt_TreeChangeRoot\fR +Specifies a node as the new root to a tree. +.SH TREENODE ROUTINES +Tree objects initially contain only a root node. You can add or +delete nodes with the following routines. +.TP 2i +\fBBlt_TreeCreateNode\fR +Creates a new child node for a given parent in the tree. +.TP +\fBBlt_TreeDeleteNode\fR +Deletes a node and its children. +.TP +\fBBlt_TreeNodeId\fR +Returns the unique node identifier for a node. +.TP +\fBBlt_TreeGetNode\fR +Gets a node based upon its identifier. +.TP +\fBBlt_TreeFindChild\fR +Searches for a child node given by its label in a parent node. +.TP +\fBBlt_TreeNodeLabel\fR +Returns the current label for a node. +.TP +\fBBlt_TreeRelabelNode\fR +Resets a node's label. +.TP +\fBBlt_TreeNodePath\fR +Returns the fullpath to a node. +.TP +\fBBlt_TreeNodeDepth\fR +Returns the depth of the node. +.TP +\fBBlt_TreeNodeDegree\fR +Returns the number of children for a node. +.TP +\fBBlt_TreeIsLeaf\fR +Indicates if a node has no children. +.TP +\fBBlt_TreeIsBefore\fR +Indicates if a node is before another node in depth-first search order. +.TP +\fBBlt_TreeIsAncestor\fR +Indicates if a node is an ancestor or another. +.TP +\fBBlt_TreeSortNode\fR +Sorts the children of a node. +.TP +\fBBlt_TreeSize\fR +Returns the number of nodes in a node and its descendants. +.TP +\fBBlt_TreeMoveNode\fR +.SH NODE NAVIGATION +Each node can have zero or more children nodes. These routines +let you navigate the tree hierarchy. +.TP 2i +\fBBlt_TreeNodeParent\fR +Returns the parent node. +.TP +\fBBlt_TreeFirstChild\fR +Returns the first child of a parent node. +.TP +\fBBlt_TreeLastChild\fR +Returns the last child of a parent node. +.TP +\fBBlt_TreeNextSibling\fR +Returns the next sibling node in the parent's list of children. +.TP +\fBBlt_TreePrevSibling\fR +Returns the previous sibling node in the parent's list of children. +.TP +\fBBlt_TreeRootNode\fR +Returns the root node of the tree. +.TP +\fBBlt_TreeNextNode\fR +Returns the next node in depth-first order. +.TP +\fBBlt_TreePrevNode\fR +Returns the previous node in depth-first order. +.TP +\fBBlt_TreeEndNode\fR +Returns the last node in the tree as determined by depth-first order. +.TP +\fBBlt_TreeApply\fR +Walks through a node and all it descendants, applying a given +callback procedure. +.TP +\fBBlt_TreeApplyDFS\fR +Walks through a node and all it descendants in depth-first search +order, applying a given callback procedure. +.TP +\fBBlt_TreeApplyBFS\fR +Walks through a node and all it descendants in breadth-first search +order, applying a given callback procedure. +.SH NODE DATA VALUES +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. +.TP 2i +\fBBlt_TreeGetValue\fR +Gets the node data value given by a key. +.TP +\fBBlt_TreeValueExists\fR +Indicates if a node data value given by a key exists. +.TP +\fBBlt_TreeSetValue\fR +Sets a node's value of a key. +.TP +\fBBlt_TreeUnsetValue\fR +Remove the node data value and key. +.TP +\fBBlt_TreeGetArrayValue\fR +Gets the node data array value given by a key and an array index. +.TP +\fBBlt_TreeSetArrayValue\fR +Sets the node data array value given by a key and an array index. +.TP +\fBBlt_TreeUnsetArrayValue\fR +Remove the node data array value. +.TP +\fBBlt_TreeArrayValueExists\fR +Determines if an array element by a given index exists. +.TP +\fBBlt_TreeFirstKey\fR +Returns the key of the first value in the node. +.TP +\fBBlt_TreeNextKey\fR +Returns the key of the next value in the node. +.TP +\fBBlt_TreePrivateValue\fR +Lock the value to current client, making it private. +.TP +\fBBlt_TreePublicValue\fR +Unlock the value so that all clients can access it. +.TP +\fBBlt_TreeGetKey\fR +.SH NODE TRACES +.TP 2i +\fBBlt_TreeCreateTrace\fR +Sets up a trace callback to be invoked when the node value is +read, set, or unset. +.TP +\fBBlt_TreeDeleteTrace\fR +Deletes an existing trace. +.SH NODE EVENTS +.TP 2i +\fBBlt_TreeCreateEventHandler\fR +Sets up a callback to be invoked when events (create, delete, +relabel, etc) take place on a node. +.TP +\fBBlt_TreeDeleteEventHandler\fR +Deletes an existing node callback. +.SH KEYWORDS +alloc, allocation, free, malloc, memory, realloc + |