2 '\" Copyright 1991-1998 by Bell Labs Innovations for Lucent Technologies.
4 '\" Permission to use, copy, modify, and distribute this software and its
5 '\" documentation for any purpose and without fee is hereby granted, provided
6 '\" that the above copyright notice appear in all copies and that both that the
7 '\" copyright notice and warranty disclaimer appear in supporting documentation,
8 '\" and that the names of Lucent Technologies any of their entities not be used
9 '\" in advertising or publicity pertaining to distribution of the software
10 '\" without specific, written prior permission.
12 '\" Lucent Technologies disclaims all warranties with regard to this software,
13 '\" including all implied warranties of merchantability and fitness. In no event
14 '\" shall Lucent Technologies be liable for any special, indirect or
15 '\" consequential damages or any damages whatsoever resulting from loss of use,
16 '\" data or profits, whether in an action of contract, negligence or other
17 '\" tortuous action, arising out of or in connection with the use or performance
21 '\" The definitions below are for supplemental macros used in Tcl/Tk
24 '\" .AP type name in/out ?indent?
25 '\" Start paragraph describing an argument to a library procedure.
26 '\" type is type of argument (int, etc.), in/out is either "in", "out",
27 '\" or "in/out" to describe whether procedure reads or modifies arg,
28 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
29 '\" needed; use .AS below instead)
32 '\" Give maximum sizes of arguments for setting tab stops. Type and
33 '\" name are examples of largest possible arguments that will be passed
34 '\" to .AP later. If args are omitted, default tab stops are used.
37 '\" Start box enclosure. From here until next .BE, everything will be
38 '\" enclosed in one large box.
41 '\" End of box enclosure.
44 '\" Begin code excerpt.
49 '\" .VS ?version? ?br?
50 '\" Begin vertical sidebar, for use in marking newly-changed parts
51 '\" of man pages. The first argument is ignored and used for recording
52 '\" the version when the .VS was added, so that the sidebars can be
53 '\" found and removed when they reach a certain age. If another argument
54 '\" is present, then a line break is forced before starting the sidebar.
57 '\" End of vertical sidebar.
60 '\" Begin an indented unfilled display.
63 '\" End of indented unfilled display.
66 '\" Start of list of standard options for a Tk widget. The
67 '\" options follow on successive lines, in four columns separated
71 '\" End of list of standard options for a Tk widget.
73 '\" .OP cmdName dbName dbClass
74 '\" Start of description of a specific option. cmdName gives the
75 '\" option's name as specified in the class command, dbName gives
76 '\" the option's name in the option database, and dbClass gives
77 '\" the option's class in the option database.
80 '\" Print arg1 underlined, then print arg2 normally.
82 '\" RCS: @(#) $Id: man.macros,v 1.3 2001/02/17 07:46:19 ghowlett Exp $
84 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
88 '\" # Start an argument description
92 . ie !"\\$2"" .TP \\n()Cu
97 \&\\$1 \\fI\\$2\\fP (\\$3)
110 '\" # define tabbing values for .AP
113 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
116 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
117 .nr )C \\n()Bu+\\w'(in/out)'u+2n
119 .AS Tcl_Interp Tcl_CreateInterp in/out
120 '\" # BS - start boxed text
121 '\" # ^y = starting y location
129 .if n \l'\\n(.lu\(ul'
132 '\" # BE - end boxed text (draw box now)
137 .ie n \l'\\n(^lu\(ul'
139 .\" Draw four-sided box normally, but don't draw top of
140 .\" box if the box started on an earlier page.
142 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
145 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
152 '\" # VS - start vertical sidebar
153 '\" # ^Y = starting y location
154 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
158 .ie n 'mc \s12\(br\s0
161 '\" # VE - end of vertical sidebar
169 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
176 '\" # Special macro to handle page bottom: finish off current
177 '\" # box/sidebar if in box/sidebar mode, then invoked standard
178 '\" # page bottom macro.
185 .\" Draw three-sided box if this is the box's first page,
186 .\" draw two sides but no top otherwise.
187 .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
188 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
191 .nr ^x \\n(^tu+1v-\\n(^Yu
192 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
205 '\" # DS - begin display
211 '\" # DE - end display
217 '\" # SO - start of list of standard options
219 .SH "STANDARD OPTIONS"
225 '\" # SE - end of list of standard options
230 See the \\fBoptions\\fR manual entry for details on the standard options.
232 '\" # OP - start of full description for a single option
237 Command-Line Name: \\fB\\$1\\fR
238 Database Name: \\fB\\$2\\fR
239 Database Class: \\fB\\$3\\fR
243 '\" # CS - begin code excerpt
251 '\" # CE - end code excerpt
261 .TH Blt_TreeCreateNode 3 2.4 BLT "BLT Library Procedures"
264 Blt_TreeCreateNode \- Creates a node in a tree data object.
270 \fBBlt_TreeCreateNode\fR(\fItree\fR, \fIparent\fR, \fIname\fR, \fIposition\fR)
272 .AS Blt_TreeNode parent
274 Tree containing the parent node.
275 .AP Blt_TreeNode parent in
276 Node in which to insert the new child.
277 .AP "const char" *name in
278 Node label. If NULL, a label will automatically be generated.
280 Position in the parent's list of children to insert the new node.
284 This procedure creates a new node is a tree data object. The node
285 is initially empty, but data values can be added with
286 \fBBlt_TreeSetValue\fR. Each node has a serial number that identifies it
287 within the tree. No two nodes in the same tree will ever have the
288 same ID. You can find a node's ID with \fBBlt_TreeNodeId\fR.
290 The arguments are as follows:
293 The tree containing the parent node.
296 Node in which the new child will be inserted.
299 Label of the new node. If \fIname\fR is NULL, a label in the
300 form "\f(CWnode0\fR", "\f(CWnode1\fR", etc. will automatically be
301 generated. \fIName\fR can be any string. Labels are non-unique. A
302 parent can contain two nodes with the same label. Nodes can be
303 relabeled using \fBBlt_TreeRelabelNode\fR.
306 Position the parent's list of children to insert the new node. For
307 example, if \fIposition\fR is 0, then the new node is prepended to the
308 beginning of the list. If \fIposition\fR is -1, then the node is
309 appended onto the end of the parent's list.
312 The new node returned is of type \fBBlt_TreeNode\fR. It's a token
313 that can be used with other routines to add/delete data values or
316 The following example creates a new node from the root node.
319 Blt_TreeNode root, node;
321 if (Blt_TreeGetToken(interp, "myTree", &token) != TCL_OK) {
324 root = Blt_TreeRootNode(token);
325 node = Blt_TreeCreateNode(token, root, "myNode", -1);
328 \fBBlt_TreeCreateNode\fR can trigger tree notify events.
329 You can be notified whenever a node is created by using the
330 \fBBlt_TreeCreateNotifyHandler\fR. A callback routine is registered
331 that will be automatically invoked whenever a new node is added
332 via \fBBlt_TreeCreateNode\fR to the tree.