/usr/share/doc/blt-dev/html/Blt_Tree.html is in blt-dev 2.5.3+dfsg-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 |
<!-- 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>
|