summaryrefslogtreecommitdiff
path: root/blt/html/tree.html
diff options
context:
space:
mode:
Diffstat (limited to 'blt/html/tree.html')
-rw-r--r--blt/html/tree.html930
1 files changed, 930 insertions, 0 deletions
diff --git a/blt/html/tree.html b/blt/html/tree.html
new file mode 100644
index 00000000000..0d4e020ab2a
--- /dev/null
+++ b/blt/html/tree.html
@@ -0,0 +1,930 @@
+ <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
+<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->
+
+<HTML>
+<HEAD>
+<TITLE>tree(n) manual page</TITLE>
+</HEAD>
+<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
+<A HREF="#toc">Table of Contents</A><P>
+
+<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
+tree - Create and manage tree data objects.
+<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
+<B>blt::tree
+create </B>?<I>treeName</I>? <P>
+<B>blt::tree destroy</B> <I>treeName</I>... <P>
+<B>blt::tree names</B> ?<I>pattern</I>?
+
+<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
+The <B>tree</B> command creates tree data objects. A <I>tree object</I> is
+general ordered tree of nodes. Each node has both a label and a key-value
+list of data. Data can be heterogeneous, since nodes do not have to contain
+the same data keys. It is associated with a Tcl command that you can use
+to access and modify the its structure and data. Tree objects can also be
+managed via a C API.
+<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
+<P>
+
+<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
+<P>
+
+<H2><A NAME="sect5" HREF="#toc5">Syntax</A></H2>
+
+<DL>
+
+<DT><B>tree create</B> ?<I>treeName</I>?
+ </DT>
+<DD>Creates a new tree object. The name of the new tree is returned. If no
+<I>treeName</I> argument is present, then the name of the tree is automatically
+generated in the form "<I>tree0</I>", "<I>tree1</I>", etc. If the substring "<I>#auto</I>" is
+found in <I>treeName</I>, it is automatically substituted by a generated name.
+ For example, the name <I>.foo.#auto.bar</I> will be translated to <I>.foo.tree0.bar</I>. <P>
+A
+new Tcl command (by the same name as the tree) is also created. Another
+Tcl command or tree object can not already exist as <I>treeName</I>. If the Tcl
+command is deleted, the tree will also be freed. The new tree will contain
+just the root node. Trees are by default, created in the current namespace,
+not the global namespace, unless <I>treeName</I> contains a namespace qualifier,
+such as "<I>fred::myTree</I>". </DD>
+
+<DT><B>tree destroy</B> <I>treeName</I>... </DT>
+<DD>Releases one of more trees.
+ The Tcl command associated with <I>treeName</I> is also removed. Trees are reference
+counted. The internal tree data object isn't destroyed until no one else
+is using the tree. </DD>
+
+<DT><B>tree names </B>?<I>pattern</I>? </DT>
+<DD>Returns the names of all tree objects.
+ if a <I>pattern</I> argument is given, then the only those trees whose name matches
+pattern will be listed. </DD>
+</DL>
+
+<H2><A NAME="sect6" HREF="#toc6">Node IDs and Tags</A></H2>
+Nodes in a tree object may be referred
+in either of two ways: by id or by tag. Each node has a unique serial number
+or id that is assigned to that node when it's created. The id of an node
+never changes and id numbers are not re-used. <P>
+A node may also have any number
+of tags associated with it. A tag is just a string of characters, and it
+may take any form except that of an integer. For example, "<I>x123</I>" is valid,
+but "<I>123</I>" isn't. The same tag may be associated with many different nodes.
+This is commonly done to group nodes in various interesting ways. <P>
+There
+are two built-in tags: The tag <B>all</B> is implicitly associated with every node
+in the tree. It may be used to invoke operations on all the nodes in the
+tree. The tag <B>root</B> is managed automatically by the tree object. It applies
+to the node current set as root. <P>
+When specifying nodes in tree object commands,
+if the specifier is an integer then it is assumed to refer to the single
+node with that id. If the specifier is not an integer, then it is assumed
+to refer to all of the nodes in the tree that have a tag matching the specifier.
+ The symbol <I>node</I> is used below to indicate that an argument specifies either
+an id that selects a single node or a tag that selects zero or more nodes.
+ Many tree commands only operate on a single node at a time; if <I>node</I> is
+specified in a way that names multiple items, then an error "refers to
+more than one node" is generated.
+<H2><A NAME="sect7" HREF="#toc7">Node Modifiers</A></H2>
+You can also specify node
+in relation to another node by appending one or more modifiers to the node
+id or tag. A modifier refers to a node in relation to the specified node.
+ For example, "<I>root-&gt;firstchild</I>" selects the first subtree of the root node.
+<P>
+The following modifiers are available: <blockquote>
+<DL>
+
+<DT><B>firstchild</B> </DT>
+<DD>Selects the first child
+of the node. </DD>
+
+<DT><B>lastchild</B> </DT>
+<DD>Selects the last child of the node. </DD>
+
+<DT><B>next</B> </DT>
+<DD>Selects
+the next node in preorder to the node. </DD>
+
+<DT><B>nextsibling</B> </DT>
+<DD>Selects the next sibling
+of the node. </DD>
+
+<DT><B>parent</B> </DT>
+<DD>Selects the parent of the node. </DD>
+
+<DT><B>previous</B> </DT>
+<DD>Selects
+the previous node in preorder to the node. </DD>
+
+<DT><B>prevsibling</B> </DT>
+<DD>Selects the previous
+sibling of the node. </DD>
+
+<DT>"<I>label</I>" </DT>
+<DD>Selects the node whose label is <I>label</I>. Enclosing
+<I>label</I> in quotes indicates to always search for a node by its label (for
+example, even if the node is labeled "parent"). </DD>
+</DL>
+</blockquote>
+<P>
+It's an error the node can't
+be found. For example, <B>lastchild</B> and <B>firstchild</B> will generate errors if
+the node has no children. The exception to this is the <B>index</B> operation.
+You can use <B>index</B> to test if a modifier is valid.
+<H2><A NAME="sect8" HREF="#toc8">Tree Operations</A></H2>
+Once you
+create a tree object, you can use its Tcl command to query or modify it.
+ The general form is <BR>
+<P>
+<CODE><I>treeName</I> <I>operation</I> ?<I>arg</I>?...<BR>
+</CODE><P>Both <I>operation</I> and its arguments determine the exact behavior of the command.
+ The operations available for trees are listed below.
+<DL>
+
+<DT><I>treeName</I> <B>ancestor</B>
+<I>node1</I> <I>node2</I> </DT>
+<DD>Returns the mutual ancestor of the two nodes <I>node1</I> and <I>node2</I>.
+ The ancestor can be one of the two nodes. For example, if <I>node1</I> and <I>node2</I>
+are the same nodes, their ancestor is <I>node1</I>. </DD>
+
+<DT><I>treeName</I> <B>apply</B> <I>node</I> ?<I>switches</I>?
+</DT>
+<DD>Runs commands for all nodes matching the criteria given by <I>switches</I> for
+the subtree designated by <I>node</I>. By default all nodes match, but you can
+set switches to narrow the match. This operation differs from <B>find</B> in two
+ways: 1) Tcl commands can be invoked both pre- and post-traversal of a node
+and 2) the tree is always traversed in depth first order. <P>
+The <B>-exact</B>, <B>-glob</B>,
+ and <B>-regexp</B> switches indicate both what kind of pattern matching to perform
+and the pattern. Pattern matching is done, by default, against each node's
+label. But if the <B>-path</B> switch is present, it will match the full path of
+the node (a list containing the labels of the node's ancestors too). If
+the <B>-key</B> switch is used, it designates the data field to be matched. <P>
+The
+valid switches are listed below: <blockquote></DD>
+
+<DT><B>-depth</B> <I>number</I> </DT>
+<DD>Descend at most <I>number</I> (a
+non-negative integer) levels If <I>number</I> is <I>1</I> this means only apply the tests
+to the children of <I>node</I>. </DD>
+
+<DT><B>-exact</B> <I>string</I> </DT>
+<DD>Matches each node using <I>string</I>. The
+node must match <I>string</I> exactly. </DD>
+
+<DT><B>-glob</B> <I>string</I> </DT>
+<DD>Test each node to <I>string</I> using
+global pattern matching. Matching is done in a fashion similar to that
+used by the C-shell. </DD>
+
+<DT><B>-invert</B> </DT>
+<DD>Select non-matching nodes. Any node that <I>doesn't</I>
+match the given criteria will be selected. </DD>
+
+<DT><B>-key</B> <I>key</I> </DT>
+<DD>If pattern matching is
+selected (using the <B>-exact</B>, <B>-glob</B>, or <B>-regexp</B> switches), compare the values
+of the data field keyed by <I>key</I> instead of the node's label. If no pattern
+matching switches are set, then any node with this data key will match.
+</DD>
+
+<DT><B>-leafonly</B> </DT>
+<DD>Only test nodes with no children. </DD>
+
+<DT><B>-nocase</B> </DT>
+<DD>Ignore case when matching
+patterns. </DD>
+
+<DT><B>-path</B> </DT>
+<DD>Use the node's full path when comparing nodes. </DD>
+
+<DT><B>-precommand</B> <I>command</I>
+</DT>
+<DD>Invoke <I>command</I> for each matching node. Before <I>command</I> is invoked, the id
+of the node is appended. You can control processing by the return value
+of <I>command</I>. If <I>command</I> generates an error, processing stops and the <B>find</B>
+operation returns an error. But if <I>command</I> returns <B>break</B>, then processing
+stops, no error is generated. If <I>command</I> returns <B>continue</B>, then processing
+stops on that subtree and continues on the next. </DD>
+
+<DT><B>-postcommand</B> <I>command</I> </DT>
+<DD>Invoke
+<I>command</I> for each matching node. Before <I>command</I> is invoked, the id of the
+node is appended. You can control processing by the return value of <I>command</I>.
+ If <I>command</I> generates an error, processing stops and the <B>find</B> operation
+ returns an error. But if <I>command</I> returns <B>break</B>, then processing stops,
+no error is generated. If <I>command</I> returns <B>continue</B>, then processing stops
+on that subtree and continues on the next. </DD>
+
+<DT><B>-regexp</B> <I>string</I> </DT>
+<DD>Test each node
+using <I>string</I> as a regular expression pattern. </DD>
+
+<DT><B>-tag</B> <I>string</I> </DT>
+<DD>Only test nodes
+that have the tag <I>string</I>. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>attach</B> <I>treeObject</I> </DT>
+<DD>Attaches to an existing
+tree object <I>treeObject</I>. This is for cases where the tree object was previously
+created via the C API. The current tree associated with <I>treeName</I> is discarded.
+ In addition, the current set of tags, notifier events, and traces are
+removed. </DD>
+
+<DT><I>treeName</I> <B>children</B> <I>node</I> </DT>
+<DD>Returns a list of children for <I>node</I>. If
+<I>node</I> is a leaf, then an empty string is returned. </DD>
+
+<DT><I>treeName</I> <B>copy</B> <I>srcNode</I>
+?<I>destTree</I>? <I>destNode</I> ?<I>switches</I>? </DT>
+<DD>Copies <I>srcNode</I> into <I>destNode</I>. Both nodes
+<I>srcNode</I> and <I>destNode</I> must already exist. If <I>destTree</I> argument is present,
+it indicates the name of the destination tree. By default both the source
+and destination trees are the same. The valid <I>switches</I> are listed below:
+<blockquote></DD>
+
+<DT><B>-overwrite</B> </DT>
+<DD>Overwrite nodes that already exist. Normally nodes are always
+created, even if there already exists a node by the same name. This switch
+indicates to add or overwrite the node's data fields. </DD>
+
+<DT><B>-recurse</B> </DT>
+<DD>Recursively
+copy all the subtrees of <I>srcNode</I> as well. In this case, <I>srcNode</I> can't be
+an ancestor of <I>destNode</I> as it would result in a cyclic copy. </DD>
+
+<DT><B>-tags</B> </DT>
+<DD>Copy tag
+inforation. Normally the following node is copied: its label and data
+fields. This indicates to copy tags as well. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>degree</B> <I>node</I> </DT>
+<DD>Returns
+the number of children of <I>node</I>. </DD>
+
+<DT><I>treeName</I> <B>delete</B> <I>node</I>... </DT>
+<DD>Recursively deletes
+one or more nodes from the tree. The node and all its descendants are
+removed. The one exception is the root node. In this case, only its descendants
+are removed. The root node will remain. Any tags or traces on the nodes
+are released. </DD>
+
+<DT><I>treeName</I> <B>depth</B> <I>node</I> </DT>
+<DD>Returns the depth of the node. The depth
+is the number of steps from the node to the root of the tree. The depth
+of the root node is <I>0</I>. </DD>
+
+<DT><I>treeName</I> <B>dump</B> <I>node</I> </DT>
+<DD>Returns a list of the paths and
+respective data for <I>node</I> and its descendants. The subtree designated by
+<I>node</I> is traversed returning the following information for each node: 1)
+the node's path relative to <I>node</I>, 2) a sublist key value pairs representing
+the node's data fields, and 3) a sublist of tags. This list returned can
+be used later to copy or restore the tree with the <B>restore</B> operation. </DD>
+
+<DT><I>treeName</I>
+<B>dumpfile</B> <I>node</I> <I>fileName</I> </DT>
+<DD>Writes a list of the paths and respective data for
+<I>node</I> and its descendants to the given file <I>fileName</I>. The subtree designated
+by <I>node</I> is traversed returning the following information for each node:
+1) the node's path relative to <I>node</I>, 2) a sublist key value pairs representing
+the node's data fields, and 3) a sublist of tags. This list returned can
+be used later to copy or restore the tree with the <B>restore</B> operation. </DD>
+
+<DT><I>treeName</I>
+<B>exists</B> <I>node</I> ?<I>key</I>? </DT>
+<DD>Indicates if <I>node</I> exists in the tree. If a <I>key</I> argument
+is present then the command also indicates if the named data field exists.
+</DD>
+
+<DT><I>treeName</I> <B>find</B> <I>node</I> ?<I>switches</I>? </DT>
+<DD>Finds for all nodes matching the criteria
+given by <I>switches</I> for the subtree designated by <I>node</I>. A list of the selected
+ nodes is returned. By default all nodes match, but you can set switches
+to narrow the match. <P>
+The <B>-exact</B>, <B>-glob</B>, and <B>-regexp</B> switches indicate both
+what kind of pattern matching to perform and the pattern. Pattern matching
+is done, by default, against each node's label. But if the <B>-path</B> switch is
+present, it will match the full path of the node. If the <B>-key</B> switch is
+used, it designates the data field to be matched. <P>
+The order in which
+the nodes are traversed is controlled by the <B>-order</B> switch. The possible
+orderings are <B>preorder</B>, <B>postorder</B>, <B>inorder</B>, and <B>breadthfirst</B>. The default
+is <B>postorder</B>. <P>
+The valid switches are listed below: <blockquote></DD>
+
+<DT><B>-addtag</B> <I>string</I> </DT>
+<DD>Add the
+tag <I>string</I> to each selected node. </DD>
+
+<DT><B>-count</B> <I>number</I> </DT>
+<DD>Stop processing after <I>number</I>
+(a positive integer) matches. </DD>
+
+<DT><B>-depth</B> <I>number</I> </DT>
+<DD>Descend at most <I>number</I> (a non-negative
+integer) levels If <I>number</I> is <I>1</I> this means only apply the tests to the children
+of <I>node</I>. </DD>
+
+<DT><B>-exact</B> <I>string</I> </DT>
+<DD>Matches each node using <I>string</I>. The node must match
+<I>string</I> exactly. </DD>
+
+<DT><B>-exec</B> <I>command</I> </DT>
+<DD>Invoke <I>command</I> for each matching node. Before
+<I>command</I> is invoked, the id of the node is appended. You can control processing
+by the return value of <I>command</I>. If <I>command</I> generates an error, processing
+stops and the <B>find</B> operation returns an error. But if <I>command</I> returns
+<B>break</B>, then processing stops, no error is generated. If <I>command</I> returns
+ <B>continue</B>, then processing stops on that subtree and continues on the next.
+</DD>
+
+<DT><B>-glob</B> <I>string</I> </DT>
+<DD>Test each node to <I>string</I> using global pattern matching. Matching
+is done in a fashion similar to that used by the C-shell. </DD>
+
+<DT><B>-invert</B> </DT>
+<DD>Select non-matching
+nodes. Any node that <I>doesn't</I> match the given criteria will be selected. </DD>
+
+<DT><B>-key</B>
+<I>key</I> </DT>
+<DD>If pattern matching is selected (using the <B>-exact</B>, <B>-glob</B>, or <B>-regexp</B> switches),
+compare the values of the data field keyed by <I>key</I> instead of the node's
+label. If no pattern matching switches are set, then any node with this
+data key will match. </DD>
+
+<DT><B>-leafonly</B> </DT>
+<DD>Only test nodes with no children. </DD>
+
+<DT><B>-nocase</B> </DT>
+<DD>Ignore
+case when matching patterns. </DD>
+
+<DT><B>-order</B> <I>string</I> </DT>
+<DD>Traverse the tree and process
+nodes according to <I>string</I>. <I>String</I> can be one of the following: <blockquote></DD>
+
+<DT><B>breadthfirst</B>
+ </DT>
+<DD>Process the node and the subtrees at each sucessive level. Each node on
+a level is processed before going to the next level. </DD>
+
+<DT><B>inorder</B> </DT>
+<DD>Recursively
+process the nodes of the first subtree, the node itself, and any the remaining
+subtrees. </DD>
+
+<DT><B>postorder</B> </DT>
+<DD>Recursively process all subtrees before the node. </DD>
+
+<DT><B>preorder</B>
+ </DT>
+<DD>Recursively process the node first, then any subtrees. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><B>-path</B> </DT>
+<DD>Use the node's
+full path when comparing nodes. </DD>
+
+<DT><B>-regexp</B> <I>string</I> </DT>
+<DD>Test each node using <I>string</I>
+as a regular expression pattern. </DD>
+
+<DT><B>-tag</B> <I>string</I> </DT>
+<DD>Only test nodes that have the
+tag <I>string</I>. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>findchild</B> <I>node</I> <I>label</I> </DT>
+<DD>Searches for a child node Ilabel
+in <I>node</I>. The id of the child node is returned if found. Otherwise <I>-1</I> is
+returned. </DD>
+
+<DT><I>treeName</I> <B>firstchild</B> <I>node</I> </DT>
+<DD>Returns the id of the first child in
+the <I>node</I>'s list of subtrees. If <I>node</I> is a leaf (has no children), then
+<I>-1</I> is returned. </DD>
+
+<DT><I>treeName</I> <B>get</B> <I>node</I> ?<I>key</I>? ?<I>defaultValue</I>? </DT>
+<DD>Returns a list of
+key-value pairs of data for the node. If <I>key</I> is present, then onlyx the
+value for that particular data field is returned. It's normally an error
+if <I>node</I> does not contain the data field <I>key</I>. But if you provide a <I>defaultValue</I>
+argument, this value is returned instead (<I>node</I> will still not contain <I>key</I>).
+ This feature can be used to access a data field of <I>node</I> without first
+testing if it exists. This operation may trigger <B>read</B> data traces. </DD>
+
+<DT><I>treeName</I>
+<B>index</B> <I>node</I> </DT>
+<DD>Returns the id of <I>node</I>. If <I>node</I> is a tag, it can only specify
+one node. If <I>node</I> does not represent a valid node id or tag, or has modifiers
+that are invalid, then <I>-1</I> is returned. </DD>
+
+<DT><I>treeName</I> <B>insert</B> <I>parent</I> ?<I>switches</I>?
+ </DT>
+<DD>Inserts a new node into parent node <I>parent</I>. The id of the new node is
+returned. The following switches are available: <blockquote></DD>
+
+<DT><B>-at</B> <I>number</I> </DT>
+<DD>Inserts the
+node into <I>parent</I>'s list of children at position <I>number</I>. The default is
+to append <I>node</I>. </DD>
+
+<DT><B>-data</B> <I>dataList</I> </DT>
+<DD>Sets the value for each data field in <I>dataList</I>
+for the new node. <I>DataList</I> is a list of key-value pairs. </DD>
+
+<DT><B>-label</B> <I>string</I> </DT>
+<DD>Designates
+the labels of the node as <I>string</I>. By default, nodes are labeled as <I>node0</I>,
+<I>node1</I>, etc. </DD>
+
+<DT><B>-tags</B> <I>tagList</I> </DT>
+<DD>Adds each tag in <I>tagList</I> to the new node. <I>TagList</I>
+is a list of tags, so be careful if a tag has embedded space. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>is</B>
+<I>property</I> <I>args</I> </DT>
+<DD>Indicates the property of a node. Both <I>property</I> and <I>args</I>
+determine the property being tested. Returns <I>1</I> if true and <I>0</I> otherwise.
+ The following <I>property</I> and <I>args</I> are valid: <blockquote></DD>
+
+<DT><B>ancestor</B> <I>node1</I> <I>node2</I> </DT>
+<DD>Indicates
+if <I>node1</I> is an ancestor of <I>node2</I>. </DD>
+
+<DT><B>before</B> <I>node1</I> <I>node2</I> </DT>
+<DD>Indicates if <I>node1</I>
+is before <I>node2</I> in depth first traversal. </DD>
+
+<DT><B>leaf</B> <I>node</I> </DT>
+<DD>Indicates if <I>node</I> is
+a leaf (it has no subtrees). </DD>
+
+<DT><B>root</B> <I>node</I> </DT>
+<DD>Indicates if <I>node</I> is the designated
+root. This can be changed by the <B>root</B> operation. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>label</B> <I>node</I> ?<I>newLabel</I>?
+</DT>
+<DD>Returns the label of the node designated by <I>node</I>. If <I>newLabel</I> is present,
+the node is relabeled using it as the new label. </DD>
+
+<DT><I>treeName</I> <B>lastchild</B> <I>node</I>
+</DT>
+<DD>Returns the id of the last child in the <I>node</I>'s list of subtrees. If <I>node</I>
+is a leaf (has no children), then <I>-1</I> is returned. </DD>
+
+<DT><I>treeName</I> <B>move</B> <I>node</I> <I>newParent</I>
+?<I>switches</I>? </DT>
+<DD>Moves <I>node</I> into <I>newParent</I>. <I>Node</I> is appended to the list children
+of <I>newParent</I>. <I>Node</I> can not be an ancestor of <I>newParent</I>. The valid flags
+for <I>switches</I> are described below. <blockquote></DD>
+
+<DT><B>-after</B> <I>child</I> </DT>
+<DD>Position <I>node</I> after <I>child</I>.
+ The node <I>child</I> must be a child of <I>newParent</I>. </DD>
+
+<DT><B>-at</B> <I>number</I> </DT>
+<DD>Inserts <I>node</I> into
+<I>parent</I>'s list of children at position <I>number</I>. The default is to append the
+node. </DD>
+
+<DT><B>-before</B> <I>child</I> </DT>
+<DD>Position <I>node</I> before <I>child</I>. The node <I>child</I> must be a
+ child of <I>newParent</I>. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>next</B> <I>node</I> </DT>
+<DD>Returns the next node from <I>node</I>
+in a preorder traversal. If <I>node</I> is the last node in the tree, then <I>-1</I> is
+returned. </DD>
+
+<DT><I>treeName</I> <B>nextsibling</B> <I>node</I> </DT>
+<DD>Returns the node representing the next
+subtree from <I>node</I> in its parent's list of children. If <I>node</I> is the last
+child, then <I>-1</I> is returned. </DD>
+
+<DT><I>treeName</I> <B>notify</B> <I>args</I> </DT>
+<DD>Manages notification events
+that indicate that the tree structure has been changed. See the <FONT SIZE=-1><B>NOTIFY
+OPERATIONS</B></FONT>
+ section below. </DD>
+
+<DT><I>treeName</I> <B>parent</B> <I>node</I> </DT>
+<DD>Returns the parent node
+of <I>node</I>. If <I>node</I> is the root of the tree, then <I>-1</I> is returned. </DD>
+
+<DT><I>treeName</I>
+<B>path</B> <I>node</I> </DT>
+<DD>Returns the full path (from root) of <I>node</I>. </DD>
+
+<DT><I>treeName</I> <B>position</B> <I>node</I>
+</DT>
+<DD>Returns the position of the node in its parent's list of children. Positions
+are numbered from 0. The position of the root node is always 0. </DD>
+
+<DT><I>treeName</I>
+<B>previous</B> <I>node</I> </DT>
+<DD>Returns the previous node from <I>node</I> in a preorder traversal.
+If <I>node</I> is the root of the tree, then <I>-1</I> is returned. </DD>
+
+<DT><I>treeName</I> <B>prevsibling</B>
+<I>node</I> </DT>
+<DD>Returns the node representing the previous subtree from <I>node</I> in its
+parent's list of children. If <I>node</I> is the first child, then <I>-1</I> is returned.
+</DD>
+
+<DT><I>treeName</I> <B>restore</B> <I>node</I> <I>dataString</I> <I>switches</I> </DT>
+<DD>Performs the inverse function
+of the <B>dump</B> operation, restoring nodes to the tree. The format of <I>dataString</I>
+is exactly what is returned by the <B>dump</B> operation. It's a list containing
+information for each node to be restored. The information consists of 1)
+the relative path of the node, 2) a sublist of key value pairs representing
+the node's data, and 3) a list of tags for the node. Nodes are created
+ starting from <I>node</I>. Nodes can be listed in any order. If a node's path
+describes ancestor nodes that do not already exist, they are automatically
+created. The valid <I>switches</I> are listed below: <blockquote></DD>
+
+<DT><B>-overwrite</B> </DT>
+<DD>Overwrite nodes
+that already exist. Normally nodes are always created, even if there already
+exists a node by the same name. This switch indicates to add or overwrite
+the node's data fields. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>restorefile</B> <I>node</I> <I>fileName</I> <I>switches</I> </DT>
+<DD>Performs
+the inverse function of the <B>dumpfile</B> operation, restoring nodes to the
+tree from the file <I>fileName</I>. The format of <I>fileName</I> is exactly what is
+returned by the <B>dumpfile</B> operation. It's a list containing information
+for each node to be restored. The information consists of 1) the relative
+path of the node, 2) a sublist of key value pairs representing the node's
+data, and 3) a list of tags for the node. Nodes are created starting
+from <I>node</I>. Nodes can be listed in any order. If a node's path describes
+ancestor nodes that do not already exist, they are automatically created.
+ The valid <I>switches</I> are listed below: <blockquote></DD>
+
+<DT><B>-overwrite</B> </DT>
+<DD>Overwrite nodes that already
+exist. Normally nodes are always created, even if there already exists
+a node by the same name. This switch indicates to add or overwrite the
+node's data fields. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>root</B> ?<I>node</I>? </DT>
+<DD>Returns the id of the root node.
+ Normally this is node <I>0</I>. If a <I>node</I> argument is provided, it will become
+the new root of the tree. This lets you temporarily work within a subset
+of the tree. Changing root affects operations such as <B>next</B>, <B>path</B>, <B>previous</B>,
+etc. </DD>
+
+<DT><I>treeName</I> <B>set</B> <I>node</I> <I>key value</I> ?<I>key value</I>...? </DT>
+<DD>Sets one or more data fields
+in <I>node</I>. <I>Node</I> may be a tag that represents several nodes. <I>Key</I> is the name
+of the data field to be set and <I>value</I> is its respective value. This operation
+may trigger <B>write</B> and <B>create</B> data traces. </DD>
+
+<DT><I>treeName</I> <B>size</B> <I>node</I> </DT>
+<DD>Returns the
+number of nodes in the subtree. This includes the node and all its descendants.
+ The size of a leaf node is 1. </DD>
+
+<DT><I>treeName</I> <B>sort</B> <I>node</I> ?<I>switches</I>? </DT>
+<DD><blockquote></DD>
+
+<DT><B>-ascii</B> </DT>
+<DD>Compare
+strings using the ASCII collation order. </DD>
+
+<DT><B>-command</B> <I>string</I> </DT>
+<DD>Use command <I>string</I>
+as a comparison command. To compare two elements, evaluate a Tcl script
+consisting of command with the two elements appended as additional arguments.
+ The script should return an integer less than, equal to, or greater than
+zero if the first element is to be considered less than, equal to, or greater
+than the second, respectively. </DD>
+
+<DT><B>-decreasing</B> </DT>
+<DD>Sort in decreasing order (largest
+items come first). </DD>
+
+<DT><B>-dictionary</B> </DT>
+<DD>Compare strings using a dictionary-style comparison.
+ This is the same as <B>-ascii</B> except (a) case is ignored except as a tie-breaker
+and (b) if two strings contain embedded numbers, the numbers compare as
+integers, not characters. For example, in <B>-dictionary</B> mode, bigBoy sorts
+between bigbang and bigboy, and x10y sorts between x9y and x11y. </DD>
+
+<DT><B>-integer</B>
+</DT>
+<DD>Compare the nodes as integers. </DD>
+
+<DT><B>-key</B> <I>string</I> </DT>
+<DD>Sort based upon the node's data
+field keyed by <I>string</I>. Normally nodes are sorted according to their label.
+ </DD>
+
+<DT><B>-path</B> </DT>
+<DD>Compare the full path of each node. The default is to compare only
+its label. </DD>
+
+<DT><B>-real</B> </DT>
+<DD>Compare the nodes as real numbers. </DD>
+
+<DT><B>-recurse</B> </DT>
+<DD>Recursively sort
+the entire subtree rooted at <I>node</I>. </DD>
+
+<DT><B>-reorder</B> </DT>
+<DD>Recursively sort subtrees for
+each node. <B>Warning</B>. Unlike the normal flat sort, where a list of nodes
+is returned, this will reorder the tree. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I> <B>tag</B> <I>args</I> </DT>
+<DD>Manages tags
+for the tree object. See the <FONT SIZE=-1><B>TAG OPERATIONS</B></FONT>
+ section below. </DD>
+
+<DT><I>treeName</I> <B>trace</B>
+<I>args</I> </DT>
+<DD>Manages traces for data fields in the tree object. Traces cause Tcl
+commands to be executed whenever a data field of a node is created, read,
+written, or unset. Traces can be set for a specific node or a tag, representing
+possibly many nodes. See the <FONT SIZE=-1><B>TRACE OPERATIONS</B></FONT>
+ section below. </DD>
+
+<DT><I>treeName</I> <B>unset</B>
+<I>node</I> <I>key</I>... </DT>
+<DD>Removes one or more data fields from <I>node</I>. <I>Node</I> may be a tag that
+represents several nodes. <I>Key</I> is the name of the data field to be removed.
+ It's not an error is <I>node</I> does not contain <I>key</I>. This operation may trigger
+<B>unset</B> data traces. </DD>
+</DL>
+</blockquote>
+
+<H2><A NAME="sect9" HREF="#toc9">Tag Operations</A></H2>
+Tags are a general means of selecting and
+marking nodes in the tree. A tag is just a string of characters, and it
+may take any form except that of an integer. The same tag may be associated
+with many different nodes. <P>
+There are two built-in tags: The tag <B>all</B> is
+implicitly associated with every node in the tree. It may be used to invoke
+operations on all the nodes in the tree. The tag <B>root</B> is managed automatically
+by the tree object. It specifies the node that is currently set as the
+root of the tree. <P>
+Most tree operations use tags. And several operations
+let you operate on multiple nodes at once. For example, you can use the
+<B>set</B> operation with the tag <B>all</B> to set a data field in for all nodes in
+the tree. <P>
+Tags are invoked by the <B>tag</B> operation. The general form is <BR>
+<P>
+<CODE><I>treeName</I> <B>tag</B> <I>operation</I> ?<I>arg</I>?...<BR>
+</CODE><P>Both <I>operation</I> and its arguments determine the exact behavior of the command.
+ The operations available for tags are listed below.
+<DL>
+
+<DT><I>treeName</I> <B>tag add</B> <I>string</I>
+<I>node</I>... </DT>
+<DD>Adds the tag <I>string</I> to one of more nodes. </DD>
+
+<DT><I>treeName</I> <B>tag delete</B> <I>string</I>
+<I>node</I>... </DT>
+<DD>Deletes the tag <I>string</I> from one or more nodes. </DD>
+
+<DT><I>treeName</I> <B>tag forget</B>
+<I>string</I> </DT>
+<DD>Removes the tag <I>string</I> from all nodes. It's not an error if no nodes
+are tagged as <I>string</I>. </DD>
+
+<DT><I>treeName</I> <B>tag names</B> ?<I>node</I>? </DT>
+<DD>Returns a list of tags used
+by the tree. If a <I>node</I> argument is present, only those tags used by <I>node</I>
+are returned. </DD>
+
+<DT><I>treeName</I> <B>tag nodes</B> <I>string</I> </DT>
+<DD>Returns a list of nodes that have
+the tag <I>string</I>. If no node is tagged as <I>string</I>, then an empty string is
+returned. </DD>
+</DL>
+
+<H2><A NAME="sect10" HREF="#toc10">Trace Operations</A></H2>
+Data fields can be traced much in the same way
+that you can trace Tcl variables. Data traces cause Tcl commands to be
+executed whenever a particular data field of a node is created, read, written,
+or unset. A trace can apply to one or more nodes. You can trace a specific
+node by using its id, or a group of nodes by a their tag. <P>
+The tree's <B>get</B>,
+<B>set</B>, and <B>unset</B> operations can trigger various traces. The <B>get</B> operation
+can cause a <I>read</I> trace to fire. The <B>set</B> operation causes a <I>write</I> trace
+to fire. And if the data field is written for the first time, you will
+also get a <I>create</I> trace. The <B>unset</B> operation triggers <I>unset</I> traces. <P>
+Data
+traces are invoked by the <B>trace</B> operation. The general form is <BR>
+<P>
+<CODE><I>treeName</I> <B>trace</B> <I>operation</I> ?<I>arg</I>?...<BR>
+</CODE><P>Both <I>operation</I> and its arguments determine the exact behavior of the command.
+ The operations available for traces are listed below.
+<DL>
+
+<DT><I>treeName</I> <B>trace create</B>
+<I>node</I> <I>key</I> <I>ops</I> <I>command</I> </DT>
+<DD>Creates a trace for <I>node</I> on data field <I>key</I>. <I>Node</I> can
+refer to more than one node (for example, the tag <B>all</B>). If <I>node</I> is a tag,
+any node with that tag can possibly trigger a trace, invoking <I>command</I>.
+ <I>Command</I> is command prefix, typically a procedure name. Whenever a trace
+is triggered, four arguments are appended to <I>command</I> before it is invoked:
+<I>treeName</I>, id of the node, <I>key</I> and, <I>ops</I>. Note that no nodes need have the
+field <I>key</I>. A trace identifier in the form "<I>trace0</I>", "<I>trace1</I>", etc. is returned.
+ <P>
+<I>Ops</I> indicates which operations are of interest, and consists of one or
+more of the following letters: <blockquote></DD>
+
+<DT><B>r</B> </DT>
+<DD>Invoke <I>command</I> whenever <I>key</I> is read. Both
+read and write traces are temporarily disabled when <I>command</I> is executed.
+</DD>
+
+<DT><B>w</B> </DT>
+<DD>Invoke <I>command</I> whenever <I>key</I> is written. Both read and write traces are
+temporarily disabled when <I>command</I> is executed. </DD>
+
+<DT><B>c</B> </DT>
+<DD>Invoke <I>command</I> whenever
+<I>key</I> is created. </DD>
+
+<DT><B>u</B> </DT>
+<DD>Invoke <I>command</I> whenever <I>key</I> is unset. Data fields are
+typically unset with the <B>unset</B> command. Data fields are also unset when
+the tree is released, but all traces are disabled prior to that. <P>
+</DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I>
+<B>trace delete</B> <I>traceId</I>... </DT>
+<DD>Deletes one of more traces. <I>TraceId</I> is the trace identifier
+returned by the <B>trace create</B> operation. </DD>
+
+<DT><I>treeName</I> <B>trace info</B> <I>traceId</I> </DT>
+<DD>Returns
+information about the trace <I>traceId</I>. <I>TraceId</I> is a trace identifier previously
+returned by the <B>trace create</B> operation. It's the same information specified
+for the <B>trace create</B> operation. It consists of the node id or tag, data
+field key, a string of letters indicating the operations that are traced
+(it's in the same form as <I>ops</I>) and, the command prefix. </DD>
+
+<DT><I>treeName</I> <B>trace names</B>
+</DT>
+<DD>Returns a list of identifers for all the current traces. </DD>
+</DL>
+
+<H2><A NAME="sect11" HREF="#toc11">Notify Operations</A></H2>
+Tree
+objects can be shared among many clients, such as a <B>hiertable</B> widget. Any
+client can create or delete nodes, sorting the tree, etc. You can request
+to be notified whenever these events occur. Notify events cause Tcl commands
+to be executed whenever the tree structure is changed. <P>
+Notifications are
+handled by the <B>notify</B> operation. The general form is <BR>
+<P>
+<CODE><I>treeName</I> <B>notify</B> <I>operation</I> ?<I>arg</I>?...<BR>
+</CODE><P>Both <I>operation</I> and its arguments determine the exact behavior of the command.
+ The operations available for events are listed below.
+<DL>
+
+<DT><I>treeName</I> <B>notify create</B>
+?<I>switches</I>? <I>command</I> ?<I>args</I>?... </DT>
+<DD>Creates a notifier for the tree. A notify identifier
+in the form "<I>notify0</I>", "<I>notify1</I>", etc. is returned. <P>
+<I>Command</I> and <I>args</I> are
+saved and invoked whenever the tree structure is changed (according to
+<I>switches</I>). Two arguments are appended to <I>command</I> and <I>args</I> before it's invoked:
+the id of the node and a string representing the type of event that occured.
+One of more switches can be set to indicate the events that are of interest.
+ The valid switches are as follows: <blockquote></DD>
+
+<DT><B>-create</B> </DT>
+<DD>Invoke <I>command</I> whenever a new
+node has been added. </DD>
+
+<DT><B>-delete</B> </DT>
+<DD>Invoke <I>command</I> whenever a node has been deleted.
+</DD>
+
+<DT><B>-move</B> </DT>
+<DD>Invoke <I>command</I> whenever a node has been moved. </DD>
+
+<DT><B>-sort</B> </DT>
+<DD>Invoke <I>command</I>
+whenever the tree has been sorted and reordered. </DD>
+
+<DT><B>-relabel</B> </DT>
+<DD>Invoke <I>command</I>
+whenever a node has been relabeled. </DD>
+
+<DT><B>-allevents</B> </DT>
+<DD>Invoke <I>command</I> whenever any
+of the above events occur. </DD>
+
+<DT><B>-whenidle</B> </DT>
+<DD>When an event occurs don't invoke <I>command</I>
+immediately, but queue it to be run the next time the event loop is entered
+and there are no events to process. If subsequent events occur before
+ the event loop is entered, <I>command</I> will still be invoked only once. </DD>
+</DL>
+</blockquote>
+
+<DL>
+
+<DT><I>treeName</I>
+<B>notify delete</B> <I>notifyId</I> </DT>
+<DD>Deletes one or more notifiers from the tree. <I>NotifyId</I>
+is the notifier identifier returned by the <B>notify create</B> operation. </DD>
+
+<DT><I>treeName</I>
+<B>notify info</B> <I>notifyId</I> </DT>
+<DD>Returns information about the notify event <I>notifyId</I>.
+ <I>NotifyId</I> is a notify identifier previously returned by the <B>notify create</B>
+operation. It's the same information specified for the <B>notify create</B> operation.
+It consists of the notify id, a sublist of event flags (it's in the same
+form as <I>flags</I>) and, the command prefix. </DD>
+
+<DT><I>treeName</I> <B>notify names</B> </DT>
+<DD>Returns a
+list of identifers for all the current notifiers. </DD>
+</DL>
+
+<H2><A NAME="sect12" HREF="#toc12">C Language API</A></H2>
+Blt_TreeApply,
+ Blt_TreeApplyBFS, Blt_TreeApplyDFS, Blt_TreeChangeRoot, Blt_TreeCreate,
+ Blt_TreeCreateEventHandler, Blt_TreeCreateNode, Blt_TreeCreateTrace,
+ Blt_TreeDeleteEventHandler, Blt_TreeDeleteNode, Blt_TreeDeleteTrace,
+ Blt_TreeExists, Blt_TreeFindChild, Blt_TreeFirstChild, Blt_TreeFirstKey,
+ Blt_TreeGetNode, Blt_TreeGetToken, Blt_TreeGetValue, Blt_TreeIsAncestor,
+ Blt_TreeIsBefore, Blt_TreeIsLeaf, Blt_TreeLastChild, Blt_TreeMoveNode,
+ Blt_TreeName, Blt_TreeNextKey, Blt_TreeNextNode, Blt_TreeNextSibling,
+ Blt_TreeNodeDegree, Blt_TreeNodeDepth, Blt_TreeNodeId, Blt_TreeNodeLabel,
+ Blt_TreeNodeParent, Blt_TreePrevNode, Blt_TreePrevSibling, Blt_TreeRelabelNode,
+ Blt_TreeReleaseToken, Blt_TreeRootNode, Blt_TreeSetValue, Blt_TreeSize,
+ Blt_TreeSortNode, and Blt_TreeUnsetValue.
+<H2><A NAME="sect13" HREF="#toc13">Keywords</A></H2>
+tree, hiertable, widget
+<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">Description</A></LI>
+<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
+<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
+<LI><A NAME="toc5" HREF="#sect5">Syntax</A></LI>
+<LI><A NAME="toc6" HREF="#sect6">Node IDs and Tags</A></LI>
+<LI><A NAME="toc7" HREF="#sect7">Node Modifiers</A></LI>
+<LI><A NAME="toc8" HREF="#sect8">Tree Operations</A></LI>
+<LI><A NAME="toc9" HREF="#sect9">Tag Operations</A></LI>
+<LI><A NAME="toc10" HREF="#sect10">Trace Operations</A></LI>
+<LI><A NAME="toc11" HREF="#sect11">Notify Operations</A></LI>
+<LI><A NAME="toc12" HREF="#sect12">C Language API</A></LI>
+<LI><A NAME="toc13" HREF="#sect13">Keywords</A></LI>
+</UL>
+</BODY></HTML>
View Lorry Controller Status