1HList(3)              User Contributed Perl Documentation             HList(3)
2
3
4

NAME

6       Tk::HList - Create and manipulate Tix Hierarchial List widgets
7

SYNOPSIS

9       $hlist = $parent->HList(?options?);
10

STANDARD OPTIONS

12       -background    -borderwidth   -cursor   -exportselection
13       -foreground    -font     -height   -highlightcolor
14       -highlightthickness -relief   -selectbackground
15       -selectforeground   -xscrollcommand     -yscrollcommand -width
16
17       See Tk::options for details of the standard options.
18

WIDGET-SPECIFIC OPTIONS

20       Name:     browsecmd
21       Class:    BrowseCmd
22       Switch:   -browsecmd
23           Specifies a perl/Tk callback to be executed when the user browses
24           through the entries in the HList widget.
25
26       Name:     columns
27       Class:    Columns
28       Switch:   -columns
29           Specifies the number of columns in this HList widget. This option
30           can only be set during the creation of the HList widget and cannot
31           be changed subsequently.
32
33       Name:     command
34       Class:    Command
35       Switch:   -command
36           Specifies the perl/Tk callback to be executed when the user invokes
37           a list entry in the HList widget. Normally the user invokes a list
38           entry by double-clicking it or pressing the Return key.
39
40       Name:     drawBranch
41       Class:    DrawBranch
42       Switch:   -drawbranch
43           A Boolean value to specify whether branch line should be drawn to
44           connect list entries to their parents.
45
46       Name:     foreground
47       Class:    Foreground
48       Switch:   -foreground
49       Alias:    -fg
50           [OBSOLETE] Specifies the default foreground color for the list
51           entries.
52
53       Name:     gap
54       Class:    Gap
55       Switch:   -gap
56           [OBSOLETE] The default distance between the bitmap/image and the
57           text in list entries.
58
59       Name:     header
60       Class:    Header
61       Switch:   -header
62           A Boolean value specifying whether headers should be displayed for
63           this HList widget (see the header method below).
64
65       Name:     height
66       Class:    Height
67       Switch:   -height
68           Specifies the desired height for the window in number of
69           characters.
70
71       Name:     indent
72       Class:    Indent
73       Switch:   -indent
74           Specifies the amount of horizontal indentation between a list entry
75           and its children. Must be a valid screen distance value.
76
77       Name:     indicator
78       Class:    Indicator
79       Switch:   -indicator
80           Specifies whether the indicators should be displayed inside the
81           HList widget. See the indicator method below.
82
83       Name:     indicatorCmd
84       Class:    IndicatorCmd
85       Switch:   -indicatorcmd
86           Specifies a perl/Tk callback to be executed when the user
87           manipulates the indicator of an HList entry. The -indicatorcmd is
88           triggered when the user press or releases the mouse button over the
89           indicator in an HList entry. By default the perl/Tk callback
90           specified by -indicatorcmd is executed with two additional
91           arguments, the entryPath of the entry whose indicator has been
92           triggered and additional information about the event.  The
93           additional information is one of the following strings:  <Arm>,
94           <Disarm>, and <Activate>.
95
96       Name:     itemType
97       Class:    ItemType
98       Switch:   -itemtype
99           Specifies the default type of display item for this HList widget.
100           When you call the itemCreate, add and addchild methods, display
101           items of this type will be created if the -itemtype option is not
102           specified .
103
104       Name:     padX
105       Class:    Pad
106       Switch:   -padx
107           [OBSOLETE] The default horizontal padding for list entries.
108
109       Name:     padY
110       Class:    Pad
111       Switch:   -padx
112           [OBSOLETE] The default vertical padding for list entries.
113
114       Name:     selectBackground
115       Class:    SelectBackground
116       Switch:   -selectbackground
117           Specifies the background color for the selected list entries.
118
119       Name:     selectBorderWidth
120       Class:    BorderWidth
121       Switch:   -selectborderwidth
122           Specifies a non-negative value indicating the width of the 3-D
123           border to draw around selected items.  The value may have any of
124           the forms acceptable to Tk_GetPixels.
125
126       Name:     selectForeground
127       Class:    SelectForeground
128       Switch:   -selectforeground
129           Specifies the foreground color for the selected list entries.
130
131       Name:     selectMode
132       Class:    SelectMode
133       Switch:   -selectmode
134           Specifies one of several styles for manipulating the selection.
135           The value of the option may be arbitrary, but the default bindings
136           expect it to be either single, browse, multiple, or extended; the
137           default value is single.
138
139       Name:     sizeCmd
140       Class:    SizeCmd
141       Switch:   -sizecmd
142           Specifies a perl/Tk callback to be called whenever the HList widget
143           changes its size.  This method can be useful to implement ``user
144           scroll bars when needed'' features.
145
146       Name:     separator
147       Class:    Separator
148       Switch:   -separator
149           Specifies the character to used as the separator character when
150           intepreting the path-names of list entries. By default the
151           character "." is used.
152
153       Name:     width
154       Class:    Width
155       Switch:   -width
156           Specifies the desired width for the window in characters.
157

DESCRIPTION

159       The HList method creates a new window (given by the $widget argument)
160       and makes it into a HList widget.  Additional options, described above,
161       may be specified on the command line or in the option database to
162       configure aspects of the HList widget such as its cursor and relief.
163
164       The HList widget can be used to display any data that have a
165       hierarchical structure, for example, file system directory trees. The
166       list entries are indented and connected by branch lines according to
167       their places in the hierachy.
168
169       Each list entry is identified by an entryPath. The entryPath is a
170       sequence of entry names separated by the separator charactor (specified
171       by the -separator option). An entry name can be any string that does
172       not contain the separator charactor, or it can be the a string that
173       contains only one separator charactor.
174
175       For example, when "." is used as the separator charactor,
176       "one.two.three" is the entryPath for a list entry whose parent is
177       "one.two", whose parent is "one", which is a toplevel entry (has no
178       parents).
179
180       Another examples: ".two.three" is the entryPath for a list entry whose
181       parent is ".two", whose parent is ".", which is a toplevel entry.
182

DISPLAY ITEMS

184       Each list entry in an HList widget is associated with a display item.
185       The display item determines what visual information should be displayed
186       for this list entry. Please see Tk::DItem for a list of all display
187       items.  When a list entry is created by the itemCreate, add or addchild
188       widget methods, the type of its display item is determined by the
189       -itemtype option passed to these methods. If the -itemtype is omitted,
190       then by default the type specified by this HList widget's -itemtype
191       option is used.
192

WIDGET METHODS

194       The HList method creates a widget object.  This object supports the
195       configure and cget methods described in Tk::options which can be used
196       to enquire and modify the options described above.  The widget also
197       inherits all the methods provided by the generic Tk::Widget class.
198
199       The following additional methods are available HList widgets:
200
201       $hlist->add($entryPath ?,option=>value, ...?)
202           Creates a new list entry with the pathname $entryPath. A list entry
203           must be created after its parent is created (unless this entry is a
204           top-level entry, which has no parent).  See also "BUGS" below.
205           This method returns the entryPath of the newly created list entry.
206           The following configuration options can be given to configure the
207           list entry:
208
209           -at => position
210                   Insert the new list at the position given by position.
211                   position must be a valid integer. The position 0 indicates
212                   the first position, 1 indicates the second position, and so
213                   on.
214
215           -after => afterWhich
216                   Insert the new list entry after the entry identified by
217                   afterWhich. afterWhich must be a valid list entry and it
218                   mush have the same parent as the new list entry
219
220           -before => beforeWhich
221                   Insert the new list entry before the entry identified by
222                   beforeWhich. beforeWhich must be a valid list entry and it
223                   mush have the same parent as the new list entry
224
225           -data => string
226                   Specifies a string to associate with this list entry. This
227                   string can be queried by the info method. The application
228                   programmer can use the -data option to associate the list
229                   entry with the data it represents.
230
231           -itemtype => type
232                   Specifies the type of display item to be display for the
233                   new list entry. type must be a valid display item type.
234                   Currently the available display item types are imagetext,
235                   text, and $widget. If this option is not specified, then by
236                   default the type specified by this HList widget's -itemtype
237                   option is used.
238
239           -state => state
240                   Specifies whether this entry can be selected or invoked by
241                   the user.  Must be either normal or disabled.
242
243           The add method accepts additional configuration options to
244           configure the display item associated with this list entry. The set
245           of additional configuration options depends on the type of the
246           display item given by the -itemtype option. Please see Tk::DItem
247           for a list of the configuration options for each of the display
248           item types.
249
250       $hlist->addchild($parentPath, ?option, value, ..., ?)
251           Adds a new child entry to the children list of the list entry
252           identified by $parentPath. Or, if $parentPath is set to be the
253           empty string, then creates a new toplevel entry. The name of the
254           new list entry will be a unique name automatically generated by the
255           HList widget. Usually if $parentPath is foo, then the entryPath of
256           the new entry will be foo.0, foo.1, ... etc.  This method returns
257           the entryPath of the newly created list entry.  option can be any
258           option for the add method.  See also "BUGS" below.
259
260       $hlist->anchorSet($entryPath)
261           Sets the anchor to the list entry identified by $entryPath.  The
262           anchor is the end of the selection that is fixed while the user is
263           dragging out a selection with the mouse.
264
265       $hlist->anchorClear
266           Removes the anchor, if any, from this HList widget. This only
267           removes the surrounding highlights of the anchor entry and does not
268           affect its selection status.
269
270       $hlist->columnWidth($col?, -char?, ?width?)
271           Querys or sets the width of a the column $col in the HList widget.
272           The value of $col is zero-based: 0 stands for the first column, 1
273           stands for the second, and so on. If no further parameters are
274           given, returns the current width of this column (in number of
275           pixels). Additional parameters can be given to set the width of
276           this column:
277
278           $hlist->columnWidth($col, '')
279                   An empty string indicates that the width of the column
280                   should be just wide enough to display the widest element in
281                   this column. In this case, the width of this column may
282                   change as a result of the elements in this column changing
283                   their sizes.
284
285           $hlist->columnWidth($col, width)
286                   width must be in a form accepted by Tk_GetPixels.
287
288           $hlist->columnWidth($col, -char, nChars)
289                   The width is set to be the average width occupied by nChars
290                   number of characters of the font specified by the -font
291                   option of this HList widget.
292
293       $hlist->delete(option, $entryPath)
294           Delete one or more list entries. option may be one of the
295           following:
296
297           all     Delete all entries in the HList. In this case the
298                   $entryPath does not need to be specified.
299
300           entry   Delete the entry specified by $entryPath and all its
301                   offsprings, if any.
302
303           offsprings
304                   Delete all the offsprings, if any, of the entry specified
305                   by $entryPath. However, $entryPath itself is not deleted.
306
307           siblings
308                   Delete all the list entries that share the same parent with
309                   the entry specified by $entryPath. However, $entryPath
310                   itself is not deleted.
311
312       $hlist->dragsiteSet($entryPath)
313           Sets the dragsite to the list entry identified by $entryPath. The
314           dragsite is used to indicate the source of a drag-and-drop action.
315           Currently drag-and-drop functionality has not been implemented in
316           Tix yet.
317
318       $hlist->dragsiteClear
319           Remove the dragsite, if any, from the this HList widget. This only
320           removes the surrounding highlights of the dragsite entry and does
321           not affect its selection status.
322
323       $hlist->dropsiteSet($entryPath)
324           Sets the dropsite to the list entry identified by $entryPath. The
325           dropsite is used to indicate the target of a drag-and-drop action.
326           Currently drag-and-drop functionality has not been implemented in
327           Tix yet.
328
329       $hlist->dropsiteClear
330           Remove the dropsite, if any, from the this HList widget. This only
331           removes the surrounding highlights of the dropsite entry and does
332           not affect its selection status.
333
334       $hlist->entrycget($entryPath, option)
335           Returns the current value of the configuration option given by
336           option for the entry indentfied by $entryPath. Option may have any
337           of the values accepted by the add method.
338
339       $hlist->entryconfigure($entryPath ?,option?, ?value=>option, ...?)
340           Query or modify the configuration options of the list entry
341           indentfied by $entryPath. If no option is specified, returns a list
342           describing all of the available options for $entryPath (see
343           Tk::options for information on the format of this list.) If option
344           is specified with no value, then the method returns a list
345           describing the one named option (this list will be identical to the
346           corresponding sublist of the value returned if no option is
347           specified). If one or more option-value pairs are specified, then
348           the method modifies the given option(s) to have the given value(s);
349           in this case the method returns an empty string.  Option may have
350           any of the values accepted by the add or addchild method. The exact
351           set of options depends on the value of the -itemtype option passed
352           to the the add or addchild method when this list entry is created.
353
354       $hlist->header(option, $col ?,args, ...?)
355           Manipulates the header items of this HList widget. If the -header
356           option of this HList widget is set to true, then a header item is
357           displayed at the top of each column. The $col argument for this
358           method must be a valid integer. 0 indicates the first column, 1 the
359           second column, ... and so on. This method supports the following
360           options:
361
362           $hlist->header(cget, $col, option)
363                   If the $col-th column has a header display item, returns
364                   the value of the specified option of the header item. If
365                   the header doesn't exist, returns an error.
366
367           $hlist->header(configure, $col, ?option?, ?value, option, value,
368           ...?)
369                   Query or modify the configuration options of the header
370                   display item of the $col-th column. The header item must
371                   exist, or an error will result.  If no option is specified,
372                   returns a list describing all of the available options for
373                   the header display item (see Tk::options for information on
374                   the format of this list.) If option is specified with no
375                   value, then the method returns a list describing the one
376                   named option (this list will be identical to the
377                   corresponding sublist of the value returned if no option is
378                   specified). If one or more option-value pairs are
379                   specified, then the method modifies the given option(s) to
380                   have the given value(s); in this case the method returns an
381                   empty string. Option may have any of the values accepted by
382                   the header create method. The exact set of options depends
383                   on the value of the -itemtype option passed to the the
384                   header create method when this display item was created.
385
386           $hlist->header(create, $col, ?-itemtype type? ?option value ...?
387                   Creates a new display item as the header for the $col-th
388                   column. See also "BUGS" below.  If an header display item
389                   already exists for this column, it will be replaced by the
390                   new item.  An optional parameter -itemtype can be used to
391                   specify what type of display item should be created. If the
392                   -itemtype is not given, then by default the type specified
393                   by this HList widget's -itemtype option is used. Additional
394                   parameters, in option-value pairs, can be passed to
395                   configure the appearance of the display item. Each option-
396                   value pair must be a valid option for this type of display
397                   item or one of the following:
398
399                   -borderwidth => color
400                               Specifies the border width of this header item.
401
402                   -headerbackground => color
403                               Specifies the background color of this header
404                               item.
405
406                   -relief => type
407                               Specifies the relief type of the border of this
408                               header item.
409
410           $hlist->header(delete, $col)
411                   Deletes the header display item for the $col-th column.
412
413           $hlist->header(exists, $col)
414                   Return true if an header display item exists for the
415                   $col-th column; return false otherwise.
416
417           $hlist->header(size, $col)
418                   If an header display item exists for the $col-th column ,
419                   returns its size in pixels in a two element list (width,
420                   height); returns an error if the header display item does
421                   not exist.
422
423       $hlist->hide(option ?,$entryPath?)
424           Makes some of entries invisible without deleting them.  Option can
425           be one of the following:
426
427           entry   Hides the list entry identified by $entryPath.
428
429           Currently only the entry option is supported. Other options will be
430           added in the next release.
431
432       $hlist->indicator(option, $entryPath, ?args, ...?)
433           Manipulates the indicator on the list entries. An indicator is
434           usually a small display item (such as an image) that is displayed
435           to the left to an entry to indicate the status of the entry.  For
436           example, it may be used to indicate whether a directory is opened
437           or closed.  Option can be one of the following:
438
439           $hlist->indicator(cget, $entryPath, option)
440                   If the list entry given by $entryPath has an indicator,
441                   returns the value of the specified option of the indicator.
442                   If the indicator doesn't exist, returns an error.
443
444           $hlist->indicator(configure, $entryPath, ?option?, ?value, option,
445           value, ...?)
446                   Query or modify the configuration options of the indicator
447                   display item of the entry specified by $entryPath. The
448                   indicator item must exist, or an error will result.  If no
449                   option is specified, returns a list describing all of the
450                   available options for the indicator display item (see
451                   Tk::options for information on the format of this list). If
452                   option is specified with no value, then the method returns
453                   a list describing the one named option (this list will be
454                   identical to the corresponding sublist of the value
455                   returned if no option is specified). If one or more option-
456                   value pairs are specified, then the method modifies the
457                   given option(s) to have the given value(s); in this case
458                   the method returns an empty string.  Option may have any of
459                   the values accepted by the indicator create method. The
460                   exact set of options depends on the value of the -itemtype
461                   option passed to the the indicator create method when this
462                   display item was created.
463
464           $hlist->indicator(create, $entryPath, ?, -itemtype type? ?option
465           value ...?)
466                   Creates a new display item as the indicator for the entry
467                   specified by $entryPath. If an indicator display item
468                   already exists for this entry, it will be replaced by the
469                   new item.  An optional parameter -itemtype can be used to
470                   specify what type of display item should be created. If the
471                   -itemtype is not given, then by default the type specified
472                   by this HList widget's -itemtype option is used. Additional
473                   parameters, in option-value pairs, can be passed to
474                   configure the appearance of the display item. Each option-
475                   value pair must be a valid option for this type of display
476                   item.
477
478           $hlist->indicator(delete, $entryPath)
479                   Deletes the indicator display item for the entry given by
480                   $entryPath.
481
482           $hlist->indicator(exists, $entryPath)
483                   Return true if an indicator display item exists for the
484                   entry given by $entryPath; return false otherwise.
485
486           $hlist->indicator(size, $entryPath)
487                   If an indicator display item exists for the entry given by
488                   $entryPath, returns its size in a two element list of the
489                   form {width height}; returns an error if the indicator
490                   display item does not exist.
491
492       $hlist->info(option, arg, ...)
493           Query information about the HList widget. option can be one of the
494           following:
495
496           $hlist->info(anchor)
497                   Returns the entryPath of the current anchor, if any, of the
498                   HList widget. If the anchor is not set, returns the empty
499                   string.
500
501           $hlist->infoBbox($entryPath)
502                   Returns a list of four numbers describing the visible
503                   bounding box of the entry given $entryPath. The first two
504                   elements of the list give the x and y coordinates of the
505                   upper-left corner of the screen area covered by the entry
506                   (specified in pixels relative to the widget) and the last
507                   two elements give the lower-right corner of the area, in
508                   pixels. If no part of the entry given by index is visible
509                   on the screen then the result is an empty string; if the
510                   entry is partially visible, the result gives the only the
511                   visible area of the entry.
512
513           $hlist->info(children ?,$entryPath?)
514                   If $entryPath is given, returns a list of the entryPath's
515                   of its children entries. Otherwise returns a list of the
516                   toplevel entryPath's.
517
518           $hlist->info(data ?,$entryPath?)
519                   Returns the data associated with $entryPath.
520
521           $hlist->info(dragsite)
522                   Returns the entryPath of the current dragsite, if any, of
523                   the HList widget. If the dragsite is not set, returns the
524                   empty string.
525
526           $hlist->info(dropsite)
527                   Returns the entryPath of the current dropsite, if any, of
528                   the HList widget. If the dropsite is not set, returns the
529                   empty string.
530
531           $hlist->info(exists, $entryPath)
532                   Returns a boolean value indicating whether the list entry
533                   $entryPath exists.
534
535           $hlist->info(hidden, $entryPath)
536                   Returns a boolean value indicating whether the list entry
537                   $entryPath is hidden or not.
538
539           $hlist->info(next, $entryPath)
540                   Returns the entryPath of the list entry, if any,
541                   immediately below this list entry. If this entry is already
542                   at the bottom of the HList widget, returns an empty string.
543
544           $hlist->info(parent, $entryPath)
545                   Returns the name of the parent of the list entry identified
546                   by $entryPath. If entryPath is a toplevel list entry,
547                   returns the empty string.
548
549           $hlist->info(prev, $entryPath)
550                   Returns the entryPath of the list entry, if any,
551                   immediately above this list entry. If this entry is already
552                   at the top of the HList widget, returns an empty string.
553
554           $hlist->info(selection)
555                   Returns a list of selected entries in the HList widget. In
556                   scalar context, returns an anonymous list of the selected
557                   entries.  If no entries are selected, undef is returned in
558                   scalar context, and an empty list otherwise.
559
560       $hlist->item(option, ?args, ...?)
561           Creates and configures the display items at individual columns the
562           entries. The form of additional of arguments depends on the choice
563           of option:
564
565           $hlist->itemCget($entryPath, $col, option)
566                   Returns the current value of the configure option of the
567                   display item at the column designated by $col of the entry
568                   specified by $entryPath.
569
570           $hlist->itemConfigure($entryPath, $col ?,option?, ?value, option,
571           value, ...?)
572                   Query or modify the configuration options of the display
573                   item at the column designated by $col of the entry
574                   specified by $entryPath. If no option is specified, returns
575                   a list describing all of the available options for
576                   $entryPath (see Tk::options for information on the format
577                   of this list). If option is specified with no value, then
578                   the method returns a list describing the one named option
579                   (this list will be identical to the corresponding sublist
580                   of the value returned if no option is specified). If one or
581                   more option-value pairs are specified, then the method
582                   modifies the given option(s) to have the given value(s); in
583                   this case the method returns an empty string.  Option may
584                   have any of the values accepted by the item create method.
585                   The exact set of options depends on the value of the
586                   -itemtype option passed to the the item create method when
587                   this display item was created.
588
589           $hlist->itemCreate($entryPath, $col ?,-itemtype=>type? ?,option
590           value ...?)
591                   Creates a new display item at the column designated by $col
592                   of the entry specified by $entryPath. An optional parameter
593                   -itemtype can be used to specify what type of display items
594                   should be created. If the -itemtype is not specified, then
595                   by default the type specified by this HList widget's
596                   -itemtype option is used.  Additional parameters, in
597                   option-value pairs, can be passed to configure the
598                   appearance of the display item. Each option- value pair
599                   must be a valid option for this type of display item.
600
601           $hlist->itemDelete($entryPath, $col)
602                   Deletes the display item at the column designated by $col
603                   of the entry specified by $entryPath.
604
605           $hlist->itemExists($entryPath, $col)
606                   Returns true if there is a display item at the column
607                   designated by $col of the entry specified by $entryPath;
608                   returns false otherwise.
609
610       $hlist->nearest(y)
611           $hlist->nearest(y) Given a y-coordinate within the HList window,
612           this method returns the entryPath of the (visible) HList element
613           nearest to that y-coordinate.
614
615       $hlist->see($entryPath)
616           Adjust the view in the HList so that the entry given by $entryPath
617           is visible. If the entry is already visible then the method has no
618           effect; if the entry is near one edge of the window then the HList
619           scrolls to bring the element into view at the edge; otherwise the
620           HList widget scrolls to center the entry.
621
622       $hlist->selection(option, arg, ...)
623       $hlist->selectionOption(arg, ...)
624           This method is used to adjust the selection within a HList widget.
625           It has several forms, depending on option:
626
627           $hlist->selectionClear(?from?, ?to?)
628                   When no extra arguments are given, deselects all of the
629                   list entrie(s) in this HList widget. When only from is
630                   given, only the list entry identified by from is
631                   deselected. When both from and to are given, deselects all
632                   of the list entrie(s) between between from and to,
633                   inclusive, without affecting the selection state of
634                   elements outside that range.
635
636           $hlist->selectionGet
637                   This is an alias for the infoSelection method.
638
639           $hlist->selectionIncludes($entryPath)
640                   Returns 1 if the list entry indicated by $entryPath is
641                   currently selected; returns 0 otherwise.
642
643           $hlist->selectionSet(from?, to?)
644                   Selects all of the list entrie(s) between between from and
645                   to, inclusive, without affecting the selection state of
646                   entries outside that range. When only from is given, only
647                   the list entry identified by from is selected.
648
649       $hlist->show(option ?,$entryPath?)
650           Show the entries that are hidden by the hide method, option can be
651           one of the following:
652
653           entry   Shows the list entry identified by $entryPath.
654
655           Currently only the entry option is supported. Other options will be
656           added in future releases.
657
658       $hlist->xview(args)
659           This method is used to query and change the horizontal position of
660           the information in the widget's window. It can take any of the
661           following forms:
662
663           $hlist->xview
664                   Returns a list containing two elements.  Each element is a
665                   real fraction between 0 and 1; together they describe the
666                   horizontal span that is visible in the window.  For
667                   example, if the first element is .2 and the second element
668                   is .6, 20% of the HList entry is off-screen to the left,
669                   the middle 40% is visible in the window, and 40% of the
670                   entry is off-screen to the right. These are the same values
671                   passed to scrollbars via the -xscrollcommand option.
672
673           $hlist->xview($entryPath)
674                   Adjusts the view in the window so that the list entry
675                   identified by $entryPath is aligned to the left edge of the
676                   window.
677
678           $hlist->xview(moveto => fraction)
679                   Adjusts the view in the window so that fraction of the
680                   total width of the HList is off-screen to the left.
681                   fraction must be a fraction between 0 and 1.
682
683           $hlist->xview(scroll => number, what)
684                   This method shifts the view in the window left or right
685                   according to number and what. Number must be an integer.
686                   What must be either units or pages or an abbreviation of
687                   one of these. If what is units, the view adjusts left or
688                   right by number character units (the width of the 0
689                   character) on the display; if it is pages then the view
690                   adjusts by number screenfuls. If number is negative then
691                   characters farther to the left become visible; if it is
692                   positive then characters farther to the right become
693                   visible.
694
695       $hlist->yview(?args?)
696           This method is used to query and change the vertical position of
697           the entries in the widget's window. It can take any of the
698           following forms:
699
700           $hlist->yview
701                   Returns a list containing two elements, both of which are
702                   real fractions between 0 and 1.  The first element gives
703                   the position of the list element at the top of the window,
704                   relative to the HList as a whole (0.5 means it is halfway
705                   through the HList, for example).  The second element gives
706                   the position of the list entry just after the last one in
707                   the window, relative to the HList as a whole.  These are
708                   the same values passed to scrollbars via the
709                   -yscrollcommand option.
710
711           $hlist->yview($entryPath)
712                   Adjusts the view in the window so that the list entry given
713                   by $entryPath is displayed at the top of the window.
714
715           $hlist->yview(moveto => fraction)
716                   Adjusts the view in the window so that the list entry given
717                   by fraction appears at the top of the window. Fraction is a
718                   fraction between 0 and 1; 0 indicates the first entry in
719                   the HList, 0.33 indicates the entry one-third the way
720                   through the HList, and so on.
721
722           $hlist->yview(scroll => number, what)
723                   This method adjust the view in the window up or down
724                   according to number and what.  Number must be an integer.
725                   What must be either units or pages.  If what is units, the
726                   view adjusts up or down by number lines; if it is pages
727                   then the view adjusts by number screenfuls.  If number is
728                   negative then earlier entries become visible; if it is
729                   positive then later entries become visible.
730

BINDINGS

732       [1] If the -selectmode is "browse", when the user drags the mouse
733           pointer over the list entries, the entry under the pointer will be
734           highlighted and the -browsecmd callback will be called with one
735           parameter, the entryPath of the highlighted entry. Only one entry
736           can be highlighted at a time. The -command callback will be called
737           when the user double-clicks on a list entry.
738
739       [2] If the -selectmode is "single", the entries will only be
740           highlighted by mouse <ButtonRelease-1> events. When a new list
741           entry is highlighted, the -browsecmd callback will be called with
742           one parameter indicating the highlighted list entry. The -command
743           callback will be called when the user double-clicks on a list
744           entry.
745
746       [3] If the -selectmode is "multiple", when the user drags the mouse
747           pointer over the list entries, all the entries under the pointer
748           will be highlighted. However, only a contiguous region of list
749           entries can be selected. When the highlighted area is changed, the
750           -browsecmd callback will be called with an undefined parameter. It
751           is the responsibility of the -browsecmd callback to find out the
752           exact highlighted selection in the HList. The -command callback
753           will be called when the user double-clicks on a list entry.
754
755       [4] If the -selectmode is "extended", when the user drags the mouse
756           pointer over the list entries, all the entries under the pointer
757           will be highlighted. The user can also make disjointed selections
758           using <Control-ButtonPress-1>. When the highlighted area is
759           changed, the -browsecmd callback will be called with an undefined
760           parameter. It is the responsibility of the -browsecmd callback to
761           find out the exact highlighted selection in the HList. The -command
762           callback will be called when the user double-clicks on a list
763           entry.
764
765       [5] Arrow key bindings: <Up> arrow key moves the anchor point to the
766           item right on top of the current anchor item. <Down> arrow key
767           moves the anchor point to the item right below the current anchor
768           item.  <Left> arrow key moves the anchor to the parent item of the
769           current anchor item. <Right> moves the anchor to the first child of
770           the current anchor item. If the current anchor item does not have
771           any children, moves the anchor to the item right below the current
772           anchor item.
773

EXAMPLE

775       This example demonstrates how to use an HList to store a file directory
776       structure and respond to the user's browse events:
777
778          use strict;
779          use Tk;
780          use Tk::Label;
781          use Tk::HList;
782
783          my $mw = MainWindow->new();
784          my $label = $mw->Label(-width=>15);
785          my $hlist = $mw->HList(
786                              -itemtype   => 'text',
787                              -separator  => '/',
788                              -selectmode => 'single',
789                              -browsecmd  => sub {
790                                        my $file = shift;
791                                        $label->configure(-text=>$file);
792                                     }
793                              );
794
795          foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) {
796              $hlist->add($_, -text=>$_);
797          }
798
799          $hlist->pack;
800          $label->pack;
801
802          MainLoop;
803

BUGS

805       The fact that the display item at column 0 is implicitly associated
806       with the whole entry is probably a design bug. This was done for
807       backward compatibility purposes. The result is that there is a large
808       overlap between the item method and the add, addchild, entrycget and
809       entryconfigure methods.  Whenever multiple columns exist, the
810       programmer should use ONLY the item method to create and configure the
811       display items in each column; the add, addchild, entrycget and
812       entryconfigure should be used ONLY to create and configure entries.
813

KEYWORDS

815       Hierarchical Listbox
816

SEE ALSO

818       Tk::DItem
819
820
821
822perl v5.36.0                      2023-01-20                          HList(3)
Impressum