1HList(3) User Contributed Perl Documentation HList(3)
2
6 Tk::HList - Create and manipulate Tix Hierarchial List widgets
7
9 $hlist = $parent->HList(?options?);
10
12 -background -borderwidth -cursor -exportselection
13 -foreground -font -height -highlightcolor
14 -highlightthickness -relief -selectbackground
15 -selectforeground -xscrollcommand -yscrollcommand -width
16 See Tk::options for details of the standard options.
18
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 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 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 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 Name: foreground
47 Class: Foreground
48 Switch: -foreground
49 Alias: -fg
50 [OBSOLETE] Specifies the default foreground color for the list
51 entries.
52 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 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 Name: height
66 Class: Height
67 Switch: -height
68 Specifies the desired height for the window in number of
69 characters.
70 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 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 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 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 Name: padX
105 Class: Pad
106 Switch: -padx
107 [OBSOLETE] The default horizontal padding for list entries.
108 Name: padY
110 Class: Pad
111 Switch: -padx
112 [OBSOLETE] The default vertical padding for list entries.
113 Name: selectBackground
115 Class: SelectBackground
116 Switch: -selectbackground
117 Specifies the background color for the selected list entries.
118 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 Name: selectForeground
127 Class: SelectForeground
128 Switch: -selectforeground
129 Specifies the foreground color for the selected list entries.
130 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 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 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 Name: width
154 Class: Width
155 Switch: -width
156 Specifies the desired width for the window in characters.
157
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 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 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 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 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
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
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 The following additional methods are available HList widgets:
200 $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 -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 -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 -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 -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 -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 -state => state
240 Specifies whether this entry can be selected or invoked by
241 the user. Must be either normal or disabled.
242 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 $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 $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 $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 $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 $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 $hlist->columnWidth($col, width)
286 width must be in a form accepted by Tk_GetPixels.
287 $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 $hlist->delete(option, $entryPath)
294 Delete one or more list entries. option may be one of the
295 following:
296 all Delete all entries in the HList. In this case the
298 $entryPath does not need to be specified.
299 entry Delete the entry specified by $entryPath and all its
301 offsprings, if any.
302 offsprings
304 Delete all the offsprings, if any, of the entry specified
305 by $entryPath. However, $entryPath itself is not deleted.
306 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 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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 -borderwidth => color
400 Specifies the border width of this header item.
401 -headerbackground => color
403 Specifies the background color of this header
404 item.
405 -relief => type
407 Specifies the relief type of the border of this
408 header item.
409 $hlist->header(delete, $col)
411 Deletes the header display item for the $col-th column.
412 $hlist->header(exists, $col)
414 Return true if an header display item exists for the
415 $col-th column; return false otherwise.
416 $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 $hlist->hide(option ?,$entryPath?)
424 Makes some of entries invisible without deleting them. Option can
425 be one of the following:
426 entry Hides the list entry identified by $entryPath.
428 Currently only the entry option is supported. Other options will be
430 added in the next release.
431 $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 $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 $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 $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 $hlist->indicator(delete, $entryPath)
479 Deletes the indicator display item for the entry given by
480 $entryPath.
481 $hlist->indicator(exists, $entryPath)
483 Return true if an indicator display item exists for the
484 entry given by $entryPath; return false otherwise.
485 $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 $hlist->info(option, arg, ...)
493 Query information about the HList widget. option can be one of the
494 following:
495 $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 $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 $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 $hlist->info(data ?,$entryPath?)
519 Returns the data associated with $entryPath.
520 $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 $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 $hlist->info(exists, $entryPath)
532 Returns a boolean value indicating whether the list entry
533 $entryPath exists.
534 $hlist->info(hidden, $entryPath)
536 Returns a boolean value indicating whether the list entry
537 $entryPath is hidden or not.
538 $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 $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 $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 $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 $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 $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 $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 $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 $hlist->itemDelete($entryPath, $col)
602 Deletes the display item at the column designated by $col
603 of the entry specified by $entryPath.
604 $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 $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 $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 $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 $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 $hlist->selectionGet
637 This is an alias for the infoSelection method.
638 $hlist->selectionIncludes($entryPath)
640 Returns 1 if the list entry indicated by $entryPath is
641 currently selected; returns 0 otherwise.
642 $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 $hlist->show(option ?,$entryPath?)
650 Show the entries that are hidden by the hide method, option can be
651 one of the following:
652 entry Shows the list entry identified by $entryPath.
654 Currently only the entry option is supported. Other options will be
656 added in future releases.
657 $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 $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 $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 $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 $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 $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 $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 $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 $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 $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
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 [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 [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 [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 [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
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 use strict;
779 use Tk;
780 use Tk::Label;
781 use Tk::HList;
782 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 foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) {
796 $hlist->add($_, -text=>$_);
797 }
798 $hlist->pack;
800 $label->pack;
801 MainLoop;
803
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
815 Hierarchical Listbox
816
818 Tk::DItem
819perl v5.16.3 2014-06-10 HList(3)