1<TITLE>hierarchy - Create and manipulate a hierarchy widget</TITLE> 2<H1>hierarchy - Create and manipulate a hierarchy widget</H1> 3 4</pre><H2>SYNOPSIS</H2> 5<B>hierarchy<I> <I>pathName </I>?<I>options</I>? 6</pre><H2>INHERITANCE</H2> 7itk::Widget <- Labeledwidget <- Scrolledwidget <- Hierarchy 8</pre><H2>STANDARD OPTIONS</H2> 9<P> 10<table cellpadding=5> 11<td valign=top> 12<B>activeBackground</B><br> 13<B>cursor</B><br> 14<B>highlightThickness</B><br> 15</td> 16<td valign=top> 17<B>activeForeground</B><br> 18<B>disabledForeground</B><br> 19<B>relief</B><br> 20</td> 21<td valign=top> 22<B>background</B><br> 23<B>foreground</B><br> 24<B>selectBackground</B><br> 25</td> 26<td valign=top> 27<B>borderWidth</B><br> 28<B>highlightColor</B><br> 29<B>selectForeground</B><br> 30</td> 31</table> 32<P> 33See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/options.n.html"> "options" </A> manual entry for details on the standard options. 34</pre><H2>ASSOCIATED OPTIONS</H2> 35<P> 36<table cellpadding=5> 37<td valign=top> 38<B>activeRelief</B><br> 39</td> 40<td valign=top> 41<B>elementBorderWidth</B><br> 42</td> 43<td valign=top> 44<B>jump</B><br> 45</td> 46<td valign=top> 47<B>troughColor</B><br> 48</td> 49</table> 50<P> 51See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/scrollbar.n.html"> "scrollbar" </A> widget manual entry for details on the above 52associated options. 53<P> 54<table cellpadding=5> 55<td valign=top> 56<B>spacing1</B><br> 57</td> 58<td valign=top> 59<B>spacing2</B><br> 60</td> 61<td valign=top> 62<B>spacing3</B><br> 63</td> 64<td valign=top> 65<B>tabs</B><br> 66</td> 67</table> 68<P> 69See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/text.n.html"> "text" </A> widget manual entry for details on the above 70associated options. 71</pre><H2>INHERITED OPTIONS</H2> 72<P> 73<table cellpadding=5> 74<td valign=top> 75<B>labelBitmap</B><br> 76<B>labelPos</B><br> 77</td> 78<td valign=top> 79<B>labelFont</B><br> 80<B>labelText</B><br> 81</td> 82<td valign=top> 83<B>labelImage</B><br> 84<B>labelVariable</B><br> 85</td> 86<td valign=top> 87<B>labelMargin</B><br> 88</td> 89</table> 90<P> 91See the <A HREF="labeledwidget.n.html"> "labeledwidget" </A> class manual entry for details on the inherited options. 92</pre><H2>WIDGET-SPECIFIC OPTIONS</H2> 93<P> 94<pre> 95Name: <B>alwaysQuery</B> 96Class: <B>AlwaysQuery</B> 97Command-Line Switch: <B>-alwaysquery</B> 98</pre> 99<UL> 100Boolean flag which tells the hierarchy widget weather or not 101each refresh of the display should be via a new query using 102the command value of the -querycommand option or use the values 103previous found the last time the query was made. The default 104is no. 105</UL> 106<P> 107<pre> 108Name: <B>closedIcon</B> 109Class: <B>Icon</B> 110Command-Line Switch: <B>-closedicon</B> 111</pre> 112<UL> 113Specifies the name of an existing closed icon image to be used in the 114hierarchy before those nodes that are collapsed. Should one not be 115provided, then a folder icon will be generated, pixmap if possible, 116bitmap otherwise. 117</UL> 118<P> 119<pre> 120Name: <B>expanded</B> 121Class: <B>Expanded</B> 122Command-Line Switch: <B>-expanded</B> 123</pre> 124<UL> 125When true, the hierarchy will be completely expanded when it 126is first displayed. A fresh display can be triggered by 127resetting the -querycommand option. The default is false. 128</UL> 129<P> 130<pre> 131Name: <B>filter</B> 132Class: <B>Filter</B> 133Command-Line Switch: <B>-filter</B> 134</pre> 135<UL> 136When true only the branch nodes and selected items are displayed. 137This gives a compact view of important items. The default is false. 138</UL> 139<P> 140<pre> 141Name: <B>height</B> 142Class: <B>Height</B> 143Command-Line Switch: <B>-height</B> 144</pre> 145<UL> 146Specifies the height of the hierarchy as an entire unit. 147The value may be specified in any of the forms acceptable to 148<B>Tk_GetPixels</B>. Any additional space needed to display the other 149components such as labels, margins, and scrollbars force the hierarchy 150to be compressed. A value of zero along with the same value for 151the width causes the value given for the visibleitems option 152to be applied which administers geometry constraints in a different 153manner. The default height is zero. 154</UL> 155<P> 156<pre> 157Name: <B>iconCommand</B> 158Class: <B>Command</B> 159Command-Line Switch: <B>-iconcommand</B> 160</pre> 161<UL> 162Specifies a command to be executed upon user selection via mouse button 163one of any additional icons given in the values returned by the command 164associated with the -querycommand option. If this command contains "%n", 165it is replaced with the name of the node the icon belongs to. Should it 166contain "%i" then the icon name is substituted. 167</UL> 168<P> 169<pre> 170Name: <B>markBackground</B> 171Class: <B>Foreground</B> 172Command-Line Switch: <B>-markbackground</B> 173</pre> 174<UL> 175Specifies the background color to use when displaying marked nodes. 176</UL> 177<P> 178<pre> 179Name: <B>markForeground</B> 180Class: <B>Background</B> 181Command-Line Switch: <B>-markforeground</B> 182</pre> 183<UL> 184Specifies the foreground color to use when displaying marked nodes. 185</UL> 186<P> 187<pre> 188Name: <B>menuCursor</B> 189Class: <B>Cursor</B> 190Command-Line Switch: <B>-menucursor</B> 191</pre> 192<UL> 193Specifies the mouse cursor to be used for the item and background 194menus. The value may have any of the forms accept able to Tk_GetCursor. 195</UL> 196<P> 197<pre> 198Name: <B>nodeIcon</B> 199Class: <B>Icon</B> 200Command-Line Switch: <B>-nodeicon</B> 201</pre> 202<UL> 203Specifies the name of an existing node icon image to be used in the 204hierarchy before those nodes that are leafs. Should one not be provided, 205then a dog-eared page icon will be generated, pixmap if possible, bitmap 206otherwise. 207</UL> 208<P> 209<pre> 210Name: <B>openIcon</B> 211Class: <B>Icon</B> 212Command-Line Switch: <B>-openicon</B> 213</pre> 214<UL> 215Specifies the name of an existing open icon image to be used in the 216hierarchy before those nodes that are expanded. Should one not be provided, 217then an open folder icon will be generated, pixmap if possible, bitmap 218otherwise. 219</UL> 220<P> 221<pre> 222Name: <B>queryCommand</B> 223Class: <B>Command</B> 224Command-Line Switch: <B>-querycommand</B> 225</pre> 226<UL> 227Specifies the command executed to query the contents of each node. If this 228command contains "%n", it is replaced with the name of the desired 229node. In its simpilest form it should return the children of the 230given node as a list which will be depicted in the display. 231Since the names of the children are used as tags in the underlying 232text widget, each child must be unique in the hierarchy. Due to 233the unique requirement, the nodes shall be reffered to as uids 234or uid in the singular sense. The format of returned list is 235</UL> 236<UL> 237 {uid [uid ...]} 238</UL> 239<UL> 240 where uid is a unique id and primary key for the hierarchy entry 241</UL> 242<UL> 243Should the unique requirement pose a problem, the list returned 244can take on another more extended form which enables the 245association of text to be displayed with the uids. The uid must 246still be unique, but the text does not have to obey the unique 247rule. In addition, the format also allows the specification of 248additional tags to be used on the same entry in the hierarchy 249as the uid and additional icons to be displayed just before 250the node. The tags and icons are considered to be the property of 251the user in that the hierarchy widget will not depend on any of 252their values. The extended format is 253</UL> 254<UL> 255 {{uid [text [tags [icons]]]} {uid [text [tags [icons]]]} ...} 256</UL> 257<UL> 258 where uid is a unique id and primary key for the hierarchy entry 259 text is the text to be displayed for this uid 260 tags is a list of user tags to be applied to the entry 261 icons is a list of icons to be displayed in front of the text 262</UL> 263<UL> 264The hierarchy widget does a look ahead from each node to determine 265if the node has a children. This can be cost some performace with 266large hierarchies. User's can avoid this by providing a hint in 267the user tags. A tag of "leaf" or "branch" tells the hierarchy 268widget the information it needs to know thereby avoiding the look 269ahead operation. 270</UL> 271<P> 272<pre> 273Name: <B>hscrollMode</B> 274Class: <B>ScrollMode</B> 275Command-Line Switch: <B>-hscrollmode</B> 276</pre> 277<UL> 278Specifies the the display mode to be used for the horizontal 279scrollbar: <B>static, dynamic,</B> or <B>none</B>. In static mode, the 280scroll bar is displayed at all times. Dynamic mode displays the 281scroll bar as required, and none disables the scroll bar display. The 282default is static. 283</UL> 284<P> 285<pre> 286Name: <B>sbWidth</B> 287Class: <B>Width</B> 288Command-Line Switch: <B>-sbwidth</B> 289</pre> 290<UL> 291Specifies the width of the scrollbar in any of the forms 292acceptable to <B>Tk_GetPixels</B>. 293</UL> 294<P> 295<pre> 296Name: <B>scrollMargin</B> 297Class: <B>Margin</B> 298Command-Line Switch: <B>-scrollmargin</B> 299</pre> 300<UL> 301Specifies the distance between the text portion of the hierarchy and 302the scrollbars in any of the forms acceptable to <B>Tk_GetPixels</B>. The 303default is 3 pixels. 304</UL> 305<P> 306<pre> 307Name: <B>textBackground</B> 308Class: <B>Background</B> 309Command-Line Switch: <B>-textbackground</B> 310</pre> 311<UL> 312Specifies the background color for the text portion of the hierarchy in 313any of the forms acceptable to <B>Tk_GetColor</B>. 314</UL> 315<P> 316<pre> 317Name: <B>textFont</B> 318Class: <B>Font</B> 319Command-Line Switch: <B>-textfont</B> 320</pre> 321<UL> 322Specifies the font to be used in the text portion of the hierarchy. 323</UL> 324<P> 325<pre> 326Name: <B>visibleitems</B> 327Class: <B>VisibleItems</B> 328Command-Line Switch: <B>-visibleitems</B> 329</pre> 330<UL> 331Specifies the widthxheight in characters and lines for the hierarchy. 332This option is only administered if the width and height options 333are both set to zero, otherwise they take precedence. The default value 334is 80x24. With the visibleitems option engaged, geometry constraints 335are maintained only on the text portion of the hierarchy. The size of 336the other components such as 337labels, margins, and scroll bars, are additive and independent, 338effecting the overall size of the hierarchy. In contrast, 339should the width and height options have non zero values, they 340are applied to the hierarchy as a whole. The hierarchy 341is compressed or expanded to maintain the geometry constraints. 342</UL> 343<P> 344<pre> 345Name: <B>vscrollMode</B> 346Class: <B>ScrollMode</B> 347Command-Line Switch: <B>-vscrollmode</B> 348</pre> 349<UL> 350Specifies the the display mode to be used for the vertical 351scrollbar: <B>static, dynamic,</B> or <B>none</B>. In static mode, the 352scroll bar is displayed at all times. Dynamic mode displays the 353scroll bar as required, and none disables the scroll bar display. The 354default is static. 355</UL> 356<P> 357<pre> 358Name: <B>width</B> 359Class: <B>Width</B> 360Command-Line Switch: <B>-width</B> 361</pre> 362<UL> 363Specifies the width of the hierarchy as an entire unit. 364The value may be specified in any of the forms acceptable to 365<B>Tk_GetPixels</B>. Any additional space needed to display the other 366components such as labels, margins, and scrollbars force the text portion 367of the hierarchy 368to be compressed. A value of zero along with the same value for 369the height causes the value given for the visibleitems option 370to be applied which administers geometry constraints in a different 371manner. The default width is zero. 372</UL> 373<P> 374</pre><HR> 375 376</pre><H2>DESCRIPTION</H2> 377<P> 378The <B>hierarchy</B> command creates a hierarchical data view widget. 379It allows the graphical management of a a list of nodes that can be 380expanded or collapsed. Individual nodes can be highlighted. 381Clicking with the right mouse button on any item brings up a 382special item menu. Clicking on the background area brings up 383a different popup menu. Options exist to provide user control over 384the loading of the nodes and actions associated with node selection. 385Since the hierarchy is based on the scrolledtext widget, it includes 386options to control the method in which the scrollbars are displayed, 387i.e. statically or dynamically. Options also exist for adding a 388label to the hierarchy and controlling its position. 389 390</pre><H2>METHODS</H2> 391<P> 392The <B>hierarchy</B> command creates a new Tcl command whose 393name is <I>pathName</I>. This 394command may be used to invoke various 395operations on the widget. It has the following general form: 396<pre> 397<I>pathName option </I>?<I>arg arg ...</I>? 398</pre> 399<I>Option</I> and the <I>arg</I>s 400determine the exact behavior of the command. The following 401commands are possible for hierarchy widgets: 402</pre><H2>ASSOCIATED METHODS</H2> 403<P> 404<table cellpadding=5> 405<td valign=top> 406<B>bbox</B><br> 407<B>dlineinfo</B><br> 408<B>insert</B><br> 409<B>tag</B><br> 410</td> 411<td valign=top> 412<B>compare</B><br> 413<B>dump</B><br> 414<B>scan</B><br> 415<B>window</B><br> 416</td> 417<td valign=top> 418<B>debug</B><br> 419<B>get</B><br> 420<B>search</B><br> 421<B>xview</B><br> 422</td> 423<td valign=top> 424<B>delete</B><br> 425<B>index</B><br> 426<B>see</B><br> 427<B>yview</B><br> 428</td> 429</table> 430<P> 431See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/text.n.html"> "text" </A> manual entry for details on the standard methods. 432 433</pre><H2>WIDGET-SPECIFIC METHODS</H2> 434<DL> 435<DT> <I>pathName <B>cget</B> <I>option</I> 436</I></B> 437<DD> Returns the current value of the configuration option given 438by <I>option</I>. 439<I>Option</I> may have any of the values accepted by the <B>hierarchy</B> 440command. 441</DL> 442<DL> 443<DT> <I>pathName <B>clear</B> 444</I></B> 445<DD> Removes all items from the hierarchy display including all tags and icons. 446The display will remain empty until the -filter or -querycommand 447options are set. 448</DL> 449<DL> 450<DT> <I>pathName <B>collapse</B> <I>uid</I> 451</I></B> 452<DD> Collapses the hierarchy beneath the node with the specified unique id by 453one level. Since this can take a moment for large hierarchies, the 454cursor will be changed to a watch during the collapse. Also, if any 455of the nodes beneath the node being collapsed are selected, their 456status is changed to unselected. 457</DL> 458<DL> 459<DT> <I>pathName</I> <B>configure</B> ?<I>option</I>? ?<I>value option value ...</I>? 460</I></B> 461<DD> Query or modify the configuration options of the widget. 462If no <I>option</I> is specified, returns a list describing all of 463the available options for <I>pathName</I> (see <B>Tk_ConfigureInfo</B> for 464information on the format of this list). If <I>option</I> is specified 465with no <I>value</I>, then the command returns a list describing the 466one named option (this list will be identical to the corresponding 467sublist of the value returned if no <I>option</I> is specified). If 468one or more <I>option-value</I> pairs are specified, then the command 469modifies the given widget option(s) to have the given value(s); in 470this case the command returns an empty string. 471<I>Option</I> may have any of the values accepted by the <B>hierarchy</B> 472command. 473</DL> 474<DL> 475<DT> <I>pathName <B>current</B> 476</I></B> 477<DD> Returns the tags for the node that was most recently selected by the 478right mouse button when the item menu was posted. Usually used by the code 479in the item menu to figure out what item is being manipulated. 480</DL> 481<DL> 482<DT> <I>pathName <B>draw</B> ?<I>when</I>? 483</I></B> 484<DD> Performs a complete redraw of the entire hierarchy. When may be either -now 485or -eventually where the latter means the draw can be performed after idle. 486</DL> 487<DL> 488<DT> <I>pathName <B>expand</B> <I>uid</I> 489</I></B> 490<DD> Expands the hierarchy beneath the node with the specified unique id by 491one level. Since this can take a moment for large hierarchies, the cursor 492will be changed to a watch during the expansion. 493</DL> 494<DL> 495<DT> <I>pathName <B>mark</B> <I>option ?arg arg ...?</I> 496</I></B> 497<DD> This command is used to manipulate marks which is quite similar to 498selection, adding a secondary means of hilighting an item in the 499hierarchy. The exact behavior of the command depends on the 500<I>option</I> argument that follows the <B>mark</B> argument. The 501following forms of the command are currently supported: 502</DL> 503<UL> 504<DL> 505<DT> <I>pathName <B>mark clear</B> 506</I></B> 507<DD> Clears all the currently marked nodes in the hierarchy. 508</DL> 509<DL> 510<DT> <I>pathName <B>mark add <I>uid </I>?<I>uid uid ...</I>? 511</I></B> 512<DD> Marks the nodes with the specified uids in the hierarchy using the 513<B>-markbackground</B> and <B>-markforeground</B> options and without 514affecting the mark state of any other nodes that were already 515marked. 516</DL> 517<DL> 518<DT> <I>pathName <B>mark remove <I>uid </I>?<I>uid uid ...</I>? 519</I></B> 520<DD> Unmarks the nodes with the specified uids in the hierarchy without 521affecting the mark state of any other nodes that were already 522marked. 523</DL> 524<DL> 525<DT> <I>pathName <B>mark get</B> 526</I></B> 527<DD> Returns a list of the unique ids that are currently marked. 528</DL> 529</UL> 530<DL> 531<DT> <I>pathName <B>refresh</B> <I>uid</I> 532</I></B> 533<DD> Performs a redraw of a specific node that has the given uid. If the node 534is not currently visible or in other words already drawn on the text, 535then no action is taken. 536</DL> 537<DL> 538<DT> <I>pathName <B>prune</B> <I>uid</I> 539</I></B> 540<DD> Removes the node specified by the given uid from the hierarchy. Should 541the node have children, then all of its children will be removed as well. 542</DL> 543<DL> 544<DT> <I>pathName <B>selection</B> <I>option </I>?<I>arg arg ...</I>? 545</I></B> 546<DD> This command is used to manipulate the selection of nodes in the 547hierarchy. The exact behavior of the command depends on the 548<I>option</I> argument that follows the <B>selection</B> argument. The 549following forms of the command are currently supported: 550</DL> 551<UL> 552<DL> 553<DT> <I>pathName <B>selection clear</B> 554</I></B> 555<DD> Clears all the currently selected nodes in the hierarchy. 556</DL> 557<DL> 558<DT> <I>pathName <B>selection add <I>uid </I>?<I>uid uid ...</I>? 559</I></B> 560<DD> Selects the nodes with the specified uids in the hierarchy using the 561<B>-selectionbackground</B> and <B>-selectionforeground</B> options and without 562affecting the selection state of any other nodes that were already 563selected. 564</DL> 565<DL> 566<DT> <I>pathName <B>selection remove <I>uid </I>?<I>uid uid ...</I>? 567</I></B> 568<DD> Deselects the nodes with the specified uids in the hierarchy without 569affecting the selection state of any other nodes that were already 570selected. 571</DL> 572<DL> 573<DT> <I>pathName <B>selection get</B> 574</I></B> 575<DD> Returns a list of the unique ids that are currently selected. 576</DL> 577</UL> 578A nodes selection status is also dependent on it being visible. If a 579node is selected and its parent is then collapsed making the selected 580node not visible, then its selection status is changed to unselected. 581<DL> 582<DT> <I>pathName <B>toggle</B> <I>uid</I> 583</I></B> 584<DD> Toggles the hierarchy beneath the node with the specified unique id. If 585the hierarchy is currently expanded, then it is collapsed, and vice-versa. 586 587</DL> 588</pre><H2>COMPONENTS</H2> 589<P> 590<pre> 591Name: <B>list</B> 592Class: <B>Text</B> 593</pre> 594<UL> 595The list component is the text widget in which the hierarchy is displayed. 596See the <A HREF="http://www.sco.com/Technology/tcl/man/tk_man/text.n.html"> "text" </A> widget manual entry for details on the text component item. 597</UL> 598<P> 599<pre> 600Name: <B>bgMenu</B> 601Class: <B>Menu</B> 602</pre> 603<UL> 604The bgMenu component is the popup menu which is displayed upon pressing 605the right mouse button in the background, i.e. not over a specific node. Menu 606items can be added along with their commands via the component command. 607See the "menu" widget manual entry for details on the bgMenu component item. 608</UL> 609<P> 610<pre> 611Name: <B>horizsb</B> 612Class: <B>Scrollbar</B> 613</pre> 614<UL> 615The horizsb component is the horizontal scroll bar. See the "scrollbar" 616widget manual entry for details on the horizsb component item. 617</UL> 618<P> 619<pre> 620Name: <B>itemMenu</B> 621Class: <B>Menu</B> 622</pre> 623<UL> 624The itemMenu component is the popup menu which is displayed upon selection 625of a hierarchy node with the right mouse button. Menu items can be 626added along with their commands via the component command. See the "menu" 627widget manual entry for details on the itemMenu component item. 628</UL> 629<P> 630<pre> 631Name: <B>vertsb</B> 632Class: <B>Scrollbar</B> 633</pre> 634<UL> 635The vertsb component is the vertical scroll bar. See the "scrollbar" widget 636manual entry for details on the vertsb component item. 637</UL> 638</table> 639 640</pre><H2>EXAMPLE</H2> 641<pre> 642proc get_files {file} { 643 global env 644 645 if {$file == ""} { 646 set dir $env(HOME) 647 } else { 648 set dir $file 649 } 650 651 if {[catch {cd $dir}] != 0} { 652 return "" 653 } 654 655 set rlist "" 656 657 foreach file [lsort [glob -nocomplain *]] { 658 lappend rlist [list [file join $dir $file] $file] 659 } 660 661 return $rlist 662} 663 664hierarchy .h -querycommand "get_files %n" -visibleitems 30x15 \ 665 -labeltext $env(HOME) 666pack .h -side left -expand yes -fill both 667</pre> 668</pre><H2>AUTHORS</H2> 669Mark L. Ulferts 670<P> 671Michael J. McLennan 672</pre><H2>KEYWORDS</H2> 673hierarchy, text, widget 674