4 Hierarchical Listbox
4.1 TixHList -- The Tix Hierarchical Listbox Widget
   TixHList is the Tix Hierarchical Listbox Widget. You can use it
  to display any data that have a hierarchical structure. For example,
  the HList widget in figure 
hlist.tex.html#4-14-1  displays a Unix file
  system directory tree; the HList widget in figure 
hlist.tex.html#4-14-1   displays the corporate hierarchy of a hypothetical company. As shown
  in these two figures, the entries inside the TixHList widget are
  indented can be optionally connected by branch lines according to
  their positions in the hierarchy.
 
      
    
Directory Tree Display
      
    
A Corporate Hierarchy
 
(Figure 4-1) Examples of the TixHList Widget
4.1.1 Creating a Hierarchical List
  A TixHList widget can be created by the command   tixHList
. However, most likely, you would want to create a TixHList
  with scrollbars attached. Therefore, usually you will use the 
  tixScrolledHList
 command to create a scrolled hierarchical listbox
  (line 1 in program 
hlist.tex.html#4-24-2 ). The  tixScrolledHList  command is very similar to the 
 TixScrolledListBox command we
  saw in section 
container.tex.html#2.3.12.3.1 . It creates a TixHList subwidget
  of the name 
 hlist and attaches two scrollbars to it.
  As shown in the first five lines in program hlist.tex.html#4-24-2 , we
  create a scrolled TixHList widget, using the 
 -options switch
  (see section 
intro.tex.html#1.3.51.3.5 ) to set several options for the   hlist
 subwidget (we'll talk about these options shortly). Then, we
  can access the HList subwidget widget using the 
 subwidget
  hlist
 method (line 7 in program hlist.tex.html#4-24-2 ).
tixScrolledHList .sh -options {
    hlist.itemType text
    hlist.drawBranch false
    hlist.indent     8
}
pack .sh -expand yes -fill both
set hlist [.sh subwidget hlist]
$hlist add foo         -text "foo"
$hlist add foo.bar     -text "foo's 1st son"
$hlist add foo.bor     -text "foo's 2nd son"
$hlist add foo.bar.bao -text "foo's 1st son's 1st son"
$hlist add foo.bar.kao -text "foo's 1st son's 2nd son"
$hlist add dor         -text "dor, who has no son"
(Figure 4-2) Creating Entries in a HList Widget
(Figure 4-3) Output of Program hlist.tex.html#4-24-2 
4.1.2 Creating Entries in a HList Widget
  Each entry in an HList widget has a unique name, called its   entry-path
, which determines each entry's position in the HList
  widget. The entry-paths of the HList entries are very similar to the
  pathnames of Unix files. Each entry-path is a list of string names
  separated by a 
 separator character. By default, the separator
  character is the period character (
 .), but it can be
  configured using the 
 -separator option of the HList widget.
  In program hlist.tex.html#4-34-3 , we add several new entries  foo,
  
 foo.bar,  foo.bor,  foo.bar.bao, .. etc, into the
  HList widget using the 
 add method. The relationship between
  the entries is signified by their names, in a way similar to how
  Unix denotes directories and subdirectories. For example, 
 foo  is the 
 parent of  foo.bar and  foo.bor;   foo.bar
 is the parent of  foo.bar.bao, and so on. As far as
  the terminology goes, we also say that 
 foo.bar a  child  of 
 foo;  foo is an  ancestor of  foo.bar.bao  and 
 foo.bar.bao is a  descendant of  foo.
  The output of program hlist.tex.html#4-24-2  is shown in figure
  
hlist.tex.html#4-34-3 . As we can see, the entries are displayed under
  their parents with the amount of indentation control by the 
  -indent
 option of the HList widget:  foo.bar.bao and   foo.bar.kao
 are display under  foo.bar, which is in turn
  displayed under 
 foo.
  Entries with no parents, for example,  foo and  dor in
  program 
hlist.tex.html#4-24-2 , are called  top-level
  entries
. Top-level entries are usually entries with no immediate
  superiors in a hierarchical. For example, the owner of a company, the
  principle of a school or the root directory of a Unix file
  system. Toplevel entries are displayed with no indentation.
  As evident from program hlist.tex.html#4-24-2 , all entries who
  entry-path does not contain a separator character are top-level
  entries. The only exception is the separator character itself is
  also a toplevel entry. This makes it easy to display Unix file and
  directory names inside the HList widget, as shown in program
  
hlist.tex.html#4-44-4 .
set folder [tix getimage folder]
tixScrolledHList .sh -options {
    hlist.separator     /
    hlist.itemType      imagetext
    hlist.drawBranch    true
    hlist.indent        14
    hlist.wideSelection false
}
pack .sh -expand yes -fill both
set hlist [.sh subwidget hlist]
foreach directory {/ /usr /usr/bin /usr/local /etc /etc/rc.d} {
    $hlist add $directory -image $folder -text $directory
}
(Figure 4-4) Displaying Directories in a HList Widget
(Figure 4-5) Output of Program hlist.tex.html#4-44-4 
  Each entry is associated with a display item (see section
 
tlist.tex.html#3.23.2  about display items). We can use the  -itemtype option of the HList widget to specify the default type of display
 item to be created by the the 
 add method, as shown in program
 
hlist.tex.html#4-24-2  and hlist.tex.html#4-44-4 . Alternatively, we can
 also specify the type of display item using the 
 -itemtype option for the 
 add method.
4.1.3 Controlling the Layout of the Entries
  There are two options to control the layout of the entries: the   -showbranch
 option specifies whether branch lines should be drawn
  between parent entries and their children. The 
 -indent option
  controls the amount of relative indentation between parent and child
  entries. Notice the 
 -drawbranch option is turned on in figure
  
hlist.tex.html#4-54-5  but turned off in figure
  
hlist.tex.html#4-34-3 . Usually, you need to set a bigger indentation
  when the branches are shown --- we used an indentation of 14 pixels
  in 
hlist.tex.html#4-54-5  compared to 8 pixels in hlist.tex.html#4-34-3 .
4.1.4 Handling the Selection and User Event
  The handling of the selection and user events for the HList widget
  is very similar to the TList widget (see section
  
tlist.tex.html#3.3.53.3.5 ), except that for the HList widget all the
  operations are based on entry-paths, not list indices. The methods
  
 info selection,  selection set and  selection clear  can be used to query, set or clear the selection; the option 
  -selectmode
 controls how many entries can be selected at a time;
  the options 
 -browsecmd and  -command can be used to
  specify a command to be called to handle user events.
  There is one more option worth mentioning: the  -wideselection  option. When set to 
 true, the selection highlight will be
  drawn across the whole HList widget (see figure
  
hlist.tex.html#4-34-3 ). When set to false, selection highlight will be
  drawn as wide as the selected entry (see figure
  
hlist.tex.html#4-54-5 ). Normally, you would set  -wideselection  to 
 false when you use  imagetext items inside (as we did
  in program 
hlist.tex.html#4-44-4 ).
  
4.2 Creating Collapsible Tree Structures with TixTree
  The TixTree widget is based on the TixScrolledHList widget; you can
  use it to create a collapsible hierarchical structure so that the
  user can conveniently navigate through a large number of list
  entries. As shown in figure 
hlist.tex.html#4-74-7 , the TixTree puts
  the little ``
 +'' and `` -'' icons next to the branches of
  an HList entry that has descendants. These two icons are knows as
  the open and close icons, respectively. When the user presses the
  open icon next to an entry, its immediate children of an entry will
  be displayed. Conversely, when the user presses the close icon, the
  entry's children will become hidden.
  Program hlist.tex.html#4-64-6  shows how to create a collapsible
  tree. We first create a TixTree widget. Then we add the entries in
  your hierarchical structure into its 
 hlist subwidget using the
  add method of this subwidget. When we are finished with adding the
  entries, we just call the 
 autosetmode method of the TixTree
  widget, which will automatically adds the open and close icons next
  to the entries who have children.
set folder [tix getimage folder]
tixTree .tree -command Command -options {
    hlist.separator  /
    hlist.itemType   imagetext
    hlist.drawBranch true
    hlist.indent     18
}
pack .tree -expand yes -fill both
set hlist [.tree subwidget hlist]
foreach directory {/ /usr /usr/bin /usr/local /etc /etc/rc.d} {
    $hlist add $directory -image $folder -text $directory
}
.tree autosetmode
proc Command {entry} {
    puts "you have selected $entry"
}
(Figure 4-6) Creating a Collapsible Hierarchy
(Figure 4-7) Output of Program hlist.tex.html#4-64-6 
  Note that in program hlist.tex.html#4-64-6  we use the  -command  option of the TixTree widget, not the 
 -command option of its   hlist
 subwidget. This is because the TixTree actually used the   -command
 option of its  hlist subwidget to process some
  low-level events. In general, if both a mega-widget and its
  subwidget have the options of the same name, you would always use
  the option that belongs to the mega-widget.
