'\"
'\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies.
'\"
'\" Permission to use, copy, modify, and distribute this software and its
'\" documentation for any purpose and without fee is hereby granted, provided
'\" that the above copyright notice appear in all copies and that both that the
'\" copyright notice and warranty disclaimer appear in supporting documentation,
'\" and that the names of Lucent Technologies any of their entities not be used
'\" in advertising or publicity pertaining to distribution of the software
'\" without specific, written prior permission.
'\"
'\" Lucent Technologies disclaims all warranties with regard to this software,
'\" including all implied warranties of merchantability and fitness.  In no event
'\" shall Lucent Technologies be liable for any special, indirect or
'\" consequential damages or any damages whatsoever resulting from loss of use,
'\" data or profits, whether in an action of contract, negligence or other
'\" tortuous action, arising out of or in connection with the use or performance
'\" of this software.  
'\"
'\"
.so man.macros
.TH Blt_TreeDeleteNode 3 BLT_VERSION BLT "BLT Library Procedures"
.BS
.SH NAME
Blt_TreeDeleteNode \- Deletes a node and its descendants.
.SH SYNOPSIS
.nf
#include <bltTree.h>
.sp
Blt_TreeNode
\fBBlt_TreeDeleteNode\fR(\fItree\fR, \fInode\fR)
.fi
.SH ARGUMENTS
.AS Blt_TreeNode node
.AP Blt_Tree tree in
Tree containing the node.
.AP Blt_TreeNode node in
Node to be deleted.
.BE
.SH DESCRIPTION
This procedure deletes a given node and all it descendants from a tree
data object.  
.PP
The arguments are as follows:
.TP 1i
\fItree\fR
The tree containing the parent node.
.TP 
\fInode\fR
Node to be deleted.  The node and its descendant nodes are deleted.
Each node's data values are deleted also.   The reference count of
the Tcl_Obj is decremented.
.PP
Since all tree objects must contain at least a root node, the root
node itself can't be deleted unless the tree is released and
destroyed. Therefore you can clear a tree by deleting its root, but
the root node will remain until the tree is destroyed.
.SH RETURNS
Always returns TCL_OK.  Errors generated in a notification callbacks
are backgrounded (see \fBTcl_TreeCreateNotifyHandler\fR).
.SH EXAMPLE
The following example deletes the root node.
.CS
Blt_TreeNode root;

root = Blt_TreeRootNode(token);
Blt_TreeDeleteNode(token, root);
.CE
.SH NOTIFICATIONS
\fBBlt_TreeDeleteNode\fR can trigger tree notify events.
You can be notified whenever a node is deleted by using the 
\fBBlt_TreeCreateNotifyHandler\fR.  A callback routine is registered
that will be automatically invoked whenever a node is deleted
via \fBBlt_TreeDeleteNode\fR to the tree.
.SH KEYWORDS
tree, token
