'\"
'\" 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: Blt_Tree.man3,v 1.1.1.1 2009/05/09 16:27:39 pcmacdon Exp $
'\" 
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\"	Start paragraph describing an argument to a library procedure.
'\"	type is type of argument (int, etc.), in/out is either "in", "out",
'\"	or "in/out" to describe whether procedure reads or modifies arg,
'\"	and indent is equivalent to second arg of .IP (shouldn't ever be
'\"	needed;  use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\"	Give maximum sizes of arguments for setting tab stops.  Type and
'\"	name are examples of largest possible arguments that will be passed
'\"	to .AP later.  If args are omitted, default tab stops are used.
'\"
'\" .BS
'\"	Start box enclosure.  From here until next .BE, everything will be
'\"	enclosed in one large box.
'\"
'\" .BE
'\"	End of box enclosure.
'\"
'\" .CS
'\"	Begin code excerpt.
'\"
'\" .CE
'\"	End code excerpt.
'\"
'\" .VS ?version? ?br?
'\"	Begin vertical sidebar, for use in marking newly-changed parts
'\"	of man pages.  The first argument is ignored and used for recording
'\"	the version when the .VS was added, so that the sidebars can be
'\"	found and removed when they reach a certain age.  If another argument
'\"	is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\"	End of vertical sidebar.
'\"
'\" .DS
'\"	Begin an indented unfilled display.
'\"
'\" .DE
'\"	End of indented unfilled display.
'\"
'\" .SO
'\"	Start of list of standard options for a Tk widget.  The
'\"	options follow on successive lines, in four columns separated
'\"	by tabs.
'\"
'\" .SE
'\"	End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\"	Start of description of a specific option.  cmdName gives the
'\"	option's name as specified in the class command, dbName gives
'\"	the option's name in the option database, and dbClass gives
'\"	the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\"	Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.1.1.1 2009/05/09 16:27:42 pcmacdon Exp $
'\"
'\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
'\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
'\"	# VS - start vertical sidebar
'\"	# ^Y = starting y location
'\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
'\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
'\"	# Special macro to handle page bottom:  finish off current
'\"	# box/sidebar if in box/sidebar mode, then invoked standard
'\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
'\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
'\"	# DE - end display
.de DE
.fi
.RE
.sp
..
'\"	# SO - start of list of standard options
.de SO
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 4c 8c 12c
.ft B
..
'\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\fBoptions\\fR manual entry for details on the standard options.
..
'\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
'\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
.ft CW
.sp
..
'\"	# CE - end code excerpt
.de CE
.fi
.RE
.ft R
.sp
..
.de UL
\\$1\l'|0\(ul'\\$2
..
.TH Blt_Tree 3 2.5 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)
.fi
.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