NAME

       hiertable  - Create and manipulate hierarchical table wid­
       gets
_________________________________________________________________


SYNOPSIS

       hiertable pathName ?options?


DESCRIPTION

       The  hiertable  widget  displays  a  scrollable  tree   of
       entries, one entry per line.  Each entry has a text label,
       an icon, and may have children (sub-entries).  A button on
       the  left  side of the entry controls whether its children
       are displayed.

       Entries may have data fields associated with  them.   Data
       fields are displayed (as text or Tk image) in columns that
       can run vertically on either side the entry.  Each  column
       can  have  its  own  color,  font,  etc.   Any data field,
       including the entry's label, can be edited in-place.

       Single or multiple entries can  be  selected.   Individual
       entries  can  be  hidden.   There is also a find operation
       that can apply operations to all entries that match  user-
       specified criteria.


INTRODUCTION

       The  hiertable  widget represents an hierarchical table of
       data.  Each row entry is a node in a general-ordered tree.
       Entries  are drawn with both a text label and an icon.  An
       entry may have sub-entries or children.  Each sub-entry in
       turn  may  have children.  Children are revealed or hidden
       by opening or closing the entry.


ENTRIES

       Entries are uniquely identified  by  a  serial  number  or
       index.   Until  an  entry  is deleted, its index is valid,
       even if the entry is moved to another position within  the
       tree.   Note that an index doesn't indicate anything about
       the entry's relative position or order in the tree.

       If an entry has children, it is drawn with a button on its
       left  side.   Clicking  the  mouse on this button opens or
       closes the sub-hierarchy.  When  an  entry  is  open,  its
       children  are exposed.  When it is closed, they are hidden
       again.  The button is normally a + or - symbol  (ala  Win­
       dows  Explorer),  but  can  be  replaced with a pair of Tk
       images (open and closed images).

       You can bind Tcl commands to be invoked when events  occur
       on  entries  (much like Tk canvas items).  You can bind an
       entry using its  index  or  its  bindtags.   Bindtags  are

       entries.  There is a built-in tag  all  that  all  entries
       automatically have.

       An  entry  can have an arbitrary number of data fields.  A
       data field is simply a name-value pair, representing  some
       bit  of data in the entry.  The field names and their val­
       ues are strings.  Entries  are  not  required  to  contain
       fields  found  in  other entries.  For example, each entry
       could have its own unique set of field names.


COLUMNS

       Data fields can be displayed in the widget in columns.   A
       column  is  associated  with  a specific data field.  Each
       entry's value for that field is drawn in  a  column  along
       side  the hierarchy.  Any entry that doesn't have the spe­
       cific field is left blank.  The widget has a built-in col­
       umn, named after the widget, that holds the tree.

       You can control the appearance and location of any column.
       The width of a column is determined by the widest value in
       the  column.   Users can override the width of a column by
       grabbing a side of the column and dragging it. Columns can
       be hidden or reordered.


LAZY INSERTION/DELETION OF ENTRIES

       In  the  case  of a file browser, it doesn't make sense to
       load the contents of the entire filesystem.  There can  be
       tens  of  thousands of entries and you really need to view
       only a small subset of those.  The hiertable lets  you  do
       lazy  insertion  and deletion of entries.  This means that
       you insert entries for a particular  directory  only  when
       necessary.

       The  hiertable can invoke Tcl procedures whenever an entry
       is opened and/or closed.   This can allow  entries  to  be
       inserted only for that directory when needed.  At the same
       time, when  an  entry  is  closed,  its  children  can  be
       removed, freeing memory and resources.


TREE DATA OBJECT

       Data  is  not  stored  directly  in  the hiertable widget.
       Instead it uses an external tree data object to the repre­
       sent   the  hierarchy  (see  the  tree  manual  entry  for
       details).  You  can  create  trees  and  then  attach  the
       hiertable to them using the -tree configuration option.

       If  no tree is specified, the widget automatically creates
       an new tree (the tree's name is  the  widget's  pathname).
       The tree will automatically contain one entry for the root
       node.  When the widget is destroyed the tree is  released.

       While entries and their data can be added or deleted using
       various widget operations, tree  data  objects  themselves

       through one of these interfaces, the  widget  is  notified
       and will automatically redraw itself.


EXAMPLE

       The hiertable command creates a new hiertable widget.

              hiertable .h -bg white

       A new Tcl command .h is also created.  This command can be
       used to query and modify the hiertable.  For  example,  to
       change  the  background color of the table to "green", you
       use the new command and the widget's configure  operation.

              # Change the background color.
              .h configure -background "green"

       By  default, the hiertable will automatically create a new
       tree object to contain the data.  The name of the new tree
       is the pathname of the widget.  Above, the new tree object
       name is ".h".  But you can use the -tree option to specify
       the name of another tree.

              # View the tree "myTree".
              .h configure -tree "myTree"

       When a new tree is created, it contains only a root entry.
       The entry is automatically opened.  The index of the  root
       entry  is  always 0 (you can use also use the index root).
       The insert operation lets  you  insert  one  or  more  new
       entries  into  the tree.  The last argument is the entry's
       pathname.

              # Create a new entry named "myEntry"
              set index [.h insert end "myEntry"]

       This appends a new entry named "myEntry".  It  will  posi­
       tioned  as  the  last child of the root of the tree (using
       the position "end").  You can supply another  position  to
       order the entry within its siblings.

              # Prepend "fred".
              set index [.h insert 0 "fred"]

       Entry  names  do  not  need to be unique.  By default, the
       entry's label is its name.  To  supply  a  different  text
       label, add the -label option.

              # Create a new entry named "fred"
              set index [.h insert end "fred" -label "Fred Flintstone"]

       The  insert  operation  returns the index of the new node.
       You can also use the index operation to get this  informa­
       tion.

              .h index "fred"

       To  insert an entry somewhere other than root, use the -at
       switch.  It takes the index of the  entry  where  the  new
       child will be added.

              # Create a new entry "barney" in "fred".
              .h insert -at $index end "barney"

       A  pathname  describes the path to an entry in the hierar­
       chy.  It's a list of entry names that compose the path  in
       the  tree.  Therefore, you can also add "barney" to "fred"
       as follows.

              # Create a new sub-entry of "fred"
              .h insert end "fred barney"

       Every name in the list  is  ancestor  of  the  next.   All
       ancestors  must  already  exist.  That means that an entry
       "fred" is an ancestor of "barney" and must already  exist.
       But  you  can  use the -autocreate configuration option to
       force the creation of ancestor nodes.

              # Force the creation of ancestors.
              .h configure -autocreate yes
              .h insert end "fred barney wilma betty"

       Sometimes the pathname is already separated by a character
       sequence  rather  than formed as a list.  A file name is a
       good example of this.  You can use the  -separator  option
       to  specify  a separator string to split the path into its
       components.  Each pathname inserted is automatically split
       using the separator string as a separator.  Multiple sepa­
       rators are treated as one.

              .h configure -separator /
              .h insert end "/usr/local/tcl/bin"

       If the path is prefixed by extraneous characters, you  can
       automatically  trim  it  off  using  the -trim option.  It
       removed the string from the path before it is parsed.

              .h configure -trim C:/windows -separator /
              .h insert end "C:/window/system"

       You can insert more than one entry  at  a  time  with  the
       insert  operation.   This  can be much faster than looping
       over a list of names.

              # The slow way
              foreach f [glob $dir/*] {
                  .h insert end $f
              }

              eval .h insert end [glob $dir/*]

       In this case, the insert operation will return a  list  of
       indices of the new entries.

       You  can  delete  entries  with  the delete operation.  It
       takes one or more indices as its argument. It deletes  the
       entry and all its children.

              .h delete $index

       Entries  have several configuration options.  They control
       the appearance of the entry's icon  and  label.   We  have
       already  seen the -label option that sets the entry's text
       label.   The entry configure operation  lets  you  set  or
       modify an entry's configuration options.

              .h entry configure $index -color red -font fixed

       You  can  hide  an  entry and its children using the -hide
       option.

              .h entry configure $index -hide yes

       More that one  entry  can  be  configured  at  once.   All
       entries specified are configured with the same options.

              .h entry configure $i1 $i2 $i3 $i4 -color brown

       An  icon  is  displayed  for  each entry.  It's a Tk image
       drawn to the left of the label.  You can set the icon with
       the  entry's  -icons option.  It takes a list of two image
       names: one to represent the open entry, another when it is
       closed.

              set im1 [image create photo -file openfolder.gif]
              set im2 [image create photo -file closefolder.gif]
              .h entry configure $index -icons "$im1 $im2"

       If  -icons  is  set to the empty string, no icons are dis­
       play.

       If an entry has children, a button  is  displayed  to  the
       left  of the icon. Clicking the mouse on this button opens
       or closes the sub-hierarchy.  The button is normally  a  +
       or  -  symbol,  but can be configured in a variety of ways
       using the button configure operation.  For example, the  +
       and - symbols can be replaced with Tk images.

              set im1 [image create photo -file closefolder.gif]
              set im2 [image create photo -file downarrow.gif]
              .h button configure $index -images "$im1 $im2" \
                  -openrelief raised -closerelief raised

       Data fields are name-value pairs.  Both the value and name
       are  strings.   The entry's -data option lets you set data
       fields.

              .h entry configure $index -data {mode 0666 group users}

       The -data takes a list of name-value pairs.

       You can display  these  data  fields  as  columns  in  the
       hiertable  widget.   You  can create and configure columns
       with the column operation.  For example, to add a new col­
       umn  to  the widget, use the column insert operation.  The
       last argument is the name of the data field that you  want
       to display.

              .h column insert end "mode"

       The  column  title  is displayed at the top of the column.
       By default, it's is the field name.  You can override this
       using the column's -text option.

              .h column insert end "mode" -text "File Permissions"

       Columns  have  several  configuration options.  The column
       configure  operation  lets  you  query  or  modify  column
       options.

              .h column configure "mode" -justify left

       The  -justify option says how the data is justified within
       in the column.  The -hide  option  indicates  whether  the
       column is displayed.

              .h column configure "mode" -hide yes

       Entries   can  be  selected  by  clicking  on  the  mouse.
       Selected entries are drawn using the colors  specified  by
       the  -selectforeground and -selectbackground configuration
       options.  The selection itself is managed by the selection
       operation.

              # Clear all selections
              .h selection clear 0 end
              # Select the root node
              .h selection set 0

       The  curselection  operation returns a list of indices for
       all selected entries.

              set indices [.h curselection]

       You can use the get operation to convert  the  indices  to
       their pathnames.


       If  an  hiertable  is  exporting  its selection (using the
       -exportselection option), then it will observe  the  stan­
       dard  X11 protocols for handling the selection.  Hiertable
       selections are available as type STRING; the value of  the
       selection  will  be the pathnames of the selected entries,
       separated by newlines.

       The hiertable supports two modes of selection: single  and
       multiple.   In  single  select mode, only one entry can be
       selected at a time, while multiple select mode allows sev­
       eral  entries to be selected.  The mode is set by the wid­
       get's -selectmode option.

              .h configure -selectmode "multiple"

       You can be notified when  the  list  of  selected  entries
       changes.  The widget's -selectcommand specifies a Tcl pro­
       cedure that is called whenever the selection changes.

              proc SelectNotify { widget } {
                 set indices [$widget curselection]
              }
              .h configure -selectcommand "SelectNotify .h"

       The widget supports the standard Tk scrolling and scanning
       operations.   The  hiertable  can be both horizontally and
       vertically. You can attach scrollbars to the hiertable the
       same way as the listbox or canvas widgets.

              scrollbar .xbar -orient horizontal -command ".h xview"
              scrollbar .ybar -orient vertical -command ".h yview"
              .h configure -xscrollcommand ".xbar set" \
                  -yscrollcommand ".ybar set"

       There  are  three  different  modes of scrolling: listbox,
       canvas, and hierbox.  In listbox mode, the last entry  can
       always  be  scrolled to the top of the widget.  In hierbox
       mode, the last entry is always drawn at the bottom of  the
       widget.   The  scroll mode is set by the widget's -select­
       mode option.

              .h configure -scrollmode "listbox"

       Entries can be programmatically opened or closed using the
       open and close operations respectively.

              .h open $index
              .h close $index

       When  an entry is opened, a Tcl procedure can be automati­
       cally invoked.  The  -opencommand  option  specifies  this
       procedure.   This  procedure  can lazily insert entries as


              proc AddEntries { dir } {
                 eval .h insert end [glob -nocomplain $dir/*]
              }
              .h configure -opencommand "AddEntries %P"

       Now when an entry is opened, the procedure  AddEntries  is
       called and adds children to the entry.  Before the command
       is invoked, special "%" substitutions (like bind) are per­
       formed.  Above,  %P  is  translated to the pathname of the
       entry.

       The same feature exists when  an  entry  is  closed.   The
       -closecommand option specifies the procedure.

              proc DeleteEntries { index } {
                 .h entry delete $index 0 end
              }
              .h configure -closecommand "DeleteEntries %#"

       When  an  entry  is closed, the procedure DeleteEntries is
       called and deletes the entry's children  using  the  entry
       delete operation (%# is the index of entry).


SYNTAX

       The  hiertable  command creates a new window (given by the
       pathName argument) and makes it into an hiertable  widget.

              hiertable pathName ?option value?...

       Additional  options,  described above, may be specified on
       the command line or in the option  database  to  configure
       aspects  of  the hiertable such as its colors, font, text,
       and relief.  The hiertable command  returns  its  pathName
       argument.  At the time this command is invoked, there must
       not exist a window named pathName, but  pathName's  parent
       must exist.


HIERTABLE INDICES

       Each  entry  in  the  hiertable  widget is identified by a
       unique serial number or index.  Many of the operations  in
       the  hiertable  widget  take  one or more indices as argu­
       ments.  You can use either the entry's  serial  number  or
       one of several special non-numeric indices shown below.

       number         Identifies  the  entry.  The number doesn't
                      indicate the location or position an entry.
                      For  example, you can't determine the order
                      of two entries  from  their  node  numbers.
                      Node 0 is always the root of the hierarchy.

       active         The entry where the mouse pointer  is  cur­
                      rently  located.   When an entry is active,

                      -activeicon  option).   The active index is
                      changed automatically by moving  the  mouse
                      pointer  over another entry or by using the
                      entry activate operation. Note  that  there
                      can be only one active entry at a time.

       anchor         The entry representing the fixed end of the
                      current selection.  The anchor  is  set  by
                      the selection anchor operation.

       current        The  entry  where the mouse pointer is cur­
                      rently located.  But  unlike  active,  this
                      index   changes   while  the  selection  is
                      dragged.  It is used to determine the  cur­
                      rent entry during button drags.

       down           The next open entry from the current focus.
                      The down of the  last  open  entry  is  the
                      same.

       end            The  last open entry (in depth-first order)
                      on the tree.

       focus          The entry that currently has  focus.   When
                      an entry has focus, it receives key events.
                      To indicate focus, the entry is drawn  with
                      a  dotted  line  around its label.  You can
                      change the focus using the focus operation.

       last           The last open entry from the current focus.
                      But unlike up, when the focus is  at  root,
                      last wraps around to the last open entry in
                      the tree.

       mark           The entry representing the non-fixed end of
                      the  current selection.  The mark is set by
                      the selection mark operation.

       next           The next open entry from the current focus.
                      But  unlike down, when the focus is on last
                      open entry, next wraps around to  the  root
                      entry.

       nextsibling    The  next  sibling  from the entry with the
                      current focus.  If the entry is already the
                      last sibling then it is the nextsibling.

       parent         The  parent  of  the entry with the current
                      focus. The parent of the root is  also  the
                      root.

       prevsibling    The  previous  sibling  from the entry with
                      the current focus.  If the entry is already

                      ling.

       root           The root entry. You can also use index 0 to
                      indicate the root.

       up             The  last open entry (in depth-first order)
                      from the current focus. The up of the  root
                      entry (i.e. the root has focus) is also the
                      root.

       view.top       First entry that's current visible  in  the
                      widget.

       view.bottom    Last  entry  that's  current visible in the
                      widget.

       path           Absolute path  of  an  entry.   Path  names
                      refer  to  the  node  name, not their entry
                      labels. Paths don't have to  start  with  a
                      separator (see the -separator configuration
                      option), but component names must be  sepa­
                      rated by the designated separator.

       @x,y           Indicates  the  entry that covers the point
                      in the hiertable window specified by x  and
                      y (in pixel coordinates).  If no entry cov­
                      ers that point, then the closest  entry  to
                      that point is used.


HIERTABLE OPERATIONS

       The  hiertable  operations  have the invoked by specifying
       the widget's pathname, the operation,  and  any  arguments
       that pertain to that operation.  The general form is:

       pathName operation ?arg arg ...?

       Operation and the args determine the exact behavior of the
       command.   The  following  operation  are  available   for
       hiertable widgets:

       pathName bbox ?-screen? index...
              Returns  a list of 4 numbers, representing a bound­
              ing box of around the specified entries. Each entry
              is  given  an index.  If the -screen flag is given,
              then the x-y coordinates of the  bounding  box  are
              returned as screen coordinates, not virtual coordi­
              nates. Virtual coordinates start from  0  from  the
              root entry.  The returned list contains the follow­
              ing values.

               x           X-coordinate of the upper-left  corner
                           of the bounding box.

                           of the bounding box.

               width       Width of the bounding box.

               height      Height of the bounding box.

       pathName bind tagName ?sequence command?
              Associates command with tagName such that  whenever
              the  event sequence given by sequence occurs for an
              entry with this tag, command will be invoked.   The
              syntax  is  similar to the bind command except that
              it operates on hiertable entries, rather than  wid­
              gets.  See  the  bind  manual  entry  for  complete
              details on sequence and the substitutions performed
              on command before invoking it.

              If  all  arguments are specified then a new binding
              is created, replacing any existing binding for  the
              same  sequence and tagName.  If the first character
              of command is + then command augments  an  existing
              binding  rather  than  replacing it.  If no command
              argument is provided  then  the  command  currently
              associated with tagName and sequence (it's an error
              occurs if there's no such binding) is returned.  If
              both  command  and sequence are missing then a list
              of all the event sequences for which bindings  have
              been defined for tagName.

       pathName button operation ?args?
              See the BUTTON OPERATIONS section below.

       pathName cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values   accepted   by   the   configure  operation
              described below.

       pathName close ?-recurse? index...
              Closes the entry specified by index.  In  addition,
              if  a Tcl script was specified by the -closecommand
              option, it is invoked.  If  the  entry  is  already
              closed,   this  command  has  no  effect.   If  the
              -recurse flag  is  present,  each  child  entry  is
              recursively closed.

       pathName column operation ?args?
              See the COLUMN OPERATIONS section below.

       pathName configure ?option? ?value option value ...?
              Query  or  modify  the configuration options of the
              widget.  If no option is specified, returns a  list
              describing  all  of the available options for path­
              Name (see Tk_ConfigureInfo for information  on  the

              no value, then the command returns a list  describ­
              ing the one named option (this list will be identi­
              cal to  the  corresponding  sublist  of  the  value
              returned  if  no  option  is specified).  If one or
              more option-value pairs  are  specified,  then  the
              command modifies the given widget option(s) to have
              the given  value(s);   in  this  case  the  command
              returns  an  empty  string.   Option  and value are
              described below:

              -activebackground color
                     Sets  the  background   color   for   active
                     entries.   An entry is active when the mouse
                     passes over it or using the activate  opera­
                     tion.

              -activeforeground color
                     Sets   the   foreground   color  for  active
                     entries.  An entry is active when the  mouse
                     passes  over it or using the activate opera­
                     tion.

              -activeicons images
                     Specifies images  to  be  displayed  for  an
                     entry's  icon when it is active. Images is a
                     list of two Tk images: the  first  image  is
                     displayed when the entry is open, the second
                     when it is closed.

              -autocreate boolean
                     Normally it is an error to insert  an  entry
                     whose  ancestors  do  not already exist.  If
                     boolean is true, it indicates  to  automati­
                     cally  create missing ancestor entries.  The
                     default is no.

              -allowduplicates boolean
                     Normally it is an error to insert  an  entry
                     with the same pathname as another entry.  If
                     boolean is true, it indicates that duplicate
                     entries  should  be allowed.  The default is
                     no.

              -background color
                     Sets the  background  color  the  hiertable.
                     The default is white.

              -borderwidth pixels
                     Sets  the width of the 3-D border around the
                     outside edge of  the  widget.   The  -relief
                     option  determines  if  the  border is to be
                     drawn.  The default is 2.

                     Specifies a Tcl script to be invoked when an
                     entry  is  closed.   Individual  entries may
                     override this with their  own  -closecommand
                     option.  The default is "".  Percent substi­
                     tutions are performed on string before it is
                     executed.   The  following substitutions are
                     valid:

                     %W   The pathname of the widget.

                     %p   The name of the entry.

                     %P   The full pathname of the entry.

                     %#   The index of the node.

                     %%   Translates to a single percent.

              -cursor cursor
                     Specifies the widget's cursor.  The  default
                     cursor is "".

              -dashes number
                     Sets  the  dash  style of the horizontal and
                     vertical  lines  drawn  connecting  entries.
                     Number  is the length in pixels which repre­
                     sents the lengths of the  dashes  and  gaps.
                     If  number  is 0, solid lines will be drawn.
                     The default is 1.

              -exportselection boolean
                     Indicates if the selection is exported.   If
                     an hiertable is exporting its selection then
                     it will observe the standard  X11  protocols
                     for  handling the selection.  Selections are
                     available as type STRING; the value  of  the
                     selection  will  be the text of the selected
                     entries,  with   newlines   separating   the
                     entries.  The default is no.

              -flat boolean
                     Indicates  whether  to display the tree as a
                     flattened list.  If boolean  is  true,  then
                     the  hierarchy  will be a list of full paths
                     for  the  entries.   This  option  also  has
                     affect  on sorting.  See the SORT OPERATIONS
                     section for more information.   The  default
                     is no.

              -focusdashes dashList
                     Sets the dash style of the outline rectangle
                     drawn around the focused entry's label. Num­
                     ber is the length in pixels which represents

                     ber  is  0,  a solid line will be drawn. The
                     default is 1.

              -focusforeground color
                     Sets the color to draw the focus  rectangle.
                     This  is  the  dotted rectangle drawn around
                     the entry currently  accepting  key  events.
                     The default is black.

              -font fontName
                     Specifies  the font to use for entry labels.
                     Individual entries may  override  this  with
                     their  own  -font  option.   The  default is
                     *-Helvetica-Bold-R-Normal-*-12-120-*.

              -foreground color
                     Specifies the text color  of  entry  labels.
                     Individual  entries  may  override this with
                     their own -foreground option.   The  default
                     is black.

              -height pixels
                     Specifies  the  requested  height of widget.
                     The default is 400.

              -hideroot boolean
                     If boolean is true, it  indicates  that  the
                     root  entry  should  no  be  displayed.  The
                     default is no.

              -highlightbackground  color
                     Specifies  the  color  to  display  in   the
                     traversal    highlight   region   when   the
                     hiertable does not have the input focus.

              -highlightcolor color
                     Specifies the color to use for the traversal
                     highlight rectangle that is drawn around the
                     widget when it has  the  input  focus.   The
                     default is black.

              -highlightthickness pixels
                     Specifies  a  non-negative  value indicating
                     the width of the highlight rectangle to draw
                     around the outside of the widget when it has
                     the input focus.  The value may have any  of
                     the  forms  acceptable  to Tk_GetPixels.  If
                     the value is zero,  no  focus  highlight  is
                     drawn  around the widget.  The default is 2.

              -icons images
                     Specifies images to  be  displayed  for  the
                     entry's  icon.   Images  is a list of two Tk

                     the  entry  is  open,  the second when it is
                     closed.

              -linecolor color
                     Sets the color  of  lines  drawn  connecting
                     entries.  The default is black.

              -linespacing pixels
                     Sets  the  number  of pixels spacing between
                     entries.  The default is 0.

              -linewidth pixels
                     Set the width of the lines drawn  connecting
                     entries.   If  pixels  is  0, no vertical or
                     horizontal lines are drawn.  The default  is
                     1.

              -opencommand string
                     Specifies a Tcl script to be invoked when an
                     entry is open.  For  example,  this  may  be
                     used to populate the hierarchy as it is tra­
                     versed.   Individual  entries  may  override
                     this  with  their  own  -opencommand option.
                     The default is  "".   Percent  substitutions
                     are  performed  on  string before it is exe­
                     cuted.   The  following  substitutions   are
                     valid:

                     %W   The pathname of the widget.

                     %p   The name of the entry.

                     %P   The full pathname of the entry.

                     %#   The index of the node.

                     %%   Translates to a single percent.

              -relief relief
                     Specifies  the  3-D  effect  for the widget.
                     Relief specifies how  the  hiertable  should
                     appear relative to widget it is packed into;
                     for  example,  raised  means  the  hiertable
                     should  appear  to protrude.  The default is
                     sunken.

              -scrollmode mode
                     Specifies the style of scrolling to be used.
                     The following styles are valid.  This is the
                     default is hierbox.

                      listbox     Like the  listbox  widget,  the
                                  last   entry   can   always  be

                                  get  window.   This  allows the
                                  scrollbar thumb  to  shrink  as
                                  the   last  entry  is  scrolled
                                  upward.

                      hierbox     Like the  hierbox  widget,  the
                                  last  entry  can only be viewed
                                  at the  bottom  of  the  widget
                                  window.   The scrollbar stays a
                                  constant size.

                      canvas      Like  the  canvas  widget,  the
                                  entries  are  bound  within the
                                  scrolling area.

              -selectbackground color
                     Specifies the color to use  when  displaying
                     background  of selected entries. The default
                     is #ffffea.

              -selectborderwidth pixels
                     Specifies a  non-negative  value  indicating
                     the  width  of the raised 3-D border to draw
                     around the labels of selected entries.   The
                     default is 0.

              -selectcommand string
                     Specifies  a  Tcl script to invoked when the
                     set  of  selected  entries   changes.    The
                     default is "".

              -selectforeground color
                     Specifies  the color to use when drawing the
                     labels of selected entries. The  default  is
                     black.

              -selectmode mode
                     Specifies  the  selection  mode.  If mode is
                     single, only one entry can be selected at  a
                     time.   If  multiple more than one entry can
                     be selected.  The default is single.

              -separator string
                     Normally  entry  pathnames  are  Tcl  lists,
                     where each element is a path component.  But
                     if string is not the empty string, it speci­
                     fies a character sequence to use when split­
                     ing the path components.  The separator  may
                     several characters (such as "::").  Multiple
                     separator are treated as one. The default is
                     "".

                     If  boolean is false, it indicates that col­
                     umn titles should  not  be  displayed.   The
                     default is yes.

              -sortselection boolean
                     Normally   entries   in  the  selection  are
                     ordered as they are selected.  If boolean is
                     true,  then  the  entries are ordered in the
                     same  way  they  are   currently   displayed
                     (depth-first or sorted).  The default is no.

              -takefocus focus
                     Provides information used  when  moving  the
                     focus  from  window  to  window via keyboard
                     traversal (e.g.,  Tab  and  Shift-Tab).   If
                     focus  is  0,  this  means  that this window
                     should be skipped entirely  during  keyboard
                     traversal.   1  means  that  the this window
                     should always receive the input  focus.   An
                     empty value means that the traversal scripts
                     make the decision whether to  focus  on  the
                     window.  The default is "1".

              -trim string
                     Specifies  leading  characters  to trim from
                     entry pathnames before parsing.   This  only
                     makes  sense  if the -separator is also set.
                     The default is "".

              -width pixels
                     Specifies the requested width of the widget.
                     If  pixels  is  0, then the with is computed
                     from the  contents  of  the  hiertable.  The
                     default is 200.

              -xscrollcommand string
                     Specifies  the  prefix for a command used to
                     communicate  with   horizontal   scrollbars.
                     Whenever the horizontal view in the widget's
                     window changes, the widget will  generate  a
                     Tcl command by concatenating the scroll com­
                     mand and two numbers.  If this option is not
                     specified, then no command will be executed.

              -xscrollincrement pixels
                     Specifies the horizontal scrolling distance.
                     The default is 20 pixels.

              -yscrollcommand string
                     Specifies  the  prefix for a command used to
                     communicate   with   vertical    scrollbars.
                     Whenever  the  vertical view in the widget's
                     window changes, the widget will  generate  a

                     mand and two numbers.  If this option is not
                     specified, then no command will be executed.

              -yscrollincrement pixels
                     Specifies the vertical  scrolling  distance.
                     The default is 20 pixels.

       pathName curselection
              Returns a list containing the indices of all of the
              entries  in  the  hiertable  that   are   currently
              selected.   If there are no entries selected in the
              hiertable then the empty string is returned.

       pathName delete index ?index...?
              Deletes one or more entries of the hiertable.   The
              entry  given by index and its children are deleted.

       pathName entry operation ?args?
              See the ENTRY OPERATIONS section.

       pathName find ?flags? first last
              Finds for all entries matching the  criteria  given
              by  flags.   A  list  of  indices  for all matching
              entries is returned. First  and  last  are  indices
              designating  the range of the search in depth-first
              order. If last is before first,  then  entries  are
              searched in reverse order.  The valid flags are:

               -name pattern
                           Specifies  pattern  to  match  against
                           entry names.

               -full pattern
                           Specifies  pattern  to  match  against
                           entry pathnames.

               -option pattern
                           Specifies pattern to match against the
                           entry's configuration option.

               -exact      Patterns must match  entries  exactly.
                           The is the default.

               -glob       Use global pattern matching.  Matching
                           is done in a fashion similar  to  that
                           used  by  the  C-shell.  For  the  two
                           strings  to match, their contents must
                           be  identical except that the  follow­
                           ing  special  sequences  may appear in
                           pattern:

                           *    Matches  any  sequence  of  char­
                                acters  in  string,  including  a


                           ?    Matches  any  single character in
                                string.

                           [chars]
                                Matches any character in the  set
                                given  by chars. If a sequence of
                                the form x-y  appears  in  chars,
                                then  any character between x and
                                y, inclusive, will match.

                           \x   Matches  the   single   character
                                x.    This   provides  a  way  of
                                avoiding  the  special  interpre­
                                tation of the characters *?[]\ in
                                the pattern.

               -regexp     Use regular expression pattern  match­
                           ing  (i.e.  the same as implemented by
                           the regexp command).

               -nonmatching
                           Expose entries that don't match.

               -exec string
                           Specifies a Tcl script to  be  invoked
                           for each matching entry.  Percent sub­
                           stitutions  are  performed  on  string
                           before  it is executed.  The following
                           substitutions are valid:

                           %W   The pathname of the widget.

                           %p   The name of the entry.

                           %P   The full pathname of the entry.

                           %#   The index of the node.

                           %%   Translates to a single percent.

               -count number
                           Stop searching after number matches.

               --          Indicates the end of flags.

       pathName focus  index
              Sets the focus to the entry given by  index.   When
              an entry has focus, it can receive keyboard events.

       pathName get ?-full? index index...
              Translates  indices  to  their  entry  names.    It
              returns  a  list  of  names  for  all  the  indices

              pathnames are returned.

       pathName hide ?flags? index ?index...?
              Hides  all  entries  matching the criteria given by
              flags.  The search  is  performed  recursively  for
              each  entry  given  by  index.  The valid flags are
              described below:

               -name pattern
                           Specifies  pattern  to  match  against
                           entry names.

               -full pattern
                           Specifies  pattern  to  match  against
                           entry pathnames.

               -option pattern
                           Specifies pattern to match against the
                           entry's configuration option.

               -exact      Match  patterns  exactly.   The is the
                           default.

               -glob       Use global pattern matching.  Matching
                           is  done  in a fashion similar to that
                           used by the C-shell.   For   the   two
                           strings  to match, their contents must
                           be identical except that the   follow­
                           ing  special  sequences  may appear in
                           pattern:

                           *    Matches  any  sequence  of  char­
                                acters  in  string,  including  a
                                null string.

                           ?    Matches any single  character  in
                                string.

                           [chars]
                                Matches  any character in the set
                                given by chars. If a sequence  of
                                the  form  x-y  appears in chars,
                                then any character between x  and
                                y, inclusive, will match.

                           \x   Matches   the   single  character
                                x.   This  provides  a   way   of
                                avoiding   the  special interpre­
                                tation of the characters *?[]\ in
                                the pattern.

               -regexp     Use  regular expression pattern match­
                           ing (i.e. the same as  implemented  by


               -nonmatching
                           Hide entries that don't match.

               --          Indicates the end of flags.

       pathName index ?-at index? string
              Returns the index of the entry specified by string.
              String  may  be  in  any  form  listed  under   the
              HIERTABLE  INDICES  section  above.   Some  special
              indices are normally relative to the entry that has
              focus.  The -at flag lets you select another entry.

       pathName insert ?-at index?  position  path  ?options...?
              ?path? ?options...?
              Inserts one or more entries at position.   Position
              is  the  location  (number  or  end)  where the new
              entries are added to the parent entry.  Path is the
              pathname  of  the new entry.  Pathnames can be for­
              mated either as a Tcl list (each element is a  path
              component)  or  as  a string separated by a special
              character sequence (using the  -separator  option).
              Pathnames are normally absolute, but the -at switch
              lets you select a  relative  starting  point.   Its
              value is the index of the starting entry.

              All  ancestors of the new entry must already exist,
              unless the -autocreate option is set.  It  is  also
              an  error  if  an  entry already exists, unless the
              -allowduplicates option is set.

              Option  and  value  may  have  any  of  the  values
              accepted by the entry configure operation described
              in the ENTRY OPERATIONS section below.   This  com­
              mand  returns  a list containing the indices of the
              new entries.

       pathName move index how destIndex
              Moves the entry given by index to  the  destination
              entry.   The  entry  can  not be an ancestor of the
              destination.  DestIndex is the index of the  desti­
              nation  entry  and can not be the root of the tree.
              In conjunction with how, it describes how the  move
              is performed.

              before  Moves  the  entry  before  the  destination
                      entry.

              after   Moves  the  entry  after  the   destination
                      entry.

              into    Moves  the entry to the end of the destina­
                      tion's list of children.

              Returns the index of the entry closest to the given
              X-Y  screen coordinate.  The optional argument var­
              Name is the name of variable which is set to either
              button  or select to indicate over what part of the
              entry the coordinate lies.  If  the  coordinate  is
              not directly over any entry, then varName will con­
              tain the empty string.

       pathName open ?-recurse? index...
              Opens the one or more entries specified  by  index.
              If  an  entry  is  not already open, the Tcl script
              specified  by  the  -opencommand  option  is   also
              invoked.  If  the  -recurse  flag is set, then each
              child is recursively opened too.

       pathName range ?-open? first last
              Returns the indices in  depth-first  order  of  the
              entries between the first and last indices.  If the
              -open flag is present,  it  indicates  to  consider
              only  open  entries.  If last is before first, then
              the indices are returned in reverse order.

       pathName scan option args
              This  command  implements  scanning.   It  has  two
              forms, depending on option:

              pathName scan mark x y
                     Records  x and y and the current view in the
                     hiertable window;  used in conjunction  with
                     later  scan dragto commands.  Typically this
                     command is associated with  a  mouse  button
                     press  in  the  widget.  It returns an empty
                     string.

              pathName scan dragto x y.
                     Computes the difference between its x and  y
                     arguments  and  the x and y arguments to the
                     last scan mark command for the  widget.   It
                     then  adjusts  the view by 10 times the dif­
                     ference in  coordinates.   This  command  is
                     typically   associated   with  mouse  motion
                     events in the widget, to produce the  effect
                     of  dragging  the list at high speed through
                     the window.  The return value  is  an  empty
                     string.

       pathName see ?-anchor anchor? index
              Adjusts  the  view  (visible  entries)  so that the
              entry given by index is visible in the widget  win­
              dow.  By default the entry is displayed in the mid­
              dle of the window.   This  can  changed  using  the
              -anchor flag.  Its value is a Tk anchor position.

              This command is used to adjust the selection within
              an hiertable.  It has several forms,  depending  on
              option:

              pathName selection anchor index
                     Sets the selection anchor to the entry given
                     by index.  If index refers to a non-existent |
                     entry,  then the closest entry is used.  The
                     selection anchor is the end of the selection
                     that is fixed while dragging out a selection
                     with the mouse.  The  index  anchor  may  be
                     used to refer to the anchor entry.

              pathName selection cancel
                     Clears  the  temporary  selection of entries
                     back  to  the  current  anchor.    Temporary
                     selections are created by the selection mark
                     operation.

              pathName selection clear first ?last?
                     Removes the entries between first  and  last
                     (inclusive)  from the selection.  Both first
                     and last are indices representing a range of
                     entries.   If  last  isn't  given, then only
                     first is deselected.   Entries  outside  the
                     selection are not affected.

              pathName selection clearall
                     Clears the entire selection.

              pathName selection mark index
                     Sets  the  selection mark to the entry given
                     by index.  This causes the range of  entries
                     between  the  anchor and the mark to be tem­
                     porarily added to the selection.  The selec­
                     tion  mark  is the end of the selection that
                     is fixed while dragging out a selection with
                     the  mouse.   The  index mark may be used to
                     refer to the anchor entry.  If index  refers |
                     to  a  non-existent  entry, then the mark is |
                     ignored.  Resetting the mark  will  unselect
                     the  previous  range.   Setting  the  anchor
                     finalizes the range.

              pathName selection includes index
                     Returns 1 if the entry indicated by index is
                     currently selected, 0 if it isn't.

              pathName selection present
                     Returns  1  if  any  entries  are  currently
                     selected and 0 otherwise.

                     Selects all of  the  entries  in  the  range
                     between  first  and last, inclusive, without
                     affecting the  selection  state  of  entries
                     outside that range.

              pathName selection toggle first ?last?
                     Selects/deselects   entries   in  the  range
                     between first and last,  inclusive,  in  the
                     selection.  If an entry is in the selection,
                     it is deselected, otherwise it is  selected.

       pathName show ?flags? index ?index...?
              Exposes  all entries matching the criteria given by
              flags.  This is the inverse of the hide  operation.
              The  search is performed recursively for each entry
              given by index.   The  valid  flags  are  described
              below:

               -name pattern
                           Specifies  pattern  to  match  against
                           entry names.

               -full pattern
                           Specifies  pattern  to  match  against
                           entry pathnames.

               -option pattern
                           Specifies pattern to match against the
                           entry's configuration option.

               -exact      Match patterns exactly.   The  is  the
                           default.

               -glob       -glob  Use  global  pattern  matching.
                           Matching is done in a fashion  similar
                           to that used by the C-shell.  For  the
                           two strings  to match, their  contents
                           must  be  identical  except  that  the
                           following   special   sequences    may
                           appear in pattern:

                           *    Matches  any  sequence  of  char­
                                acters  in  string,  including  a
                                null string.

                           ?    Matches  any  single character in
                                string.

                           [chars]
                                Matches any character in the  set
                                given  by chars. If a sequence of
                                the form x-y  appears  in  chars,
                                then  any character between x and


                           \x   Matches  the   single   character
                                x.    This   provides  a  way  of
                                avoiding  the  special  interpre­
                                tation of the characters *?[]\ in
                                the pattern.

               -regexp     Use regular expression pattern  match­
                           ing  (i.e.  the same as implemented by
                           the regexp command).

               -nonmatching
                           Expose entries that don't match.

               --          Indicates the end of flags.

       pathName sort ?flags? index...
              Sorts the children for each  entries  specified  by
              index.  By default, entries are sorted by name, but
              you can specify a Tcl proc to do your  own  compar­
              isons.

               -command string
                           Specifies a Tcl proc to use to compare
                           entries when sorting.   The  procedure
                           is  called  with  three arguments: the
                           pathname of the widget and the indices
                           of two entries.  The procedure returns
                           1 if the first entry is  greater  than
                           the   second,  -1  is  the  second  is
                           greater, and 0 if equal.

               -recurse    Recursively sort  the  entire  branch,
                           not just the children.

       pathName text operation ?args?
              See the TEXT OPERATIONS section.

       pathName toggle index
              Opens  or  closes the entry given by index.  If the
              corresponding -opencommand or -closecommand  option
              is set, then that command is also invoked.

       pathName xview args
              This  command is used to query and change the hori­
              zontal position of the information in the  widget's
              window.  It can take any of the following forms:

              pathName xview
                     Returns  a  list  containing  two  elements.
                     Each element is a real  fraction  between  0
                     and  1;  together they describe the horizon­
                     tal span that is visible in the window.  For

                     second element is .6, 20% of the hiertable's
                     text  is  off-screen to the left, the middle
                     40% is visible in the window, and 40% of the
                     text  is off-screen to the right.  These are
                     the same values passed to scrollbars via the
                     -xscrollcommand option.

              pathName xview index
                     Adjusts  the  view in the window so that the
                     character position given by  index  is  dis­
                     played  at  the  left  edge  of  the window.
                     Character positions are defined by the width
                     of the character 0.

              pathName xview moveto fraction
                     Adjusts the view in the window so that frac­
                     tion of the total  width  of  the  hiertable
                     text  is  off-screen  to the left.  fraction
                     must be a fraction between 0 and 1.

              pathName xview scroll number what
                     This command shifts the view in  the  window
                     left  or right according to number and what.
                     Number must be an  integer.   What  must  be
                     either  units or pages or an abbreviation of
                     one of these.  If what is  units,  the  view
                     adjusts  left  or  right by number character
                     units (the width of the 0 character) on  the
                     display;   if  it  is  pages  then  the view
                     adjusts by number screenfuls.  If number  is
                     negative then characters farther to the left
                     become visible;   if  it  is  positive  then
                     characters farther to the right become visi­
                     ble.

       pathName yview ?args?
              This command is used to query and change the verti­
              cal  position  of  the text in the widget's window.
              It can take any of the following forms:

              pathName yview
                     Returns a list containing two elements, both
                     of which are real fractions between 0 and 1.
                     The first element gives the position of  the
                     hiertable  entry  at  the top of the window,
                     relative to the hiertable as  a  whole  (0.5
                     means  it  is halfway through the hiertable,
                     for example).  The second element gives  the
                     position  of  the hiertable entry just after
                     the last one in the window, relative to  the
                     hiertable  as  a  whole.  These are the same
                     values  passed   to   scrollbars   via   the
                     -yscrollcommand option.

                     Adjusts  the  view in the window so that the
                     entry given by index is displayed at the top
                     of the window.

              pathName yview moveto fraction
                     Adjusts  the  view in the window so that the
                     entry given by fraction appears at  the  top
                     of  the  window.   Fraction  is  a  fraction
                     between 0 and  1;   0  indicates  the  first
                     entry  in  the hiertable, 0.33 indicates the
                     entry  one-third   the   way   through   the
                     hiertable, and so on.

              pathName yview scroll number what
                     This  command adjusts the view in the window
                     up or down according  to  number  and  what.
                     Number  must  be  an  integer.  What must be
                     either units or pages.  If  what  is  units,
                     the view adjusts up or down by number lines;
                     if it is pages then the view adjusts by num­
                     ber  screenfuls.  If number is negative then
                     earlier entrys become  visible;   if  it  is
                     positive then later entrys become visible.


GLOBAL VS. LOCAL ATTRIBUTES

       Many  configuration options in the hiertable widget can be
       set globally or locally.  For example, there is a -closec­
       ommand configuration option for both widget and individual
       entries.  Options set at the widget level are  global  for
       all entries.  If the entry option is set, it overrides the
       global widget option.  This is done to avoid wasting  mem­
       ory  by  replicated options. Most entries will have redun­
       dant options.


ENTRY OPERATIONS

       The following entry operations are available.

       pathName entry activate index
              Sets the active entry to index.  Index is an  entry
              index.   When  an entry is active it is drawn using
              its active icon (see the -activeicon option).  Note
              that  there can be only one active entry at a time.
              The index of the currently active entry is  active.

       pathName entry cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values   accepted   by   the   configure  operation
              described below.

       pathName entry children index  ?first? ?last?
              Returns a list of indices for the  given  range  of
              children  of index.  Index is index of the entry to

              then  the  index  of the that child at that numeric
              position is returned.  If both first and last argu­
              ments  are given, then the indices of all the chil­
              dren in that range  are  returned.   Otherwise  the
              indices of all children are returned.

       pathName entry configure ?option? ?value option value ...?
              Query or modify the configuration  options  of  the
              widget.   If no option is specified, returns a list
              describing all of the available options  for  path­
              Name  (see  Tk_ConfigureInfo for information on the
              format of this list).  If option is specified  with
              no  value, then the command returns a list describ­
              ing the one named option (this list will be identi­
              cal  to  the  corresponding  sublist  of  the value
              returned if no option is  specified).   If  one  or
              more  option-value  pairs  are  specified, then the
              command modifies the given widget option(s) to have
              the  given  value(s);   in  this  case  the command
              returns an empty  string.   Option  and  value  are
              described below:

              -activeicons images
                     Specifies  images  to  be  displayed for the
                     entry's icon when it is active.  This  over­
                     rides  the global -activeicons configuration
                     option for the specific entry.  Images is  a
                     list  of  two  Tk images: the first image is
                     displayed when the entry is open, the second
                     when it is closed.

              -bindtags tagList
                     Specifies  the  binding  tags  for  entries.
                     TagList is a list of binding tag names.  The
                     tags  and  their  order  will  determine how
                     events are handled for entries.  Each tag in
                     the list matching the current event sequence
                     will have its  Tcl  command  executed.   The
                     default value is all.

              -button string
                     Indicates  whether  a  button should be dis­
                     played  on  the  left  side  of  the  entry.
                     String  can  be  yes, no, or auto.  If auto,
                     then a button is automatically displayed  if
                     the   entry   has  children.   This  is  the
                     default.  This is typically used  when  per­
                     forming   lazy  insertions.   An  entry  may
                     require a button, while it has  no  children
                     yet.

              -closecommand string
                     Specifies  a  Tcl  script to be invoked when

                     global  -closecommand option for this entry.
                     The default is  "".   Percent  substitutions
                     are  performed  on  string before it is exe­
                     cuted.   The  following  substitutions   are
                     valid:

                     %W   The pathname of the widget.

                     %p   The name of the entry.

                     %P   The full pathname of the entry.

                     %#   The index of the node.

                     %%   Translates to a single percent.

              -data string
                     Sets data fields for the entry.  String is a
                     list of name-value pairs to be set.  Entries
                     are not required to contain the same fields.
                     The default is "".

              -font fontName
                     Specifies the font to use for entry  labels.
                     Individual  entries  may  override this with
                     their own  -font  option.   The  default  is
                     *-Helvetica-Bold-R-Normal-*-12-120-*.

              -foreground color
                     Specifies the text color of the entry label.
                     This overrides the global  -foreground  con­
                     figuration option.  The default is "".

              -icons images
                     Specifies  images  to  be  displayed for the
                     entry's icon.   This  overrides  the  global
                     -icons  configuration  option.   Images is a
                     list of two Tk images: the  first  image  is
                     displayed when the entry is open, the second
                     when it is closed.

              -label string
                     Sets the text displayed in the  entry's  the
                     label.   If  not  set,  this defaults to the
                     name of the entry.  String may contain  new­
                     lines but not tabs.  The default is "".

              -opencommand string
                     Specifies  a  Tcl  script to be invoked when
                     thex entry is open.  For example,  this  may
                     be  used  to populate the hierarchy as it is
                     traversed.  This overrides the global -open­
                     command option.  The default is "".  Percent

                     it is executed.  The following substitutions
                     are valid:

                     %W   The pathname of the widget.

                     %p   The name of the entry.

                     %P   The full pathname of the entry.

                     %#   The index of the node.

                     %%   Translates to a single percent.

       pathName entry delete index ?first ?last?
              Deletes the one or more children of the entry given
              by index.  If present, first and last are the posi­
              tions designating a range of children nodes  to  be
              deleted.

       pathName entry isbefore index1  index2
              Returns  1  if index1 is before index2 and 0 other­
              wise.

       pathName entry ishidden index
              Returns 1 if the entry is currently  hidden  and  0
              otherwise.   An  entry  is not hidden if all of its
              ancestor entries are open.

       pathName entry isopen index
              Returns 1 if the entry is currently open and 0 oth­
              erwise.

       pathName entry size -recurse index
              Returns  the  number  of children at index.  If the
              -recurse flag is set, then number of entries in the
              entire  branch is returned.  The entry index is not
              counted.


BUTTON OPERATIONS

       The following operation are available for  hiertable  but­
       tons.

       pathName button activate index
              Sets  the active entry to index.  Index is an entry
              index.  When an entry is active it is  drawn  using
              its active icon (see the -activeicon option).  Note
              that there can be only one active entry at a  time.
              The  index of the currently active entry is active.

       pathName button bind tagName ?sequence command?
              Associates command with tagName such that  whenever
              the  event sequence given by sequence occurs for an
              button of an entry with this tag, command  will  be

              except  that  it  operates  on  hiertable  entries,
              rather  than widgets. See the bind manual entry for
              complete details on sequence and the  substitutions
              performed on command before invoking it.

              If  all  arguments are specified then a new binding
              is created, replacing any existing binding for  the
              same  sequence and tagName.  If the first character
              of command is + then command augments  an  existing
              binding  rather  than  replacing it.  If no command
              argument is provided  then  the  command  currently
              associated with tagName and sequence (it's an error
              occurs if there's no such binding) is returned.  If
              both  command  and sequence are missing then a list
              of all the event sequences for which bindings  have
              been defined for tagName.

       pathName button cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values   accepted   by   the   configure  operation
              described below.

       pathName button configure ?option? ?value option value
              ...?
              Query  or  modify  the configuration options of the
              widget.  If no option is specified, returns a  list
              describing  all  of the available options for path­
              Name (see Tk_ConfigureInfo for information  on  the
              format  of this list).  If option is specified with
              no value, then the command returns a list  describ­
              ing the one named option (this list will be identi­
              cal to  the  corresponding  sublist  of  the  value
              returned  if  no  option  is specified).  If one or
              more option-value pairs  are  specified,  then  the
              command modifies the given widget option(s) to have
              the given  value(s);   in  this  case  the  command
              returns  an  empty  string.   Option  and value are
              described below:

              -activebackground color
                     Sets the background color  for  active  but­
                     tons.   An  button  is active when the mouse
                     passes over it or using the button  activate
                     operation.

              -activeforeground color
                     Sets  the  foreground  color for active but­
                     tons.  An entry is  active  when  the  mouse
                     passes  over it or using the button activate
                     operation.

                     Sets the  background  of  the  button.   The
                     default is white.

              -borderwidth pixels
                     Sets  the width of the 3-D border around the
                     outside edge of  the  button.   The  -relief
                     option  determines  if  the  border is to be
                     drawn.  The default is 1.

              -closerelief relief
                     Specifies the 3-D effect for the closed but­
                     ton.  Relief specifies how the button should
                     appear relative to the widget; for  example,
                     raised  means  the  button  should appear to
                     protrude.  The default is solid.

              -cursor cursor
                     Specifies the widget's cursor.  The  default
                     cursor is "".

              -foreground color
                     Specifies  the  foreground color of buttons.
                     The default is black.

              -images images
                     If set, specifies images to be displayed for
                     the  button.   Images  is  a  list of two Tk
                     images: the first image  is  displayed  when
                     the  button  is  open, the second when it is
                     closed.

              -openrelief relief
                     Specifies the 3-D effect for the  open  but­
                     ton.  Relief specifies how the button should
                     appear relative to the widget; for  example,
                     raised  means  the  button  should appear to
                     protrude.  The default is flat.

              -size pixels
                     Sets the requested size for the button.  The
                     default is 0.


COLUMN OPERATIONS

       The   following  operation  are  available  for  hiertable
       columns.

       pathName column activate column
              Sets the active column to column.   Column  is  the
              name  of  a column in the widget.  When a column is
              active, it's drawn using its -activetitlebackground
              and  -activetitleforeground  options.  If column is
              the "", then no column will be active.  If no  col­
              umn  argument  is  provided,  then  the name of the


       pathName column cget name option
              Returns the current value of the column  configura­
              tion  option given by option for name.  Name is the
              name of column that corresponds to  a  data  field.
              Option  may  have any of the values accepted by the
              configure operation described below.

       pathName column configure name ?option? ?value option
              value  ...?
              Query or modify the configuration  options  of  the
              column  designated by name. Name is the name of the
              column corresponding to a data field.  If no option
              is  specified, returns a list describing all of the
              available options for pathName  (see  Tk_Configure­
              Info  for  information on the format of this list).
              If option is specified with no value, then the com­
              mand returns a list describing the one named option
              (this list will be identical to  the  corresponding
              sublist of the value returned if no option is spec­
              ified).  If one  or  more  option-value  pairs  are
              specified, then the command modifies the given wid­
              get option(s) to have the given value(s);  in  this
              case  the  command returns an empty string.  Option
              and value are described below:

              -background color
                     Sets the background  of  the  column.   This
                     overrides   the  widget's  -background.  The
                     default is white.

              -borderwidth pixels
                     Sets the width of the 3-D border around  the
                     outside  edge  of  the  column.  The -relief
                     option determines if the  border  is  to  be
                     drawn.  The default is 0.

              -edit boolean
                     Indicates whether the column data fields can
                     be editted. If boolean is false, the  column
                     data fields in the column may not be edited.
                     The default is yes.

              -foreground color
                     Specifies the foreground color of  the  data
                     fields  in  the  column.  Individual entries
                     may override this with their own -foreground
                     option.  The default is black.

              -font fontName
                     Specifies  the  font  to use for column data
                     fields.   Individual  entries  may  override
                     this  with  their  own  -font  option.   The

                     mal-*-12-120-*.

              -hide boolean
                     If  boolean  is true, then the column is not
                     displayed.  The default is yes.

              -justify justify
                     Specifies how the column data  fields  title
                     should be justified within the column.  This
                     matters only when the column is  wider  than
                     the  data field to be display.  Justify must
                     be left, right, or center.  The  default  is
                     left.

              -pad pad
                     Sets the padding to the left and right sides
                     of the column.  Pad can be a list of one  or
                     two  screen  distances.  If pad has two ele­
                     ments, the left side of the legend is padded
                     by  the first distance and the right side by
                     the second.  If pad has just  one  distance,
                     both  the  left  and  right sides are padded
                     evenly.  The default is 2.

              -relief relief
                     Specifies the 3-D  effect  for  the  column.
                     Relief   specifies  how  the  button  should
                     appear relative to the widget; for  example,
                     raised  means  the  column  should appear to
                     protrude.  The default is flat.

              -state state
                     Sets the state of the column.  If  state  is
                     disable then the column can not be activated
                     nor invoked.  The default is normal.

              -text string
                     Sets the title for the column.  The  default
                     is "".

              -titleforeground color
                     Specifies the foreground color of the column
                     title.  The default is black.

              -titleshadow color
                     Specifies the color of the drop shadow  used
                     for the column title.  The default is "".

              -width pixels
                     Specifies the requested width of the column.
                     This overriders the  computed  with  of  the
                     column.   If  pixels is 0, the width is com­
                     puted as from the contents  of  the  column.


       pathName column delete field ?field...?
              Deletes  one  of  more columns designated by field.
              Note that this does  not  delete  the  data  fields
              themselves.

       pathName column insert position field ?options...?
              Inserts one of more columns designated by field.  A
              column displays each entry's data field by the same
              name.   Entries  are  not  required  to have a data
              field.  In this  case,  the  cell  is  left  blank.
              Position  indicates where in the list of columns to
              add the new column.  It may be either a  number  or
              end.

       pathName column invoke field
              Invokes  the Tcl command associated with the column
              field, if there is one (using the column's -command
              option).   The  command  is ignored if the column's
              -state option set to disabled.

       pathName column move name dest
              Moves the column name to the destination  position.
              Dest  is  the  name  of  another column or a screen
              position in the form @x,y.

       pathName column names
              Returns a list of the names of all columns  in  the
              widget.   The  list  is  ordered as the columns are
              drawn from left-to-right.

       pathName column nearest x ?y?
              Returns the name of the column closest to the given
              X-Y screen coordinate.  If you provide a y argument
              (it's optional), a name is returned  only  when  if
              the point is over a column's title.


SORT OPERATIONS

       pathName sort auto ?boolean
              Turns  on/off  automatic  sorting  of  entries.  If
              boolean is  true,  entries  will  be  automatically
              sorted  as  they  are  opened, closed, inserted, or
              deleted.  If no boolean argument is  provided,  the
              current state is returned.

       pathName sort cget option
              Returns  the  current  value  of  the configuration
              option given by option.  Option may have any of the
              values   accepted   by   the   configure  operation
              described below.

       pathName sort configure ?option? ?value option value ...?
              Query or modify the sorting  configuration  options

              a list describing all of the available options  for
              pathName  (see  Tk_ConfigureInfo for information on
              the format of this list).  If option  is  specified
              with  no  value,  then  the  command returns a list
              describing the one named option (this list will  be
              identical to the corresponding sublist of the value
              returned if no option is  specified).   If  one  or
              more  option-value  pairs  are  specified, then the
              command modifies the  given  sorting  option(s)  to
              have  the given value(s);  in this case the command
              returns an empty  string.   Option  and  value  are
              described below:

              -column string
                     Specifies the column to sort. Entries in the
                     widget are rearranged according to this col­
                     umn.   If  column is "" then no sort is per­
                     formed.

              -command string
                     Specifies a Tcl procedure to be called  when
                     sorting  entries.   The  procedure is called
                     with three arguments: the  pathname  of  the
                     widget  and  the fields of two entries.  The
                     procedure returns 1 if the  first  entry  is
                     greater than the second, -1 is the second is
                     greater, and 0 if equal.

              -decreasing boolean
                     Indicates to  sort  in  ascending/descending
                     order.  If boolean is true, then the entries
                     as in descending order. The default is no.

              -mode string
                     Specifies how to compare entries when  sort­
                     ing. String may be one of the following:

                     ascii          Use  string  comparison based
                                    upon  the   ASCII   collation
                                    order.

                     dictionary     Use dictionary-style compari­
                                    son.  This  is  the  same  as
                                    ascii   except  (a)  case  is
                                    ignored  except  as  a   tie-
                                    breaker   and   (b)   if  two
                                    strings contain embedded num­
                                    bers,  the numbers compare as
                                    integers,   not   characters.
                                    For  example,  "bigBoy" sorts
                                    between "bigbang"  and  "big­
                                    boy",    and   "x10y"   sorts
                                    between "x9y" and "x11y".


                     real           Compares  fields  as floating
                                    point numbers.

                     command        Use the Tcl proc specified by
                                    the  -command  option to com­
                                    pare  entries  when  sorting.
                                    If  no  command is specified,
                                    the  sort  reverts  to  ascii
                                    sorting.

              pathName sort once ?flags? index...
                     Sorts  the  children for each entries speci­
                     fied by  index.   By  default,  entries  are
                     sorted  by  name,  but you can specify a Tcl
                     proc to do your own comparisons.

               -recurse    Recursively sort  the  entire  branch,
                           not just the children.


DEFAULT BINDINGS

       To be announced.

       Tk  automatically  creates  class  bindings for hiertables
       that give them Motif-like behavior.  Much of the  behavior
       of  an  hiertable is determined by its -selectmode option,
       which selects one of two ways of dealing with  the  selec­
       tion.

       If  the selection mode is single, at most one entry can be
       selected in the hiertable at once.  Clicking button  1  on
       an entry selects it and deselects any other selected item.

       If the selection mode is multiple, any number  of  entries
       may  be  selected at once, including discontiguous ranges.
       Clicking Control-Button-1 on an entry toggles  its  selec­
       tion  state without affecting any other entries.  Pressing
       Shift-Button-1 on an entry selects it, extends the  entry.

       In  addition  to  the  above behavior, the following addi­
       tional behavior is defined by the default bindings:

       [1]    In  extended  mode,  the  selected  range  can   be
              adjusted  by  pressing  button 1 with the Shift key
              down:  this modifies the selection  to  consist  of
              the  entries between the anchor and the entry under
              the mouse, inclusive.  The un-anchored end of  this
              new  selection  can also be dragged with the button
              down.

       [2]    In extended mode, pressing button 1 with  the  Con­
              trol key down starts a toggle operation: the anchor
              is set to  the  entry  under  the  mouse,  and  its

              of other entries isn't changed.  If  the  mouse  is
              dragged  with  button  1  down,  then the selection
              state of all entries between  the  anchor  and  the
              entry  under  the mouse is set to match that of the
              anchor entry;  the selection  state  of  all  other
              entries remains what it was before the toggle oper­
              ation began.

       [3]    If the mouse leaves the hiertable window with  but­
              ton 1 down, the window scrolls away from the mouse,
              making information visible that  used  to  be  off-
              screen  on  the  side  of the mouse.  The scrolling
              continues until the mouse re-enters the window, the
              button  is released, or the end of the hiertable is
              reached.

       [4]    Mouse button 2 may be used for scanning.  If it  is
              pressed  and  dragged  over the hiertable, the con­
              tents of the hiertable drag at high  speed  in  the
              direction the mouse moves.

       [5]    If the Up or Down key is pressed, the location cur­
              sor (active entry) moves up or down one entry.   If
              the  selection  mode is browse or extended then the
              new active entry is also  selected  and  all  other
              entries  are  deselected.  In extended mode the new
              active entry becomes the selection anchor.

       [6]    In extended mode, Shift-Up and Shift-Down move  the
              location cursor (active entry) up or down one entry
              and also extend the selection to that  entry  in  a
              fashion similar to dragging with mouse button 1.

       [7]    The  Left  and Right keys scroll the hiertable view
              left and right by the width  of  the  character  0.
              Control-Left and Control-Right scroll the hiertable
              view left and right by the  width  of  the  window.
              Control-Prior and Control-Next also scroll left and
              right by the width of the window.

       [8]    The Prior and Next keys scroll the  hiertable  view
              up and down by one page (the height of the window).

       [9]    The Home and End keys scroll the hiertable horizon­
              tally to the left and right edges, respectively.

       [10]   Control-Home  sets  the  location cursor to the the
              first entry in the hiertable, selects  that  entry,
              and deselects everything else in the hiertable.

       [11]   Control-End  sets  the  location  cursor to the the
              last entry in the hiertable,  selects  that  entry,
              and deselects everything else in the hiertable.

              selection to the first entry in the  hiertable  and
              Control-Shift-End extends the selection to the last
              entry.

       [13]   In  multiple  mode,  Control-Shift-Home  moves  the
              location cursor to the first entry in the hiertable
              and Control-Shift-End moves the location cursor  to
              the last entry.

       [14]   The  space  and Select keys make a selection at the
              location cursor (active entry)  just  as  if  mouse
              button 1 had been pressed over this entry.

       [15]   In  extended  mode,  Control-Shift-space and Shift-
              Select extend the selection  to  the  active  entry
              just as if button 1 had been pressed with the Shift
              key down.

       [16]   In extended mode, the Escape key cancels  the  most
              recent  selection  and  restores all the entries in
              the selected  range  to  their  previous  selection
              state.

       [17]   Control-slash  selects  everything  in  the widget,
              except in single and browse modes, in which case it
              selects  the  active entry and deselects everything
              else.

       [18]   Control-backslash deselects everything in the  wid­
              get,  except in browse mode where it has no effect.

       [19]   The F16 key (labelled Copy  on  many  Sun  worksta­
              tions) or Meta-w copies the selection in the widget
              to the clipboard, if there is a selection.

       The behavior of hiertablees can be changed by defining new
       bindings for individual widgets or by redefining the class
       bindings.


KEYWORDS

       hiertable, widget


Man(1) output converted with man2html