NAME

       tixHList - Create and manipulate Tix Hierarchial List wid­
       gets


SYNOPSIS

       tixHList pathName ?options?


STANDARD OPTIONS

       -background     -borderWidth   -cursor         -foreground
       -font           -height        -highlightColor -highlightThickness
       -relief         -selectBackground              -selectForeground
       -xScrollCommand -yScrollCommand                -width

       See the options manual entry for details on  the  standard
       options.


WIDGET-SPECIFIC OPTIONS

       Command-Line Name:-browsecmd
       Database Name:  browsecmd
       Database Class: BrowseCmd

              Specifies  a  TCL  command  to be executed when the
              user browses through the entries in the HList  wid­
              get.

       Command-Line Name:-columns
       Database Name:  columns
       Database Class: Columns

              Specifies  the number of columns in this HList wid­
              get. This option can only be set  during  the  cre­
              ation  of  the  HList  widget and cannot be changed
              subsequently.

       Command-Line Name:-command
       Database Name:  command
       Database Class: Command

              Specifies the TCL command to be executed  when  the
              user invokes a list entry in the HList widget. Nor­
              mally the user invokes  a  list  entry  by  double-
              clicking it or pressing the Return key.

       Command-Line Name:-drawbranch
       Database Name:  drawBranch
       Database Class: DrawBranch

              A  Boolean  value  to  specify  whether branch line
              should be drawn to connect list  entries  to  their
              parents.

       Command-Line Name:-foreground or -fg

       Database Class: Foreground

              [OBSOLETE]  Specifies  the default foreground color
              for the list entries.

       Command-Line Name:-gap
       Database Name:  gap
       Database Class: Gap

              [OBSOLETE]  The  default   distance   between   the
              bitmap/image and the text in list entries.

       Command-Line Name:-header
       Database Name:  header
       Database Class: Header

              A  Boolean  value specifying whether headers should
              be displayed for this HList widget (see the  header
              widget command below).

       Command-Line Name:-height
       Database Name:  height
       Database Class: Height

              Specifies the desired height for the window in num­
              ber of characters.

       Command-Line Name:-indent
       Database Name:  indent
       Database Class: Indent

              Specifies  the  amount  of  horizontal  indentation
              between  a  list  entry and its children. Must be a
              valid screen distance value.

       Command-Line Name:-indicator
       Database Name:  indicator
       Database Class: Indicator

              Specifies whether the  indicators  should  be  dis­
              played  inside  the HList widget. See the indicator
              widget command below.

       Command-Line Name:-indicatorcmd
       Database Name:  indicatorCmd
       Database Class: IndicatorCmd

              Specifies a TCL command to  be  executed  when  the
              user  manipulates  the indicator of an HList entry.
              The -indicatorcmd is triggered when the user  press
              or  releases the mouse button over the indicator in
              an HList entry. By default the TCL  command  speci­
              fied   by   -indicatorcmd   is  executed  with  one

              whose  indicator  has  been  triggered.  Additional
              information about the event can be obtained by  the
              tixEvent command.

       Command-Line Name:-itemtype
       Database Name:  itemType
       Database Class: ItemType

              Specifies the default type of display item for this
              HList widget. When you call the  add  and  addchild
              widget commands, display items of this type will be
              created if the -itemtype option is not specified  .

       Command-Line Name:-padx
       Database Name:  padX
       Database Class: Pad

              [OBSOLETE]  The default horizontal padding for list
              entries.

       Command-Line Name:-padx
       Database Name:  padY
       Database Class: Pad

              [OBSOLETE] The default vertical  padding  for  list
              entries.

       Command-Line Name:-selectbackground
       Database Name:  selectBackground
       Database Class: SelectBackground

              Specifies  the  background  color  for the selected
              list entries.

       Command-Line Name:-selectborderwidth
       Database Name:  selectBorderWidth
       Database Class: BorderWidth

              Specifies a non-negative value indicating the width
              of  the  3-D  border to draw around selected items.
              The value may have any of the forms  acceptable  to
              Tk_GetPixels.

       Command-Line Name:-selectforeground
       Database Name:  selectForeground
       Database Class: SelectForeground

              Specifies  the  foreground  color  for the selected
              list entries.

       Command-Line Name:-selectmode
       Database Name:  selectMode
       Database Class: SelectMode

              the  selection.   The  value  of  the option may be
              arbitrary, but the default bindings expect it to be
              either  single,  browse, multiple, or extended; the
              default value is single.

       Command-Line Name:-sizecmd
       Database Name:  sizeCmd
       Database Class: SizeCmd

              Specifies a TCL script to be  called  whenever  the
              HList  widget changes its size. This command can be
              useful to implement "user scroll bars when  needed"
              features.

       Command-Line Name:-separator
       Database Name:  separator
       Database Class: Separator

              Specifies  the  character  to used as the separator
              character when intepreting the path-names  of  list
              entries. By default the character "." is used.

       Command-Line Name:-width
       Database Name:  width
       Database Class: Width

              Specifies the desired width for the window in char­
              acters.
_________________________________________________________________


DESCRIPTION

       The tixHList command creates a new window  (given  by  the
       pathName  argument)  and  makes  it  into  a HList widget.
       Additional options, described above, may be  specified  on
       the  command  line  or in the option database to configure
       aspects of the HList widget such as its cursor and relief.

       The HList widget can be used to display any data that have
       a hierarchical structure, for example, file system  direc­
       tory trees. The list entries are indented and connected by
       branch lines according to their places in the hierachy.

       Each list entry is identified by an entryPath. The  entry­
       Path is a sequence of entry names separated by the separa­
       tor charactor (specified by  the  -separator  option).  An
       entry  name  can  be  any string that does not contain the
       separator charactor, or it can be the a string  that  con­
       tains only one separator charactor.

       For  example, when "." is used as the separator charactor,
       "one.two.three" is the entryPath for a  list  entry  whose
       parent  is  "one.two",  whose  parent is "one", which is a
       toplevel entry (has no parents).

       entry  whose  parent is ".two", whose parent is ".", which
       is a toplevel entry.


DISPLAY ITEMS

       Each list entry in an HList widget is  associated  with  a
       display  item.   The  display  item determines what visual
       information should  be  displayed  for  this  list  entry.
       Please  see  the tixDisplayStyle manual page for a list of
       all display items.

       When a list entry is created by the add or addchild widget
       commands,  the  type  of its display item is determined by
       the -itemtype option passed  to  these  commands.  If  the
       -itemtype  is  omitted, then by default the type specified
       by this HList widget's -itemtype option is used.


WIDGET COMMAND

       The tixHList command creates a new Tcl command whose  name
       is the same as the path name of the HList widget's window.
       This command may be used to invoke various  operations  on
       the widget.  It has the following general form:
                     pathName option ?arg arg ...?
       PathName  is the name of the command, which is the same as
       the HList widget's path name.  Option and the args  deter­
       mine  the  exact  behavior  of the command.  The following
       commands are possible for HList widgets:

       pathName add entryPath ?option value ...?
              Creates a new list entry with the  pathname  entry­
              Path. A list entry must be created after its parent
              is created (unless this entry is a top-level entry,
              which  has  no  parent).  This  command returns the
              entryPath of the newly created list entry. The fol­
              lowing  configuration  options can be given to con­
              figure the list entry:

              -at position
                     Insert the new list at the position given by
                     position.  position must be a valid integer.
                     the Position 0 indicates the first position,
                     1  indicates the second position, and so on.

              -after afterWhich
                     Insert the new list entry  after  the  entry
                     identified by afterWhich. afterWhich must be
                     a valid list entry and it mush have the same
                     parent as the new list entry

              -before beforeWhich
                     Insert  the  new list entry before the entry
                     identified by beforeWhich. beforeWhich  must
                     be  a  valid list entry and it mush have the
                     same parent as the new list entry

                     Specifies a string to  associate  with  this
                     list  entry.  This  string can be queried by
                     the info  widget  command.  The  application
                     programmer can use the -data option to asso­
                     ciate the list entry with the data it repre­
                     sents.

              -itemtype type
                     Specifies  the  type  of  display item to be
                     display for the new list entry. type must be
                     a  valid  display  item  type. Currently the
                     available display item types are  imagetext,
                     text,  and  window.  If  this  option is not
                     specified, then by default the  type  speci­
                     fied by this HList widget's -itemtype option
                     is used.

              -state Specifies whether this entry can be selected
                     or invoked by the user.  Must be either nor­
                     mal or disabled.
       The add widget command  accepts  additional  configuration
       options to configure the display item associated with this
       list entry. The set of  additional  configuration  options
       depends  on  the  type  of  the  display item given by the
       -itemtype option. Please see  the  tixDisplayStyle  manual
       page  for  a list of the configuration options for each of
       the display item types.

       pathName addchild parentPath ?option value ... ?
              Adds a new child entry to the children list of  the
              list entry identified by parentPath. Or, if parent­
              Path is set to be the empty string, then creates  a
              new  toplevel entry. The name of the new list entry
              will be a unique name  automatically  generated  by
              the  HList  widget.  Usually  if parentPath is foo,
              then the entryPath of the new entry will be  foo.1,
              foo.2, ... etc.  This command returns the entryPath
              of the newly created list entry.  option can be any
              option for the add widget command.

       pathName anchor set entryPath
              Sets  the  anchor  to  the list entry identified by
              entryPath.  The anchor is the end of the  selection
              that  is  fixed  while  the  user is dragging out a
              selection with the mouse.

       pathName anchor clear
              Removes the anchor, if any, from this HList widget.
              This only removes the surrounding highlights of the
              anchor entry and does not affect its selection sta­
              tus.

              Returns  the  current  value  of  the configuration
              option given by option. Option may have any of  the
              values accepted by the tixHList command.

       pathName column width col ?-char? ?width?
              Querys or sets the width of a the column col in the
              HList widget. The value of  col  is  zero-based:  0
              stands  for the first column, 1 stands for the sec­
              ond, and so on. If no further parameters are given,
              returns the current width of this column (in number
              of pixels). Additional parameters can be  given  to
              set the width of this column:

              pathName column width col {}
                     An  empty string indicates that the width of
                     the column should be  just  wide  enough  to
                     display  the  widest element in this column.
                     In this case, the width of this  column  may
                     change  as  a result of the elements in this
                     column changing their sizes.

              pathName column width col width
                     width must be in a form accepted by  Tk_Get­
                     Pixels(3).

              pathName column width col -char nChars
                     The  width  is  set  to be the average width
                     occupied by nChars number of  characters  of
                     the  font  specified  by the -font option of
                     this HList widget.

       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
              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 may  have  any  of
              the values accepted by the tixHList command.

       pathName delete option ?entryPath?
              Delete  one or more list entries. option may be one
              of the following:

              all    Delete all entries in  the  HList.  In  this

                     ified.

              entry  Delete the entry specified by entryPath  and
                     all its offsprings, if any.

              offsprings
                     Delete  all  the  offsprings, if any, of the
                     entry  specified  by   entryPath.   However,
                     entryPath itself is not deleted.

              siblings
                     Delete  all  the list entries that share the
                     same parent  with  the  entry  specified  by
                     entryPath.  However, entryPath itself is not
                     deleted.

       pathName dragsite set entryPath
              Sets the dragsite to the list entry  identified  by
              entryPath.  The  dragsite  is  used to indicate the
              source of a drag-and-drop action.  Currently  drag-
              and-drop  functionality has not been implemented in
              Tix yet.

       pathName dragsite clear
              Remove the dragsite, if any, from  the  this  HList
              widget.  This  only  removes  the surrounding high­
              lights of the dragsite entry and  does  not  affect
              its selection status.

       pathName dropsite set entryPath
              Sets  the  dropsite to the list entry identified by
              entryPath. The dropsite is  used  to  indicate  the
              target  of  a grag-and-drop action. Currently drag-
              and-drop functionality has not been implemented  in
              Tix yet.

       pathName dropsite clear
              Remove  the  dropsite,  if any, from the this HList
              widget. This only  removes  the  surrounding  high­
              lights  of  the  dropsite entry and does not affect
              its selection status.

       pathName entrycget  entryPath option
              Returns the  current  value  of  the  configuration
              option  given by option for the entry indentfied by
              entryPath.  Option  may  have  any  of  the  values
              accepted by the add widget command.

       pathName  entryconfigure  entryPath  ?option? ?value
              option value ...?
              Query  or  modify  the configuration options of the
              list entry indentfied by entryPath. If no option is
              specified,  returns  a  list  describing all of the

              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 spec­
              ified,   then   the   command  modifies  the  given
              option(s) to have the given value(s); in this  case
              the  command  returns  an empty string.  Option may
              have any of the values accepted by the add or  add­
              child  widget  command.  The  exact  set of options
              depends on the value of the -itemtype option passed
              to the the add or addchild widget command when this
              list entry is created.

       pathName header option col ?args ...?
              Manipulates the header items of this HList  widget.
              If  the  -header option of this HList widget is set
              to true, then a header item is displayed at the top
              of  each  column. The col argument for this command
              must be a valid integer. 0 indicates the first col­
              umn,  1 the second column, ... and so on. This com­
              mand supports the following options:

              pathName header cget col option
                     If the col-th column has  a  header  display
                     item,  returns  the  value  of the specified
                     option of the header  item.  If  the  header
                     doesn't exist, returns an error.

              pathName header configure col ?option? ?value
                     option value ...?
                     Query or modify the configuration options of
                     the  header  display item of the col-th col­
                     umn. The header item must exist, or an error
                     will  result.   If  no  option is specified,
                     returns a list describing all of the  avail­
                     able  options  for  the  header display item
                     (see Tk_ConfigureInfo(3) for information  on
                     the format of this list.) If option is spec­
                     ified  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 option(s) to have
                     the given value(s); in this case the command
                     returns an empty string. Option may have any
                     of  the values accepted by the header create
                     widget command. The  exact  set  of  options
                     depends on the value of the -itemtype option
                     passed  to  the  the  header  create  widget


              pathName header create col ?-itemtype type? ?option
                     value ...?
                     Creates a new display item as the header for
                     the col-th column. If an header display item
                     already  exists  for this column, it will be
                     replaced  by  the  new  item.   An  optional
                     parameter  -itemtype  can be used to specify
                     what type of display item should be created.
                     If  the  -itemtype  is  not  given,  then by
                     default the type  specified  by  this  HList
                     widget's  -itemtype  option  is  used. Addi­
                     tional parameters,  in  option-value  pairs,
                     can be passed to configure the appearance of
                     the display  item.  Each  option-value  pair
                     must be a valid option for this type of dis­
                     play item or one of the following:

                      -borderwidth
                             Specifies the border width  of  this
                             header item.

                      -headerbackground
                             Specifies  the  background  color of
                             this header item.

                      -relief
                             Specifies the  relief  type  of  the
                             border of this header item.

              pathName header delete col
                     Deletes the header display item for the col-
                     th column.

              pathName header exists col
                     Return true if an header display item exists
                     for  the  col-th column; return false other­
                     wise.

              pathName header size entryPath
                     If an header display  item  exists  for  the
                     col-th  column  ,  returns its size in a two
                     element list of  the  form  {width  height};
                     returns  an error if the header display item
                     does not exist.

       pathName hide option ?entryPath?
              Makes some of entries invisible  invisible  without
              deleting them.  Option can be one of the following:

              entry  Hides the list entry  identified  by  entry­
                     Path.

              options will be added in the next release.

       pathName indicator option entryPath ?args ...?
              Manipulates the indicator on the list  entries.  An
              indicator  is usually a small display item (such as
              an image) that is displayed to the left to an entry
              to  indicate  the status of the entry. For example,
              it may be used to indicator whether a directory  is
              opened  or closed. option can be one of the follow­
              ing:

              pathName indicator cget entryPath option
                     If the list entry given by entryPath has  an
                     indicator,  returns  the value of the speci­
                     fied option of the indicator. If the indica­
                     tor doesn't exist, returns an error.

              pathName  indicator  configure  entryPath  ?option?
                     ?value option value ...?
                     Query or modify the configuration options of
                     the indicator  display  item  of  the  entry
                     specified  by  entryPath. The indicator item
                     must exist, or an error will result.  If  no
                     option is specified, returns a list describ­
                     ing all of the  available  options  for  the
                     indicator  display  item  (see Tk_Configure­
                     Info(3) 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  sub­
                     list  of  the value returned if no option is
                     specified).  If  one  or  more  option-value
                     pairs  are specified, then the command modi­
                     fies the given option(s) to have  the  given
                     value(s);  in  this case the command returns
                     an empty string.  Option may have any of the
                     values accepted by the indicator create wid­
                     get  command.  The  exact  set  of   options
                     depends on the value of the -itemtype option
                     passed to the the  indicator  create  widget
                     command  when this display item was created.

              pathName indicator  create  entryPath  ?-itemtype
                     type?  ?option value ...?
                     Creates a new display item as the  indicator
                     for  the entry specified by entryPath. If an
                     indicator display item  already  exists  for
                     this  entry,  it will be replaced by the new
                     item.  An optional parameter  -itemtype  can
                     be used to specify what type of display item
                     should be created. If the -itemtype  is  not
                     given, then by default the type specified by

                     used. Additional parameters, in option-value
                     pairs,  can  be  passed  to  configure   the
                     appearance of the display item. Each option-
                     value pair must be a valid option  for  this
                     type of display item.

              pathName indicator delete entryPath
                     Deletes  the  indicator display item for the
                     entry given by entryPath.

              pathName indicator exists entryPath
                     Return true if  an  indicator  display  item
                     exists  for  the  entry  given by entryPath;
                     return false otherwise.

              pathName indicator size entryPath
                     If an indicator display item exists for  the
                     entry  given  by entryPath, returns its size
                     in a two element list  of  the  form  {width
                     height};  returns  an error if the indicator
                     display item does not exist.

       pathName info option arg ...
              Query information about the  HList  widget.  option
              can be one of the following:

              pathName info anchor
                     Returns the entryPath of the current anchor,
                     if any, of the HList widget. If  the  anchor
                     is not set, returns the empty string.

              pathName info bbox entryPath
                     Returns  a  list  of four numbers describing
                     the visible bounding box of the entry  given
                     entryPath.  The  first  two  elements of the
                     list give the x and  y  coordinates  of  the
                     upper-left corner of the screen area covered
                     by the entry (specified in  pixels  relative
                     to  the  widget)  and  the last two elements
                     give the lower-right corner of the area,  in
                     pixels.  If  no  part  of the entry given by
                     index is visible  on  the  screen  then  the
                     result  is  an empty string; if the entry is
                     partially visible, the result gives the only
                     the visible area of the entry.

              pathName info children ?entryPath?
                     If  entrpyPath  is  given, returns a list of
                     the entryPath's  of  its  children  entries.
                     Otherwise  returns  a  list  of the toplevel
                     entryPath's.

                     Returns the data associated with  entryPath.

              pathName info dragsite
                     Returns   the   entryPath   of  the  current
                     dragsite, if any, of the  HList  widget.  If
                     the  dragsite  is not set, returns the empty
                     string.

              pathName info dropsite
                     Returns the entryPath of the  current  drop­
                     site,  if  any,  of the HList widget. If the
                     dropsite  is  not  set,  returns  the  empty
                     string.

              pathName info exists entryPath
                     Returns  a  boolean value indicating whether
                     the list entry entrpyPath exists.

              pathName info hidden entryPath
                     Returns a boolean value  indicating  whether
                     the  list entry entrpyPath is hidden or not.

              pathName info next entryPath
                     Returns the entryPath of the list entry,  if
                     any,  immediately  below this list entry. If
                     this entry is already at the bottom  of  the
                     HList widget, returns an empty string.

              pathName info parent entryPath
                     Returns  the  name of the parent of the list
                     entry identified by entrpyPath.  If  entrpy­
                     Path  is  a toplevel list entry, returns the
                     empty string.

              pathName info prev entryPath
                     Returns the entryPath of the list entry,  if
                     any,  immediately  above this list entry. If
                     this entry is already  at  the  top  of  the
                     HList widget, returns an empty string.

              pathName info selection
                     Returns  a  list  of selected entries in the
                     HList widget. If  no  entries  are  selectd,
                     returns an empty string.

       pathName item option ?args ...?
              Creates  and  configures the display items at indi­
              vidual columns the entries. The form of  additional
              of arguments depends on the choice of option:

              pathName item cget entryPath col option
                     Returns  the  current value of the configure
                     option of the display  item  at  the  column

                     entryPath.

              pathName item configure  entryPath  col  ?option?
                     ?value  option value ...?
                     Query or modify the configuration options of
                     the display item at the column designated by
                     col of the entry specified by entryPath.  If
                     no  option  is  specified,  returns  a  list
                     describing all of the available options  for
                     entryPath   (see   Tk_ConfigureInfo(3)   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
                     option(s) to have  the  given  value(s);  in
                     this  case  the  command  returns  an  empty
                     string.  Option may have any of  the  values
                     accepted  by the item create widget command.
                     The exact set  of  options  depends  on  the
                     value  of the -itemtype option passed to the
                     the item create  widget  command  when  this
                     display item was created.

              pathName item create entryPath col ?-itemtype type?
                     ?option value ...?
                     Creates  a  new  display  item at the column
                     designated by col of the entry specified  by
                     entryPath.  An  optional parameter -itemtype
                     can be used to specify what type of  display
                     items should be created. If the -itemtype is
                     not specified,  then  by  default  the  type
                     specified  by  this HList widget's -itemtype
                     option is used.  Additional  parameters,  in
                     option-value pairs, can be passed to config­
                     ure the appearance of the display item. Each
                     option-  value  pair  must be a valid option
                     for this type of display item.

              pathName item delete entryPath col
                     Deletes the display item at the column  des­
                     ignated  by  col  of  the entry specified by
                     entryPath.

              pathName item exists entryPath col
                     Returns true if there is a display  item  at
                     the  column  designated  by col of the entry
                     specified by entryPath; returns false other­
                     wise.

              Given  a y-coordinate within the HList window, this
              command returns  the  entryPath  of  the  (visible)
              HList element nearest to that y-coordinate.

       pathName see entryPath
              Adjust  the  view  in  the  HList so that the entry
              given by entryPath is  visible.  If  the  entry  is
              already  visible then the command has no effect; if
              the entry is near one edge of the window  then  the
              HList scrolls to bring the element into view at the
              edge; otherwise the HList widget scrolls to  center
              the entry.

       pathName selection option arg ...
              This command is used to adjust the selection within
              a HList widget. It has several forms, depending  on
              option:

              pathName selection clear ?from? ?to?
                     When no extra arguments are given, deselects
                     all of the list entrie(s) in this HList wid­
                     get.  When only from is given, only the list
                     entry identified by from is deselected. When
                     both from and to are given, deselects all of
                     the list entrie(s) between between from  and
                     to,  inclusive, without affecting the selec­
                     tion state of entries outside that range.

              pathName selection get
                     This is an alias for the info selection wid­
                     get command.  ,

              pathName selection includes entryPath
                     Returns  1  if  the  list entry indicated by
                     entryPath is currently selected;  returns  0
                     otherwise.

              pathName selection set from ?to?
                     Selects  all  of  the list entrie(s) between
                     between  from  and  to,  inclusive,  without
                     affecting  the  selection  state  of entries
                     outside that range. When only from is given,
                     only  the  list  entry identified by from is
                     selected.

       pathName show option ?entryPath?
              Show the entries that are hidden by the  hide  com­
              mand, option can be one of the following:

              entry  Shows  the  list  entry identified by entry­
                     Path.

              Currently only the entry option is supported. Other


       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 horizontal
                     span that is visible  in  the  window.   For
                     example,  if the first element is .2 and the
                     second element is .6, 20% of the HList entry
                     is off-screen to the left, the middle 40% is
                     visible in the window, and 40% of the  entry
                     is  off-screen  to  the right. These are the
                     same values passed  to  scrollbars  via  the
                     -xscrollcommand option.

              pathName xview entryPath
                     Adjusts  the  view in the window so that the
                     list  entry  identified  by   entryPath   is
                     aligned to the left edge of the window.

              pathName xview moveto fraction
                     Adjusts the view in the window so that frac­
                     tion of the total width of the HList is off-
                     screen to the left. fraction must be a frac­
                     tion 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 char­
                     acters  farther to the right become visible.

       pathName yview ?args?
              This command is used to query and change the verti­
              cal position of the entries 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

                     tive to the HList as a whole (0.5  means  it
                     is  halfway through the HList, for example).
                     The second element gives the position of the
                     list  entry  just  after the last one in the
                     window, relative to the HList  as  a  whole.
                     These  are the same values passed to scroll­
                     bars via the -yscrollcommand option.

              pathName yview entryPath
                     Adjusts the view in the window so  that  the
                     list  entry  given by entryPath is displayed
                     at the top of the window.

              pathName yview moveto fraction
                     Adjusts the view in the window so  that  the
                     list  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 HList, 0.33 indicates the entry  one-
                     third  the way through the HList, and so on.

              pathName yview scroll number what
                     This command adjust 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  entries  become  visible;  if it is
                     positive then later entries become  visible.


BINDINGS

       [1]    If the -selectmode is "browse", when the user drags
              the mouse pointer over the list entries, the  entry
              under  the  pointer  will  be  highlighted  and the
              -browsecmd procedure will be called with one param­
              eter,  the entryPath of the highlighted entry. Only
              one entry can be highlighted at a time.  The  -com­
              mand procedure will be called when the user double-
              clicks on a list entry.

       [2]    If the -selectmode is "single",  the  entries  will
              only  be  highlighted  by  mouse  <ButtonRelease-1>
              events. When a new list entry is  highlighted,  the
              -browsecmd procedure will be called with one param­
              eter indicating the  highlighted  list  entry.  The
              -command  procedure  will  be  called when the user
              double-clicks on a list entry.

       [3]    If the -selectmode is  "multiple",  when  the  user
              drags  the mouse pointer over the list entries, all
              the entries under the pointer will be  highlighted.

              can be  selected.  When  the  highlighted  area  is
              changed,  the  -browsecmd  procedure will be called
              with an undefined parameter. It is the responsibil­
              ity  of  the  -browsecmd  procedure to find out the
              exact highlighted selection in the HList. The -com­
              mand procedure will be called when the user double-
              clicks on a list entry.

       [4]    If the -selectmode is  "extended",  when  the  user
              drags  the mouse pointer over the list entries, all
              the entries under the pointer will be  highlighted.
              The  user can also make disjointed selections using
              <Control-ButtonPress-1>. When the highlighted  area
              is changed, the -browsecmd procedure will be called
              with an undefined parameter. It is the responsibil­
              ity  of  the  -browsecmd  procedure to find out the
              exact highlighted selection in the HList. The -com­
              mand procedure will be called when the user double-
              clicks on a list entry.

       [5]    Arrow key bindings: <Up> arrow key moves the anchor
              point  to  the  item  right  on  top of the current
              anchor item. <Down>  arrow  key  moves  the  anchor
              point  to  the  item right below the current anchor
              item.  <Left> arrow key moves  the  anchor  to  the
              parent  item  of  the  current anchor item. <Right>
              moves the anchor to the first child of the  current
              anchor  item.  If  the current anchor item does not
              have any children, moves the  anchor  to  the  item
              right below the current anchor item.


EXAMPLE

       This  example  demonstrates how to use an HList to store a
       file directory structure and respond to the user's  browse
       events:

              set h [tixHList .h -separator "/" -browsecmd browse \
                  -selectmode single -itemtype text]
              $h add /         -text /
              $h add /home     -text /home
              $h add /home/ioi -text /home/ioi
              $h add /home/foo -text /home/foo
              $h add /usr      -text /usr
              $h add /usr/lib  -text /usr/lib
              pack $h

              proc browse {file} {
                  puts "$file browsed"
              }


BUGS

       The  fact  that the display item at column 0 is implicitly
       associated with the whole entry is probably a design  bug.

       result is that there is a large overlap between  the  item
       command  and the add, addchild, entrycget and entryconfig­
       ure commands. Whenever multiple columns  exist,  the  pro­
       grammer  should  use  ONLY  the item command to create and
       configure the display items in each column; the add,  add­
       child, entrycget and entryconfigure should be used ONLY to
       create and configure entries.


KEYWORDS

       hierarchical listbox, widget


Man(1) output converted with man2html