1tixHList(n)                  Tix Built-In Commands                 tixHList(n)
2
3
4

NAME

6       tixHList - Create and manipulate Tix Hierarchial List widgets
7

SYNOPSIS

9       tixHList    pathName   ?options?    -background    -borderWidth   -cur‐
10       sor   -foreground -font     -height   -highlightColor  -highlightThick‐
11       ness       -relief   -selectBackground   -selectForeground -xScrollCom‐
12       mand     -yScrollCommand     -width
13

WIDGET-SPECIFIC OPTIONS

15       [-browsecmd browsecmd] Specifies a TCL command to be executed when  the
16       user  browses  through the entries in the HList widget.  [-columns col‐
17       umns] Specifies the number of columns in this HList widget. This option
18       can  only  be set during the creation of the HList widget and cannot be
19       changed subsequently.  [-command command] Specifies the TCL command  to
20       be  executed  when  the  user invokes a list entry in the HList widget.
21       Normally the user invokes a list entry by double-clicking it or  press‐
22       ing  the Return key.  [-drawbranch drawBranch] A Boolean value to spec‐
23       ify whether branch line should be drawn  to  connect  list  entries  to
24       their parents.
25
26       Name:          foreground
27       Class:         Foreground
28       Switch:        -foreground
29       Alias:         -fg
30
31              [OBSOLETE]  Specifies  the default foreground color for the list
32              entries.  [-gap gap] [OBSOLETE] The default distance between the
33              bitmap/image  and  the text in list entries.  [-header header] A
34              Boolean value specifying whether headers should be displayed for
35              this  HList  widget  (see  the  header  widget  command  below).
36              [-height height] Specifies the desired height for the window  in
37              number  of characters.  [-indent indent] Specifies the amount of
38              horizontal indentation between a list entry  and  its  children.
39              Must  be  a valid screen distance value.  [-indicator indicator]
40              Specifies whether the indicators should be displayed inside  the
41              HList widget. See the indicator widget command below.  [-indica‐
42              torcmd indicatorCmd] Specifies a TCL command to be executed when
43              the user manipulates the indicator of an HList entry. The -indi‐
44              catorcmd is triggered when the user press or releases the  mouse
45              button  over the indicator in an HList entry. By default the TCL
46              command specified by -indicatorcmd is executed  with  one  addi‐
47              tional  argument, the entryPath of the entry whose indicator has
48              been triggered. Additional information about the  event  can  be
49              obtained  by  the tixEvent command.  [-itemtype itemType] Speci‐
50              fies the default type of display item  for  this  HList  widget.
51              When  you  call  the  add  and addchild widget commands, display
52              items of this type will be created if the  -itemtype  option  is
53              not  specified .  [-padx padX] [OBSOLETE] The default horizontal
54              padding for list entries.  [-padx padY] [OBSOLETE]  The  default
55              vertical  padding  for list entries.  [-selectbackground select‐
56              Background] Specifies the background color for the selected list
57              entries.    [-selectborderwidth selectBorderWidth]  Specifies  a
58              non-negative value indicating the width of  the  3-D  border  to
59              draw around selected items.  The value may have any of the forms
60              acceptable  to   Tk_GetPixels.    [-selectforeground selectFore‐
61              ground]  Specifies  the  foreground  color for the selected list
62              entries.   [-selectmode selectMode]  Specifies  one  of  several
63              styles  for manipulating the selection.  The value of the option
64              may be arbitrary, but the  default  bindings  expect  it  to  be
65              either  single, browse, multiple, or extended; the default value
66              is single.  [-sizecmd sizeCmd] Specifies  a  TCL  script  to  be
67              called  whenever the HList widget changes its size. This command
68              can be useful to implement "user scroll bars when  needed"  fea‐
69              tures.   [-separator separator]  Specifies the character to used
70              as the separator character when intepreting  the  path-names  of
71              list   entries.   By   default   the   character  "."  is  used.
72              [-width width] Specifies the desired width  for  the  window  in
73              characters.
74

DESCRIPTION

76       The  tixHList command creates a new window (given by the pathName argu‐
77       ment) and makes it into a HList widget.  Additional options,  described
78       above,  may  be specified on the command line or in the option database
79       to configure aspects of the HList widget such as its cursor and relief.
80
81       The HList widget can be used to display any data that have a hierarchi‐
82       cal  structure,  for  example,  file  system  directory trees. The list
83       entries are indented and connected by branch lines according  to  their
84       places in the hierachy.
85
86       Each  list  entry  is  identified  by  an entryPath. The entryPath is a
87       sequence of entry names separated by the separator charactor (specified
88       by  the  -separator  option). An entry name can be any string that does
89       not contain the separator charactor, or it can be  the  a  string  that
90       contains only one separator charactor.
91
92       For   example,   when   "."   is   used  as  the  separator  charactor,
93       "one.two.three" is the entryPath for  a  list  entry  whose  parent  is
94       "one.two",  whose  parent  is  "one", which is a toplevel entry (has no
95       parents).
96
97       Another examples: ".two.three" is the entryPath for a list entry  whose
98       parent is ".two", whose parent is ".", which is a toplevel entry.
99

DISPLAY ITEMS

101       Each  list  entry in an HList widget is associated with a display item.
102       The display item determines what visual information should be displayed
103       for  this  list entry. Please see the tixDisplayStyle manual page for a
104       list of all display items.
105
106       When a list entry is created by the add or  addchild  widget  commands,
107       the  type  of  its  display  item is determined by the -itemtype option
108       passed to these commands. If the -itemtype is omitted, then by  default
109       the type specified by this HList widget's -itemtype option is used.
110

WIDGET COMMAND

112       The  tixHList  command creates a new Tcl command whose name is the same
113       as the path name of the HList widget's window.   This  command  may  be
114       used  to invoke various operations on the widget.  It has the following
115       general form:
116              pathName option ?arg arg ...?
117       PathName is the name of the command, which is the  same  as  the  HList
118       widget's  path  name.  Option and the args determine the exact behavior
119       of the command.  The following commands are possible for HList widgets:
120
121       pathName add entryPath ?option value ...?
122              Creates a new list entry with the  pathname  entryPath.  A  list
123              entry  must  be created after its parent is created (unless this
124              entry is a top-level entry, which has no parent).  This  command
125              returns  the entryPath of the newly created list entry. The fol‐
126              lowing configuration options can be given to configure the  list
127              entry:
128
129              -at position
130                     Insert  the  new  list at the position given by position.
131                     position must be a valid integer. the  Position  0  indi‐
132                     cates  the  first  position, 1 indicates the second posi‐
133                     tion, and so on.
134
135              -after afterWhich
136                     Insert the new list entry after the entry  identified  by
137                     afterWhich.  afterWhich must be a valid list entry and it
138                     mush have the same parent as the new list entry
139
140              -before beforeWhich
141                     Insert the new list entry before the entry identified  by
142                     beforeWhich.  beforeWhich  must be a valid list entry and
143                     it mush have the same parent as the new list entry
144
145              -data string
146                     Specifies a string to associate  with  this  list  entry.
147                     This  string  can  be queried by the info widget command.
148                     The application programmer can use the  -data  option  to
149                     associate the list entry with the data it represents.
150
151              -itemtype type
152                     Specifies  the type of display item to be display for the
153                     new list entry. type must be a valid display  item  type.
154                     Currently the available display item types are imagetext,
155                     text, and window. If this option is not  specified,  then
156                     by  default  the  type  specified  by this HList widget's
157                     -itemtype option is used.
158
159              -state Specifies whether this entry can be selected  or  invoked
160                     by the user.  Must be either normal or disabled.
161       The add widget command accepts additional configuration options to con‐
162       figure the display item associated with this list  entry.  The  set  of
163       additional  configuration  options  depends  on the type of the display
164       item given by the -itemtype option. Please see the tixDisplayStyle man‐
165       ual  page  for a list of the configuration options for each of the dis‐
166       play item types.
167
168       pathName addchild parentPath ?option value ... ?
169              Adds a new child entry to the children list of  the  list  entry
170              identified  by  parentPath.  Or,  if parentPath is set to be the
171              empty string, then creates a new toplevel entry. The name of the
172              new  list entry will be a unique name automatically generated by
173              the HList widget. Usually if parentPath is foo, then the  entry‐
174              Path  of the new entry will be foo.1, foo.2, ... etc.  This com‐
175              mand returns the entryPath of  the  newly  created  list  entry.
176              option can be any option for the add widget command.
177
178       pathName anchor set entryPath
179              Sets  the anchor to the list entry identified by entryPath.  The
180              anchor is the end of the selection that is fixed while the  user
181              is dragging out a selection with the mouse.
182
183       pathName anchor clear
184              Removes  the  anchor,  if any, from this HList widget. This only
185              removes the surrounding highlights of the anchor entry and  does
186              not affect its selection status.
187
188       pathName cget option
189              Returns  the  current value of the configuration option given by
190              option. Option may have any of the values accepted by the  tixH‐
191              List command.
192
193       pathName column width col ?-char? ?width?
194              Querys  or  sets the width of a the column col in the HList wid‐
195              get. The value of col is zero-based: 0 stands for the first col‐
196              umn,  1  stands for the second, and so on. If no further parame‐
197              ters are given, returns the current width  of  this  column  (in
198              number of pixels). Additional parameters can be given to set the
199              width of this column:
200
201              pathName column width col {}
202                     An empty string indicates that the width  of  the  column
203                     should  be just wide enough to display the widest element
204                     in this column. In this case, the width  of  this  column
205                     may  change  as  a  result of the elements in this column
206                     changing their sizes.
207
208              pathName column width col width
209                     width must be in a form accepted by Tk_GetPixels(3).
210
211              pathName column width col -char nChars
212                     The width is set to be  the  average  width  occupied  by
213                     nChars  number of characters of the font specified by the
214                     -font option of this HList widget.
215
216       pathName configure ?option? ?value option value ...?
217              Query or modify the configuration options of the widget.  If  no
218              option is specified, returns a list describing all of the avail‐
219              able options for pathName (see Tk_ConfigureInfo for  information
220              on  the  format  of  this  list). If option is specified with no
221              value, then the command returns a list describing the one  named
222              option (this list will be identical to the corresponding sublist
223              of the value returned if no option is  specified).   If  one  or
224              more option-value pairs are specified, then the command modifies
225              the given widget option(s) to have the given value(s);  in  this
226              case  the  command returns an empty string.  Option may have any
227              of the values accepted by the tixHList command.
228
229       pathName delete option ?entryPath?
230              Delete one or more list entries. option may be one of  the  fol‐
231              lowing:
232
233              all    Delete  all entries in the HList. In this case the entry‐
234                     Path does not need to be specified.
235
236              entry  Delete the entry specified by entryPath and all its  off‐
237                     springs, if any.
238
239              offsprings
240                     Delete all the offsprings, if any, of the entry specified
241                     by entryPath. However, entryPath itself is not deleted.
242
243              siblings
244                     Delete all the list entries that share  the  same  parent
245                     with the entry specified by entryPath. However, entryPath
246                     itself is not deleted.
247
248       pathName dragsite set entryPath
249              Sets the dragsite to the list entry identified by entryPath. The
250              dragsite  is  used  to  indicate  the  source of a drag-and-drop
251              action.  Currently  drag-and-drop  functionality  has  not  been
252              implemented in Tix yet.
253
254       pathName dragsite clear
255              Remove  the  dragsite,  if any, from the this HList widget. This
256              only removes the surrounding highlights of  the  dragsite  entry
257              and does not affect its selection status.
258
259       pathName dropsite set entryPath
260              Sets the dropsite to the list entry identified by entryPath. The
261              dropsite is used to  indicate  the  target  of  a  grag-and-drop
262              action.  Currently  drag-and-drop  functionality  has  not  been
263              implemented in Tix yet.
264
265       pathName dropsite clear
266              Remove the dropsite, if any, from the this  HList  widget.  This
267              only  removes  the  surrounding highlights of the dropsite entry
268              and does not affect its selection status.
269
270       pathName entrycget  entryPath option
271              Returns the current value of the configuration option  given  by
272              option  for  the  entry indentfied by entryPath. Option may have
273              any of the values accepted by the add widget command.
274
275       pathName entryconfigure entryPath ?option? ?value option value ...?
276              Query or modify the configuration  options  of  the  list  entry
277              indentfied  by  entryPath.  If no option is specified, returns a
278              list describing all of the available options for entryPath  (see
279              Tk_ConfigureInfo for information on the format of this list.) If
280              option is specified with no value, then the  command  returns  a
281              list  describing the one named option (this list will be identi‐
282              cal to the corresponding sublist of the  value  returned  if  no
283              option  is  specified).  If  one  or more option-value pairs are
284              specified, then the command modifies the given option(s) to have
285              the  given  value(s);  in this case the command returns an empty
286              string.  Option may have any of the values accepted by  the  add
287              or  addchild widget command. The exact set of options depends on
288              the value of the -itemtype option passed to the the add or  add‐
289              child widget command when this list entry is created.
290
291       pathName header option col ?args ...?
292              Manipulates  the  header  items  of  this  HList  widget. If the
293              -header option of this HList widget  is  set  to  true,  then  a
294              header  item  is  displayed  at  the top of each column. The col
295              argument for this command must be a valid integer.  0  indicates
296              the  first column, 1 the second column, ... and so on. This com‐
297              mand supports the following options:
298
299              pathName header cget col option
300                     If the col-th column has a header display  item,  returns
301                     the  value of the specified option of the header item. If
302                     the header doesn't exist, returns an error.
303
304              pathName header configure col ?option? ?value option value ...?
305                     Query or modify the configuration options of  the  header
306                     display  item  of the col-th column. The header item must
307                     exist, or an error will result.  If no option  is  speci‐
308                     fied,  returns  a  list  describing  all of the available
309                     options for the header display  item  (see  Tk_Configure‐
310                     Info(3)  for  information on the format of this list.) If
311                     option is specified  with  no  value,  then  the  command
312                     returns a list describing the one named option (this list
313                     will be identical to the  corresponding  sublist  of  the
314                     value returned if no option is specified). If one or more
315                     option-value pairs are specified, then the command  modi‐
316                     fies  the  given option(s) to have the given value(s); in
317                     this case the command returns an empty string. Option may
318                     have any of the values accepted by the header create wid‐
319                     get command. The exact set  of  options  depends  on  the
320                     value  of  the  -itemtype option passed to the the header
321                     create widget command when this display item was created.
322
323              pathName header create col ?-itemtype type? ?option value ...?
324                     Creates a new display item as the header for  the  col-th
325                     column. If an header display item already exists for this
326                     column, it will be replaced by the new item.  An optional
327                     parameter  -itemtype  can be used to specify what type of
328                     display item should be created. If the -itemtype  is  not
329                     given,  then  by default the type specified by this HList
330                     widget's -itemtype option is used. Additional parameters,
331                     in  option-value  pairs,  can  be passed to configure the
332                     appearance of the display item.  Each  option-value  pair
333                     must  be  a valid option for this type of display item or
334                     one of the following:
335
336                     -borderwidth
337                            Specifies the border width of this header item.
338
339                     -headerbackground
340                            Specifies the  background  color  of  this  header
341                            item.
342
343                     -relief
344                            Specifies  the  relief  type of the border of this
345                            header item.
346
347              pathName header delete col
348                     Deletes the header display item for the col-th column.
349
350              pathName header exists col
351                     Return true if an header display item exists for the col-
352                     th column; return false otherwise.
353
354              pathName header size entryPath
355                     If  an header display item exists for the col-th column ,
356                     returns its size in a two element list of the form {width
357                     height}; returns an error if the header display item does
358                     not exist.
359
360       pathName hide option ?entryPath?
361              Makes some of entries invisible invisible without deleting them.
362              Option can be one of the following:
363
364              entry  Hides the list entry identified by entryPath.
365
366              Currently only the entry option is supported. Other options will
367              be added in the next release.
368
369       pathName indicator option entryPath ?args ...?
370              Manipulates the indicator on the list entries. An  indicator  is
371              usually  a  small  display  item (such as an image) that is dis‐
372              played to the left to an entry to indicate  the  status  of  the
373              entry. For example, it may be used to indicator whether a direc‐
374              tory is opened or closed. option can be one of the following:
375
376              pathName indicator cget entryPath option
377                     If the list entry given by entryPath  has  an  indicator,
378                     returns  the value of the specified option of the indica‐
379                     tor. If the indicator doesn't exist, returns an error.
380
381              pathName indicator configure entryPath  ?option?  ?value  option
382              value ...?
383                     Query  or modify the configuration options of the indica‐
384                     tor display item of the entry specified by entryPath. The
385                     indicator  item  must exist, or an error will result.  If
386                     no option is specified, returns a list describing all  of
387                     the available options for the indicator display item (see
388                     Tk_ConfigureInfo(3) for information on the format of this
389                     list).  If  option  is  specified with no value, then the
390                     command returns a list describing the  one  named  option
391                     (this list will be identical to the corresponding sublist
392                     of the value returned if no option is specified). If  one
393                     or  more  option-value pairs are specified, then the com‐
394                     mand modifies the  given  option(s)  to  have  the  given
395                     value(s);  in  this  case  the  command  returns an empty
396                     string.  Option may have any of the  values  accepted  by
397                     the  indicator  create  widget  command. The exact set of
398                     options depends on the  value  of  the  -itemtype  option
399                     passed  to  the  the indicator create widget command when
400                     this display item was created.
401
402              pathName indicator create  entryPath  ?-itemtype  type?  ?option
403              value ...?
404                     Creates a new display item as the indicator for the entry
405                     specified by entryPath.  If  an  indicator  display  item
406                     already exists for this entry, it will be replaced by the
407                     new item.  An optional parameter -itemtype can be used to
408                     specify  what  type of display item should be created. If
409                     the -itemtype is not given,  then  by  default  the  type
410                     specified  by  this  HList  widget's  -itemtype option is
411                     used. Additional parameters, in option-value  pairs,  can
412                     be  passed  to  configure  the  appearance of the display
413                     item. Each option-value pair must be a valid  option  for
414                     this type of display item.
415
416              pathName indicator delete entryPath
417                     Deletes the indicator display item for the entry given by
418                     entryPath.
419
420              pathName indicator exists entryPath
421                     Return true if an indicator display item exists  for  the
422                     entry given by entryPath; return false otherwise.
423
424              pathName indicator size entryPath
425                     If  an  indicator display item exists for the entry given
426                     by entryPath, returns its size in a two element  list  of
427                     the  form {width height}; returns an error if the indica‐
428                     tor display item does not exist.
429
430       pathName info option arg ...
431              Query information about the HList widget. option can be  one  of
432              the following:
433
434              pathName info anchor
435                     Returns  the  entryPath of the current anchor, if any, of
436                     the HList widget. If the anchor is not set,  returns  the
437                     empty string.
438
439              pathName info bbox entryPath
440                     Returns  a  list  of  four numbers describing the visible
441                     bounding box of the entry given entryPath. The first  two
442                     elements  of the list give the x and y coordinates of the
443                     upper-left corner of the screen area covered by the entry
444                     (specified in pixels relative to the widget) and the last
445                     two elements give the lower-right corner of the area,  in
446                     pixels. If no part of the entry given by index is visible
447                     on the screen then the result is an empty string; if  the
448                     entry is partially visible, the result gives the only the
449                     visible area of the entry.
450
451              pathName info children ?entryPath?
452                     If entrpyPath is given, returns a list of the entryPath's
453                     of  its children entries. Otherwise returns a list of the
454                     toplevel entryPath's.
455
456              pathName info data ?entryPath?
457                     Returns the data associated with entryPath.
458
459              pathName info dragsite
460                     Returns the entryPath of the current dragsite, if any, of
461                     the HList widget. If the dragsite is not set, returns the
462                     empty string.
463
464              pathName info dropsite
465                     Returns the entryPath of the current dropsite, if any, of
466                     the HList widget. If the dropsite is not set, returns the
467                     empty string.
468
469              pathName info exists entryPath
470                     Returns a boolean value indicating whether the list entry
471                     entrpyPath exists.
472
473              pathName info hidden entryPath
474                     Returns a boolean value indicating whether the list entry
475                     entrpyPath is hidden or not.
476
477              pathName info next entryPath
478                     Returns the entryPath of the list entry, if any,  immedi‐
479                     ately  below this list entry. If this entry is already at
480                     the bottom of the HList widget, returns an empty string.
481
482              pathName info parent entryPath
483                     Returns the name of the parent of the list entry  identi‐
484                     fied  by  entrpyPath.  If  entrpyPath  is a toplevel list
485                     entry, returns the empty string.
486
487              pathName info prev entryPath
488                     Returns the entryPath of the list entry, if any,  immedi‐
489                     ately  above this list entry. If this entry is already at
490                     the top of the HList widget, returns an empty string.
491
492              pathName info selection
493                     Returns a list of selected entries in the  HList  widget.
494                     If no entries are selectd, returns an empty string.
495
496       pathName item option ?args ...?
497              Creates  and  configures the display items at individual columns
498              the entries. The form of additional of arguments depends on  the
499              choice of option:
500
501              pathName item cget entryPath col option
502                     Returns  the current value of the configure option of the
503                     display item at the column designated by col of the entry
504                     specified by entryPath.
505
506              pathName  item  configure  entryPath  col ?option? ?value option
507              value ...?
508                     Query or modify the configuration options of the  display
509                     item  at the column designated by col of the entry speci‐
510                     fied by entryPath. If no option is specified,  returns  a
511                     list  describing  all of the available options for entry‐
512                     Path (see Tk_ConfigureInfo(3) for information on the for‐
513                     mat  of this list). If option is specified with no value,
514                     then the command returns a list describing the one  named
515                     option  (this list will be identical to the corresponding
516                     sublist of the value returned if no option is specified).
517                     If one or more option-value pairs are specified, then the
518                     command modifies the given option(s) to  have  the  given
519                     value(s);  in  this  case  the  command  returns an empty
520                     string.  Option may have any of the  values  accepted  by
521                     the  item create widget command. The exact set of options
522                     depends on the value of the -itemtype  option  passed  to
523                     the the item create widget command when this display item
524                     was created.
525
526              pathName item create  entryPath  col  ?-itemtype  type?  ?option
527              value ...?
528                     Creates  a  new  display item at the column designated by
529                     col of the entry  specified  by  entryPath.  An  optional
530                     parameter  -itemtype  can be used to specify what type of
531                     display items should be created. If the -itemtype is  not
532                     specified,  then  by  default  the type specified by this
533                     HList widget's  -itemtype  option  is  used.   Additional
534                     parameters,  in option-value pairs, can be passed to con‐
535                     figure the appearance of the display item.  Each  option-
536                     value  pair  must be a valid option for this type of dis‐
537                     play item.
538
539              pathName item delete entryPath col
540                     Deletes the display item at the column designated by  col
541                     of the entry specified by entryPath.
542
543              pathName item exists entryPath col
544                     Returns  true  if  there  is a display item at the column
545                     designated by col of the entry  specified  by  entryPath;
546                     returns false otherwise.
547
548       pathName nearest y
549              Given  a  y-coordinate  within  the  HList  window, this command
550              returns the entryPath of the (visible) HList element nearest  to
551              that y-coordinate.
552
553       pathName see entryPath
554              Adjust  the  view in the HList so that the entry given by entry‐
555              Path is visible. If the entry is already visible then  the  com‐
556              mand  has no effect; if the entry is near one edge of the window
557              then the HList scrolls to bring the element  into  view  at  the
558              edge; otherwise the HList widget scrolls to center the entry.
559
560       pathName selection option arg ...
561              This command is used to adjust the selection within a HList wid‐
562              get. It has several forms, depending on option:
563
564              pathName selection clear ?from? ?to?
565                     When no extra arguments are given, deselects all  of  the
566                     list  entrie(s)  in  this HList widget. When only from is
567                     given, only the list entry identified by  from  is  dese‐
568                     lected. When both from and to are given, deselects all of
569                     the list entrie(s) between between from  and  to,  inclu‐
570                     sive,  without  affecting  the selection state of entries
571                     outside that range.
572
573              pathName selection get
574                     This is an alias for the info selection  widget  command.
575                     ,
576
577              pathName selection includes entryPath
578                     Returns  1  if  the  list entry indicated by entryPath is
579                     currently selected; returns 0 otherwise.
580
581              pathName selection set from ?to?
582                     Selects all of the list entrie(s)  between  between  from
583                     and  to, inclusive, without affecting the selection state
584                     of entries outside that range. When only from  is  given,
585                     only the list entry identified by from is selected.
586
587       pathName show option ?entryPath?
588              Show the entries that are hidden by the hide command, option can
589              be one of the following:
590
591              entry  Shows the list entry identified by entryPath.
592
593              Currently only the entry option is supported. Other options will
594              be added in future releases.
595
596       pathName xview args
597              This command is used to query and change the horizontal position
598              of the information in the widget's window. It can  take  any  of
599              the following forms:
600
601              pathName xview
602                     Returns  a list containing two elements.  Each element is
603                     a real fraction between 0 and 1; together  they  describe
604                     the  horizontal  span that is visible in the window.  For
605                     example, if the first element is .2 and the  second  ele‐
606                     ment  is  .6, 20% of the HList entry is off-screen to the
607                     left, the middle 40% is visible in the window, and 40% of
608                     the  entry is off-screen to the right. These are the same
609                     values  passed  to  scrollbars  via  the  -xscrollcommand
610                     option.
611
612              pathName xview entryPath
613                     Adjusts  the  view  in  the window so that the list entry
614                     identified by entryPath is aligned to the  left  edge  of
615                     the window.
616
617              pathName xview moveto fraction
618                     Adjusts  the  view  in the window so that fraction of the
619                     total width of the HList is off-screen to the left. frac‐
620                     tion must be a fraction between 0 and 1.
621
622              pathName xview scroll number what
623                     This  command shifts the view in the window left or right
624                     according to number and what. Number must be an  integer.
625                     What  must be either units or pages or an abbreviation of
626                     one of these. If what is units, the view adjusts left  or
627                     right by number character units (the width of the 0 char‐
628                     acter) on the display; if  it  is  pages  then  the  view
629                     adjusts  by number screenfuls. If number is negative then
630                     characters farther to the left become visible; if  it  is
631                     positive then characters farther to the right become vis‐
632                     ible.
633
634       pathName yview ?args?
635              This command is used to query and change the  vertical  position
636              of  the  entries  in the widget's window. It can take any of the
637              following forms:
638
639              pathName yview
640                     Returns a list containing two elements, both of which are
641                     real  fractions between 0 and 1.  The first element gives
642                     the position of the list element at the top of  the  win‐
643                     dow,  relative  to  the HList as a whole (0.5 means it is
644                     halfway through the HList, for example).  The second ele‐
645                     ment  gives the position of the list entry just after the
646                     last one in the window, relative to the HList as a whole.
647                     These  are  the  same values passed to scrollbars via the
648                     -yscrollcommand option.
649
650              pathName yview entryPath
651                     Adjusts the view in the window so  that  the  list  entry
652                     given by entryPath is displayed at the top of the window.
653
654              pathName yview moveto fraction
655                     Adjusts  the  view  in  the window so that the list entry
656                     given by fraction appears at the top of the window. Frac‐
657                     tion is a fraction between 0 and 1; 0 indicates the first
658                     entry in the HList, 0.33 indicates  the  entry  one-third
659                     the way through the HList, and so on.
660
661              pathName yview scroll number what
662                     This  command  adjust  the  view in the window up or down
663                     according to number and what.  Number must be an integer.
664                     What  must  be  either units or pages.  If what is units,
665                     the view adjusts up or down by number  lines;  if  it  is
666                     pages  then  the  view  adjusts by number screenfuls.  If
667                     number is negative then earlier entries  become  visible;
668                     if it is positive then later entries become visible.
669

BINDINGS

671       [1]    If  the  -selectmode  is "browse", when the user drags the mouse
672              pointer over the list entries, the entry under the pointer  will
673              be  highlighted and the -browsecmd procedure will be called with
674              one parameter, the entryPath of the highlighted entry. Only  one
675              entry  can be highlighted at a time. The -command procedure will
676              be called when the user double-clicks on a list entry.
677
678       [2]    If the -selectmode is "single", the entries will only  be  high‐
679              lighted by mouse <ButtonRelease-1> events. When a new list entry
680              is highlighted, the -browsecmd procedure will be called with one
681              parameter  indicating  the  highlighted list entry. The -command
682              procedure will be called when the user double-clicks on  a  list
683              entry.
684
685       [3]    If  the -selectmode is "multiple", when the user drags the mouse
686              pointer over the list entries, all the entries under the pointer
687              will  be  highlighted. However, only a contiguous region of list
688              entries can be selected. When the highlighted area  is  changed,
689              the -browsecmd procedure will be called with an undefined param‐
690              eter. It is the responsibility of the  -browsecmd  procedure  to
691              find out the exact highlighted selection in the HList. The -com‐
692              mand procedure will be called when the user double-clicks  on  a
693              list entry.
694
695       [4]    If  the -selectmode is "extended", when the user drags the mouse
696              pointer over the list entries, all the entries under the pointer
697              will  be  highlighted.  The user can also make disjointed selec‐
698              tions using <Control-ButtonPress-1>. When the  highlighted  area
699              is  changed,  the  -browsecmd  procedure  will be called with an
700              undefined parameter. It is the responsibility of the  -browsecmd
701              procedure  to  find  out  the exact highlighted selection in the
702              HList. The -command procedure will be called when the user  dou‐
703              ble-clicks on a list entry.
704
705       [5]    Arrow key bindings: <Up> arrow key moves the anchor point to the
706              item right on top of the current anchor item. <Down>  arrow  key
707              moves  the  anchor  point  to  the  item right below the current
708              anchor item.  <Left> arrow key moves the anchor  to  the  parent
709              item of the current anchor item. <Right> moves the anchor to the
710              first child of the current anchor item. If  the  current  anchor
711              item  does  not  have any children, moves the anchor to the item
712              right below the current anchor item.
713

EXAMPLE

715       This example demonstrates how to use an HList to store a file directory
716       structure and respond to the user's browse events:
717
718        tixHList .h -separator "/" -browsecmd browse -selectmode single \
719           -itemtype text
720        .h add /         -text /
721        .h add /home     -text /home
722        .h add /home/ioi -text /home/ioi
723        .h add /home/foo -text /home/foo
724        .h add /usr      -text /usr
725        .h add /usr/lib  -text /usr/lib
726        pack .h
727
728        proc browse {file} {
729            puts "$file browsed"
730        }
731

BUGS

733       The  fact  that  the  display item at column 0 is implicitly associated
734       with the whole entry is probably a design bug. This was done for  back‐
735       ward  compatibility purposes. The result is that there is a large over‐
736       lap between the item command  and  the  add,  addchild,  entrycget  and
737       entryconfigure  commands. Whenever multiple columns exist, the program‐
738       mer should use ONLY the item command to create and configure  the  dis‐
739       play  items  in each column; the add, addchild, entrycget and entrycon‐
740       figure should be used ONLY to create and configure entries.
741

KEYWORDS

743       Tix(n), Hierarchical Listbox
744
745
746
747
748Tix                                   4.0                          tixHList(n)
Impressum