summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/HList.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/HList.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/HList.pod1050
1 files changed, 1050 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/HList.pod b/Master/tlpkg/tlperl/lib/Tk/HList.pod
new file mode 100644
index 00000000000..0843e689843
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/HList.pod
@@ -0,0 +1,1050 @@
+# Copyright (c) 1996, Expert Interface Technologies
+# See the file "license.terms" for information on usage and redistribution
+# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+#
+# The file man.macros and some of the macros used by this file are
+# copyrighted: (c) 1990 The Regents of the University of California.
+# (c) 1994-1995 Sun Microsystems, Inc.
+# The license terms of the Tcl/Tk distribution are in the file
+# license.tcl.
+
+=head1 NAME
+
+Tk::HList - Create and manipulate Tix Hierarchial List widgets
+
+=for category Tk Widget Classes
+
+=head1 SYNOPSIS
+
+I<$hlist> = I<$parent>-E<gt>B<HList>(?I<options>?);
+
+=head1 STANDARD OPTIONS
+
+B<-background> B<-borderwidth> B<-cursor> B<-exportselection>
+B<-foreground> B<-font> B<-height> B<-highlightcolor>
+B<-highlightthickness> B<-relief> B<-selectbackground>
+B<-selectforeground> B<-xscrollcommand> B<-yscrollcommand>
+B<-width>
+
+See L<Tk::options> for details of the standard options.
+
+=head1 WIDGET-SPECIFIC OPTIONS
+
+=over 4
+
+=item Name: B<browsecmd>
+
+=item Class: B<BrowseCmd>
+
+=item Switch: B<-browsecmd>
+
+Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user browses through the
+entries in the HList widget.
+
+=item Name: B<columns>
+
+=item Class: B<Columns>
+
+=item Switch: B<-columns>
+
+Specifies the number of columns in this HList widget. This option can
+only be set during the creation of the HList widget and cannot be
+changed subsequently.
+
+=item Name: B<command>
+
+=item Class: B<Command>
+
+=item Switch: B<-command>
+
+Specifies the perl/Tk L<callback|Tk::callbacks> to be executed when the user invokes a list
+entry in the HList widget. Normally the user invokes a list
+entry by double-clicking it or pressing the Return key.
+
+=item Name: B<drawBranch>
+
+=item Class: B<DrawBranch>
+
+=item Switch: B<-drawbranch>
+
+A Boolean value to specify whether branch line should be drawn to
+connect list entries to their parents.
+
+=item Name: B<foreground>
+
+=item Class: B<Foreground>
+
+=item Switch: B<-foreground>
+
+=item Alias: B<-fg>
+
+B<[OBSOLETE]> Specifies the default foreground color for the list entries.
+
+=item Name: B<gap>
+
+=item Class: B<Gap>
+
+=item Switch: B<-gap>
+
+B<[OBSOLETE]> The default distance between the bitmap/image and the
+text in list entries.
+
+=item Name: B<header>
+
+=item Class: B<Header>
+
+=item Switch: B<-header>
+
+A Boolean value specifying whether headers should be displayed for
+this HList widget (see the B<header> method below).
+
+=item Name: B<height>
+
+=item Class: B<Height>
+
+=item Switch: B<-height>
+
+Specifies the desired height for the window in number of characters.
+
+=item Name: B<indent>
+
+=item Class: B<Indent>
+
+=item Switch: B<-indent>
+
+Specifies the amount of horizontal indentation between a list entry
+and its children. Must be a valid screen distance value.
+
+=item Name: B<indicator>
+
+=item Class: B<Indicator>
+
+=item Switch: B<-indicator>
+
+Specifies whether the indicators should be displayed inside the HList
+widget. See the B<indicator> method below.
+
+=item Name: B<indicatorCmd>
+
+=item Class: B<IndicatorCmd>
+
+=item Switch: B<-indicatorcmd>
+
+Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user manipulates the
+indicator of an HList entry. The B<-indicatorcmd> is triggered
+when the user press or releases the mouse button over the indicator in
+an HList entry. By default the perl/Tk B<callback> specified by
+B<-indicatorcmd> is executed with two additional arguments, the
+entryPath of the entry whose indicator has been triggered and additional
+information about the event. The additional information is one of the
+following strings: B<E<lt>ArmE<gt>>, B<E<lt>DisarmE<gt>>,
+and B<E<lt>ActivateE<gt>>.
+
+=item Name: B<itemType>
+
+=item Class: B<ItemType>
+
+=item Switch: B<-itemtype>
+
+Specifies the default type of display item for this HList widget. When
+you call the B<itemCreate>, B<add> and B<addchild> methods, display
+items of this
+type will be created if the B<-itemtype> option is not specified .
+
+=item Name: B<padX>
+
+=item Class: B<Pad>
+
+=item Switch: B<-padx>
+
+B<[OBSOLETE]> The default horizontal padding for list entries.
+
+=item Name: B<padY>
+
+=item Class: B<Pad>
+
+=item Switch: B<-padx>
+
+B<[OBSOLETE]> The default vertical padding for list entries.
+
+=item Name: B<selectBackground>
+
+=item Class: B<SelectBackground>
+
+=item Switch: B<-selectbackground>
+
+Specifies the background color for the selected list entries.
+
+=item Name: B<selectBorderWidth>
+
+=item Class: B<BorderWidth>
+
+=item Switch: B<-selectborderwidth>
+
+Specifies a non-negative value indicating the width of the 3-D border
+to draw around selected items. The value may have any of the forms
+acceptable to B<Tk_GetPixels>.
+
+=item Name: B<selectForeground>
+
+=item Class: B<SelectForeground>
+
+=item Switch: B<-selectforeground>
+
+Specifies the foreground color for the selected list entries.
+
+=item Name: B<selectMode>
+
+=item Class: B<SelectMode>
+
+=item Switch: B<-selectmode>
+
+Specifies one of several styles for manipulating the selection. The
+value of the option may be arbitrary, but the default bindings expect
+it to be either B<single>, B<browse>, B<multiple>, or
+B<extended>; the default value is B<single>.
+
+=item Name: B<sizeCmd>
+
+=item Class: B<SizeCmd>
+
+=item Switch: B<-sizecmd>
+
+Specifies a perl/Tk L<callback|Tk::callbacks> to be called whenever the HList widget
+changes its size. This method can be useful to implement ``I<user scroll
+bars when needed>'' features.
+
+=item Name: B<separator>
+
+=item Class: B<Separator>
+
+=item Switch: B<-separator>
+
+Specifies the character to used as the separator character when
+intepreting the path-names of list entries. By default the character
+"." is used.
+
+=item Name: B<width>
+
+=item Class: B<Width>
+
+=item Switch: B<-width>
+
+Specifies the desired width for the window in characters.
+
+=back
+
+=head1 DESCRIPTION
+
+The B<HList> method creates a new window (given by the
+$widget argument) and makes it into a HList widget.
+Additional options, described above, may be specified on the command
+line or in the option database to configure aspects of the
+HList widget such as its cursor and relief.
+
+The HList widget can be used to display any data that have a
+hierarchical structure, for example, file system directory trees. The
+list entries are indented and connected by branch lines according to
+their places in the hierachy.
+
+Each list entry is identified by an B<entryPath>. The entryPath is a
+sequence of B<entry names> separated by the separator charactor
+(specified by the B<-separator> option). An B<entry name> can be
+any string that does not contain the separator charactor, or it can be
+the a string that contains only one separator charactor.
+
+For example, when "." is used as the separator charactor,
+"one.two.three" is the entryPath for a list entry whose parent is
+"one.two", whose parent is "one", which is a toplevel entry (has no
+parents).
+
+Another examples: ".two.three" is the entryPath for a list entry whose
+parent is ".two", whose parent is ".", which is a toplevel entry.
+
+=head1 DISPLAY ITEMS
+
+Each list entry in an HList widget is associated with a B<display>
+item. The display item determines what visual information should
+be displayed for this list entry. Please see L<Tk::DItem>
+for a list of all display items.
+When a list entry is created by the B<itemCreate>, B<add> or
+B<addchild> widget
+methods, the type of its display item is determined by the
+B<-itemtype> option passed to these methods. If the
+B<-itemtype> is omitted, then by default the type specified by
+this HList widget's B<-itemtype> option is used.
+
+=head1 WIDGET METHODS
+
+The B<HList> method creates a widget object.
+This object supports the B<configure> and B<cget> methods
+described in L<Tk::options> which can be used to enquire and
+modify the options described above.
+The widget also inherits all the methods provided by the generic
+L<Tk::Widget|Tk::Widget> class.
+
+The following additional methods are available HList widgets:
+
+=over 4
+
+=item I<$hlist>-E<gt>B<add>(I<$entryPath> ?,I<option>=E<gt>I<value>, ...?)
+
+Creates a new list entry with the pathname I<$entryPath>. A list
+entry must be created after its parent is created (unless this entry
+is a top-level entry, which has no parent). See also L<"BUGS"> below.
+This method returns the
+entryPath of the newly created list entry. The following
+configuration options can be given to configure the list entry:
+
+=over 8
+
+=item B<-at> =E<gt> I<position>
+
+Insert the new list at the position given by I<position>.
+I<position> must be a valid integer. The position B<0> indicates
+the first position, B<1> indicates the second position, and so on.
+
+=item B<-after> =E<gt> I<afterWhich>
+
+Insert the new list entry after the entry identified by
+I<afterWhich>. I<afterWhich> must be a valid list entry and it
+mush have the same parent as the new list entry
+
+=item B<-before> =E<gt> I<beforeWhich>
+
+Insert the new list entry before the entry identified by
+I<beforeWhich>. I<beforeWhich> must be a valid list entry and it
+mush have the same parent as the new list entry
+
+=item B<-data> =E<gt> I<string>
+
+Specifies a string to associate with this list entry. This string can
+be queried by the B<info> method. The application
+programmer can use the B<-data> option to associate the list entry
+with the data it represents.
+
+=item B<-itemtype> =E<gt> I<type>
+
+Specifies the type of display item to be display for the new list
+entry. B<type> must be a valid display item type. Currently the
+available display item types are B<imagetext>, B<text>, and
+$widget. If this option is not specified, then by default the
+type specified by this HList widget's B<-itemtype> option is used.
+
+=item B<-state> =E<gt> I<state>
+
+Specifies whether this entry can be selected or invoked by the user.
+Must be either B<normal> or B<disabled>.
+
+=back
+
+The B<add> method accepts additional configuration options
+to configure the display item associated with this list entry. The set
+of additional configuration options depends on the type of the display
+item given by the B<-itemtype> option. Please see
+L<Tk::DItem> for a list of the configuration options for
+each of the display item types.
+
+=item I<$hlist>-E<gt>B<addchild>(I<$parentPath, >?I<option, value, ..., >?)
+
+Adds a new child entry to the children list of the list entry
+identified by I<$parentPath>. Or, if I<$parentPath> is set to be
+the empty string, then creates a new toplevel entry. The name of the
+new list entry will be a unique name automatically generated by the
+HList widget. Usually if I<$parentPath> is B<foo>, then the
+entryPath of the new entry will be B<foo.0>, B<foo.1>, ... etc.
+This method returns the entryPath of the newly created list entry.
+I<option> can be any option for the B<add> method.
+See also L<"BUGS"> below.
+
+=item I<$hlist>-E<gt>B<anchorSet>(I<$entryPath>)
+
+Sets the anchor to the list entry identified by I<$entryPath>. The
+anchor is the end of the selection that is fixed while the user is
+dragging out a selection with the mouse.
+
+=item I<$hlist>-E<gt>B<anchorClear>
+
+Removes the anchor, if any, from this HList widget. This only
+removes the surrounding highlights of the anchor entry and does not
+affect its selection status.
+
+=item I<$hlist>-E<gt>B<columnWidth>(I<$col>?, I<-char>?, ?I<width>?)
+
+Querys or sets the width of a the column I<$col> in the HList
+widget. The value of I<$col> is zero-based: 0 stands for the first
+column, 1 stands for the second, and so on. If no further parameters
+are given, returns the current width of this column (in number of
+pixels). Additional parameters can be given to set the width of this
+column:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<columnWidth>(I<$col>, B<''>)
+
+An empty string indicates that the width of the column should be just
+wide enough to display the widest element in this column. In this
+case, the width of this column may change as a result of the elements
+in this column changing their sizes.
+
+=item I<$hlist>-E<gt>B<columnWidth>(I<$col, >I<width>)
+
+I<width> must be in a form accepted by B<Tk_GetPixels>.
+
+=item I<$hlist>-E<gt>B<columnWidth>(I<$col, >B<-char, >I<nChars>)
+
+The width is set to be the average width occupied by I<nChars>
+number of characters of the font specified by the B<-font> option
+of this HList widget.
+
+=back
+
+=item I<$hlist>-E<gt>B<delete>(I<option>, I<$entryPath>)
+
+Delete one or more list entries. I<option> may be one of the
+following:
+
+=over 8
+
+=item B<all>
+
+Delete all entries in the HList. In this case the I<$entryPath>
+does not need to be specified.
+
+=item B<entry>
+
+Delete the entry specified by I<$entryPath> and all its offsprings,
+if any.
+
+=item B<offsprings>
+
+Delete all the offsprings, if any, of the entry specified by
+I<$entryPath>. However, I<$entryPath> itself is not deleted.
+
+=item B<siblings>
+
+Delete all the list entries that share the same parent with the entry
+specified by I<$entryPath>. However, I<$entryPath> itself is not
+deleted.
+
+=back
+
+=item I<$hlist>-E<gt>B<dragsiteSet>(I<$entryPath>)
+
+Sets the dragsite to the list entry identified by
+I<$entryPath>. The dragsite is used to indicate the source of a
+drag-and-drop action. Currently drag-and-drop functionality has not
+been implemented in Tix yet.
+
+=item I<$hlist>-E<gt>B<dragsiteClear>
+
+Remove the dragsite, if any, from the this HList widget. This only
+removes the surrounding highlights of the dragsite entry and does not
+affect its selection status.
+
+=item I<$hlist>-E<gt>B<dropsiteSet>(I<$entryPath>)
+
+Sets the dropsite to the list entry identified by I<$entryPath>. The
+dropsite is used to indicate the target of a drag-and-drop
+action. Currently drag-and-drop functionality has not been implemented
+in Tix yet.
+
+=item I<$hlist>-E<gt>B<dropsiteClear>
+
+Remove the dropsite, if any, from the this HList widget. This only
+removes the surrounding highlights of the dropsite entry and does not
+affect its selection status.
+
+=item I<$hlist>-E<gt>B<entrycget>(I<$entryPath>, I<option>)
+
+Returns the current value of the configuration option given by
+I<option> for the entry indentfied by I<$entryPath>. I<Option>
+may have any of the values accepted by the B<add> method.
+
+=item I<$hlist>-E<gt>B<entryconfigure>(I<$entryPath> ?,I<option>?, ?I<value>=E<gt>I<option>, ...?)
+
+Query or modify the configuration options of the list entry indentfied
+by I<$entryPath>. If no I<option> is specified, returns a list
+describing all of the available options for I<$entryPath> (see
+L<Tk::options> for information on the format of this list.) If
+I<option> is specified with no I<value>, then the method
+returns a list describing the one named option (this list will be
+identical to the corresponding sublist of the value returned if no
+I<option> is specified). If one or more I<option-value> pairs
+are specified, then the method modifies the given option(s) to have
+the given value(s); in this case the method returns an empty string.
+I<Option> may have any of the values accepted by the B<add> or
+B<addchild> method. The exact set of options depends on the
+value of the B<-itemtype> option passed to the the B<add> or
+B<addchild> method when this list entry is created.
+
+=item I<$hlist>-E<gt>B<header>(I<option>, I<$col> ?,I<args>, ...?)
+
+Manipulates the header items of this HList widget. If the
+B<-header> option of this HList widget is set to true, then a
+header item is displayed at the top of each column. The I<$col>
+argument for this method must be a valid integer. 0 indicates the
+first column, 1 the second column, ... and so on. This method
+supports the following options:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<header>(B<cget>, I<$col>, I<option>)
+
+If the I<$col>-th column has a header display item, returns the
+value of the specified I<option> of the header item. If the header
+doesn't exist, returns an error.
+
+=item I<$hlist>-E<gt>B<header>(B<configure, >I<$col, >?I<option>?, I<?value, option, value, ...>?)
+
+Query or modify the configuration options of the header display item
+of the I<$col>-th column. The header item must exist, or an error
+will result. If no I<option> is specified, returns a list
+describing all of the available options for the header display item
+(see L<Tk::options> for information on the format of this
+list.) If I<option> is specified with no I<value>, then the
+method returns a list describing the one named option (this list will
+be identical to the corresponding sublist of the value returned if no
+I<option> is specified). If one or more I<option-value> pairs
+are specified, then the method modifies the given option(s) to have
+the given value(s); in this case the method returns an empty
+string. I<Option> may have any of the values accepted by the
+B<header create> method. The exact set of options depends
+on the value of the B<-itemtype> option passed to the the B<header>
+create method when this display item was created.
+
+=item I<$hlist>-E<gt>B<header>(B<create, >I<$col, >?I<-itemtype type>? ?I<option value ...>?
+
+Creates a new display item as the header for the I<$col>-th
+column. See also L<"BUGS"> below.
+If an header display item already exists for this column, it
+will be replaced by the new item. An optional parameter
+I<-itemtype> can be used to specify what type of display item
+should be created. If the I<-itemtype> is not given, then by
+default the type specified by this HList widget's B<-itemtype>
+option is used. Additional parameters, in I<option-value> pairs,
+can be passed to configure the appearance of the display item. Each
+I<option-value> pair must be a valid option for this type of
+display item or one of the following:
+
+=over 12
+
+=item B<-borderwidth> =E<gt> I<color>
+
+Specifies the border width of this header item.
+
+=item B<-headerbackground> =E<gt> I<color>
+
+Specifies the background color of this header item.
+
+=item B<-relief> =E<gt> I<type>
+
+Specifies the relief type of the border of this header item.
+
+=back
+
+=item I<$hlist>-E<gt>B<header>(B<delete, >I<$col>)
+
+Deletes the header display item for the I<$col>-th column.
+
+=item I<$hlist>-E<gt>B<header>(B<exists, >I<$col>)
+
+Return true if an header display item exists for the I<$col>-th
+column; return false otherwise.
+
+=item I<$hlist>-E<gt>B<header>(B<size>, I<$col>)
+
+If an header display item exists for the I<$col>-th column , returns
+its size in pixels in a two element list I<(width, height)>;
+returns an error if the header display item does not exist.
+
+=back
+
+=item I<$hlist>-E<gt>B<hide>(I<option> ?,I<$entryPath>?)
+
+Makes some of entries invisible without deleting them.
+I<Option> can be one of the following:
+
+=over 8
+
+=item B<entry>
+
+Hides the list entry identified by I<$entryPath>.
+
+=back
+
+Currently only the B<entry> option is supported. Other options will
+be added in the next release.
+
+=item I<$hlist>-E<gt>B<indicator>(I<option>, I<$entryPath>, ?I<args, ...>?)
+
+Manipulates the indicator on the list entries. An indicator is usually
+a small display item (such as an image) that is displayed to the left
+to an entry to indicate the status of the entry. For example, it may
+be used to indicate whether a directory is opened or
+closed. I<Option> can be one of the following:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<indicator>(B<cget>, I<$entryPath>, I<option>)
+
+If the list entry given by I<$entryPath> has an indicator, returns
+the value of the specified I<option> of the indicator. If the
+indicator doesn't exist, returns an error.
+
+=item I<$hlist>-E<gt>B<indicator>(B<configure>, I<$entryPath>, ?I<option>?, I<?value, option, value, ...>?)
+
+Query or modify the configuration options of the indicator display
+item of the entry specified by I<$entryPath>. The indicator item
+must exist, or an error will result. If no I<option> is specified,
+returns a list describing all of the available options for the
+indicator display item (see L<Tk::options> for information
+on the format of this list). If I<option> is specified with no
+I<value>, then the method returns a list describing the one named
+option (this list will be identical to the corresponding sublist of
+the value returned if no I<option> is specified). If one or more
+I<option-value> pairs are specified, then the method modifies the
+given option(s) to have the given value(s); in this case the method
+returns an empty string. I<Option> may have any of the values
+accepted by the B<indicator create> method. The exact set
+of options depends on the value of the B<-itemtype> option passed
+to the the B<indicator create> method when this display item
+was created.
+
+=item I<$hlist>-E<gt>B<indicator>(B<create, >I<$entryPath, >?, I<-itemtype type>? ?I<option value ...>?)
+
+Creates a new display item as the indicator for the entry specified by
+I<$entryPath>. If an indicator display item already exists for this
+entry, it will be replaced by the new item. An optional parameter
+I<-itemtype> can be used to specify what type of display item
+should be created. If the I<-itemtype> is not given, then by
+default the type specified by this HList widget's B<-itemtype>
+option is used. Additional parameters, in I<option-value> pairs,
+can be passed to configure the appearance of the display item. Each
+I<option-value> pair must be a valid option for this type of
+display item.
+
+=item I<$hlist>-E<gt>B<indicator>(B<delete>, I<$entryPath>)
+
+Deletes the indicator display item for the entry given by I<$entryPath>.
+
+=item I<$hlist>-E<gt>B<indicator>(B<exists>, I<$entryPath>)
+
+Return true if an indicator display item exists for the entry given by
+I<$entryPath>; return false otherwise.
+
+=item I<$hlist>-E<gt>B<indicator>(B<size>, I<$entryPath>)
+
+If an indicator display item exists for the entry given by
+I<$entryPath>, returns its size in a two element list of the form
+{I<width height>}; returns an error if the indicator display item
+does not exist.
+
+=back
+
+=item I<$hlist>-E<gt>B<info>(I<option>, I<arg, ...>)
+
+Query information about the HList widget. I<option> can be one
+of the following:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<info>(B<anchor>)
+
+Returns the entryPath of the current anchor, if any, of the HList
+widget. If the anchor is not set, returns the empty string.
+
+=item I<$hlist>-E<gt>B<infoBbox>(I<$entryPath>)
+
+Returns a list of four numbers describing the visible bounding box of
+the entry given I<$entryPath>. The first two elements of the list
+give the x and y coordinates of the upper-left corner of the screen
+area covered by the entry (specified in pixels relative to the widget)
+and the last two elements give the lower-right corner of the area, in
+pixels. If no part of the entry given by index is visible on the
+screen then the result is an empty string; if the entry is partially
+visible, the result gives the only the visible area of the entry.
+
+=item I<$hlist>-E<gt>B<info>(B<children> ?,I<$entryPath>?)
+
+If I<$entryPath> is given, returns a list of the entryPath's of its
+children entries. Otherwise returns a list of the toplevel
+entryPath's.
+
+=item I<$hlist>-E<gt>B<info>(B<data> ?,I<$entryPath>?)
+
+Returns the data associated with I<$entryPath>.
+
+=item I<$hlist>-E<gt>B<info>(B<dragsite>)
+
+Returns the entryPath of the current dragsite, if any, of the HList
+widget. If the dragsite is not set, returns the empty string.
+
+=item I<$hlist>-E<gt>B<info>(B<dropsite>)
+
+Returns the entryPath of the current dropsite, if any, of the HList
+widget. If the dropsite is not set, returns the empty string.
+
+=item I<$hlist>-E<gt>B<info>(B<exists>, I<$entryPath>)
+
+Returns a boolean value indicating whether the list entry
+I<$entryPath> exists.
+
+=item I<$hlist>-E<gt>B<info>(B<hidden>, I<$entryPath>)
+
+Returns a boolean value indicating whether the list entry
+B<$entryPath> is hidden or not.
+
+=item I<$hlist>-E<gt>B<info>(B<next>, I<$entryPath>)
+
+Returns the entryPath of the list entry, if any, immediately below
+this list entry. If this entry is already at the bottom of the HList
+widget, returns an empty string.
+
+=item I<$hlist>-E<gt>B<info>(B<parent>, I<$entryPath>)
+
+Returns the name of the parent of the list entry identified by
+I<$entryPath>. If I<entryPath> is a toplevel list entry,
+returns the empty string.
+
+=item I<$hlist>-E<gt>B<info>(B<prev>, I<$entryPath>)
+
+Returns the entryPath of the list entry, if any, immediately above
+this list entry. If this entry is already at the top of the HList
+widget, returns an empty string.
+
+=item I<$hlist>-E<gt>B<info>(B<selection>)
+
+Returns a list of selected entries in the HList widget. In scalar
+context, returns an anonymous list of the selected entries.
+If no entries are selected, undef is returned in scalar context, and
+an empty list otherwise.
+
+=back
+
+=item I<$hlist>-E<gt>B<item>(I<option, >?I<args, ...>?)
+
+Creates and configures the display items at individual columns the
+entries. The form of additional of arguments depends on the choice of
+I<option>:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<itemCget>(I<$entryPath>, I<$col>, I<option>)
+
+Returns the current value of the configure I<option> of the display
+item at the column designated by I<$col> of the entry specified by
+I<$entryPath>.
+
+=item I<$hlist>-E<gt>B<itemConfigure>(I<$entryPath>, I<$col> ?,I<option>?, I<?value, option, value, ...>?)
+
+Query or modify the configuration options of the display item at the
+column designated by I<$col> of the entry specified by
+I<$entryPath>. If no I<option> is specified, returns a list
+describing all of the available options for I<$entryPath> (see
+L<Tk::options> for information on the format of this
+list). If I<option> is specified with no I<value>, then the
+method returns a list describing the one named option (this list will
+be identical to the corresponding sublist of the value returned if no
+I<option> is specified). If one or more I<option-value> pairs
+are specified, then the method modifies the given option(s) to have
+the given value(s); in this case the method returns an empty string.
+I<Option> may have any of the values accepted by the B<item>
+create method. The exact set of options depends on the
+value of the B<-itemtype> option passed to the the B<item>
+create method when this display item was created.
+
+=item I<$hlist>-E<gt>B<itemCreate>(I<$entryPath>, I<$col> ?,I<-itemtype>=E<gt>I<type>? ?,I<option value ...>?)
+
+Creates a new display item at the column designated by I<$col> of
+the entry specified by I<$entryPath>. An optional parameter
+I<-itemtype> can be used to specify what type of display items
+should be created. If the I<-itemtype> is not specified, then by
+default the type specified by this HList widget's B<-itemtype>
+option is used. Additional parameters, in I<option-value> pairs,
+can be passed to configure the appearance of the display item. Each
+I<option- value> pair must be a valid option for this type of
+display item.
+
+=item I<$hlist>-E<gt>B<itemDelete>(I<$entryPath>, I<$col>)
+
+Deletes the display item at the column designated by I<$col> of
+the entry specified by I<$entryPath>.
+
+=item I<$hlist>-E<gt>B<itemExists>(I<$entryPath>, I<$col>)
+
+Returns true if there is a display item at the column designated by
+I<$col> of the entry specified by I<$entryPath>; returns false
+otherwise.
+
+=back
+
+=item I<$hlist>-E<gt>B<nearest>(I<y>)
+
+I<$hlist>-E<gt>B<nearest>(I<y>)
+Given a y-coordinate within the HList window, this method returns
+the entryPath of the (visible) HList element nearest to that
+y-coordinate.
+
+=item I<$hlist>-E<gt>B<see>(I<$entryPath>)
+
+Adjust the view in the HList so that the entry given by I<$entryPath> is
+visible. If the entry is already visible then the method has no
+effect; if the entry is near one edge of the window then the HList
+scrolls to bring the element into view at the edge; otherwise the
+HList widget scrolls to center the entry.
+
+=item I<$hlist>-E<gt>B<selection>(I<option>, I<arg>, ...)
+
+=item I<$hlist>-E<gt>B<selection>I<Option>(I<arg>, ...)
+
+This method is used to adjust the selection within a HList widget. It
+has several forms, depending on I<option>:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?)
+
+When no extra arguments are given, deselects all of the list entrie(s)
+in this HList widget. When only I<from> is given, only the list
+entry identified by I<from> is deselected. When both I<from> and
+I<to> are given, deselects all of the list entrie(s) between
+between I<from> and I<to>, inclusive, without affecting the
+selection state of elements outside that range.
+
+=item I<$hlist>-E<gt>B<selectionGet>
+
+This is an alias for the B<infoSelection> method.
+
+=item I<$hlist>-E<gt>B<selectionIncludes>(I<$entryPath>)
+
+Returns 1 if the list entry indicated by I<$entryPath> is currently
+selected; returns 0 otherwise.
+
+=item I<$hlist>-E<gt>B<selectionSet>(I<from>?, I<to>?)
+
+Selects all of the list entrie(s) between between I<from> and
+I<to>, inclusive, without affecting the selection state of entries
+outside that range. When only I<from> is given, only the list entry
+identified by I<from> is selected.
+
+=back
+
+=item I<$hlist>-E<gt>B<show>(I<option> ?,I<$entryPath>?)
+
+Show the entries that are hidden by the B<hide> method,
+I<option> can be one of the following:
+
+=over 8
+
+=item B<entry>
+
+Shows the list entry identified by I<$entryPath>.
+
+=back
+
+Currently only the B<entry> option is supported. Other options will
+be added in future releases.
+
+=item I<$hlist>-E<gt>B<xview>(I<args>)
+
+This method is used to query and change the horizontal position of the
+information in the widget's window. It can take any of the following
+forms:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<xview>
+
+Returns a list containing two elements. Each element is a real
+fraction between 0 and 1; together they describe the horizontal span
+that is visible in the window. For example, if the first element is
+.2 and the second element is .6, 20% of the HList entry is
+off-screen to the left, the middle 40% is visible in the window, and
+40% of the entry is off-screen to the right. These are the same values
+passed to scrollbars via the B<-xscrollcommand> option.
+
+=item I<$hlist>-E<gt>B<xview>(I<$entryPath>)
+
+Adjusts the view in the window so that the list entry identified by
+I<$entryPath> is aligned to the left edge of the window.
+
+=item I<$hlist>-E<gt>B<xview>(B<moveto> =E<gt> I<fraction>)
+
+Adjusts the view in the window so that I<fraction> of the total
+width of the HList is off-screen to the left. I<fraction> must be
+a fraction between 0 and 1.
+
+=item I<$hlist>-E<gt>B<xview>(B<scroll> =E<gt> I<number, what>)
+
+This method shifts the view in the window left or right according to
+I<number> and I<what>. I<Number> must be an integer.
+I<What> must be either B<units> or B<pages> or an
+abbreviation of one of these. If I<what> is B<units>, the view
+adjusts left or right by I<number> character units (the width of
+the B<0> character) on the display; if it is B<pages> then the
+view adjusts by I<number> screenfuls. If I<number> is negative
+then characters farther to the left become visible; if it is positive
+then characters farther to the right become visible.
+
+=back
+
+=item I<$hlist>-E<gt>B<yview>(I<?args>?)
+
+This method is used to query and change the vertical position of the
+entries in the widget's window. It can take any of the following forms:
+
+=over 8
+
+=item I<$hlist>-E<gt>B<yview>
+
+Returns a list containing two elements, both of which are real
+fractions between 0 and 1. The first element gives the position of
+the list element at the top of the window, relative to the HList as a
+whole (0.5 means it is halfway through the HList, for example). The
+second element gives the position of the list entry just after the
+last one in the window, relative to the HList as a whole. These are
+the same values passed to scrollbars via the B<-yscrollcommand>
+option.
+
+=item I<$hlist>-E<gt>B<yview>(I<$entryPath>)
+
+Adjusts the view in the window so that the list entry given by
+I<$entryPath> is displayed at the top of the window.
+
+=item I<$hlist>-E<gt>B<yview>(B<moveto> =E<gt> I<fraction>)
+
+Adjusts the view in the window so that the list entry given by
+I<fraction> appears at the top of the window. I<Fraction> is a
+fraction between 0 and 1; 0 indicates the first entry in the
+HList, 0.33 indicates the entry one-third the way through the
+HList, and so on.
+
+=item I<$hlist>-E<gt>B<yview>(B<scroll> =E<gt> I<number, what>)
+
+This method adjust the view in the window up or down according to
+I<number> and I<what>. I<Number> must be an integer.
+I<What> must be either B<units> or B<pages>. If I<what>
+is B<units>, the view adjusts up or down by I<number> lines; if
+it is B<pages> then the view adjusts by I<number> screenfuls.
+If I<number> is negative then earlier entries become visible; if
+it is positive then later entries become visible.
+
+=back
+
+=back
+
+=head1 BINDINGS
+
+=over 4
+
+=item [1]
+
+If the B<-selectmode> is "browse", when the user drags the mouse
+pointer over the list entries, the entry under the pointer will be
+highlighted and the B<-browsecmd> callback will be called with
+one parameter, the entryPath of the highlighted entry. Only one entry
+can be highlighted at a time. The B<-command> callback will be
+called when the user double-clicks on a list entry.
+
+=item [2]
+
+If the B<-selectmode> is "single", the entries will only be
+highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry
+is highlighted, the B<-browsecmd> callback will be called with
+one parameter indicating the highlighted list entry. The
+B<-command> callback will be called when the user double-clicks
+on a list entry.
+
+=item [3]
+
+If the B<-selectmode> is "multiple", when the user drags the mouse
+pointer over the list entries, all the entries under the pointer will
+be highlighted. However, only a contiguous region of list entries can
+be selected. When the highlighted area is changed, the
+B<-browsecmd> callback will be called with an undefined
+parameter. It is the responsibility of the B<-browsecmd> callback
+to find out the exact highlighted selection in the HList. The
+B<-command> callback will be called when the user double-clicks
+on a list entry.
+
+=item [4]
+
+If the B<-selectmode> is "extended", when the user drags the mouse
+pointer over the list entries, all the entries under the pointer will
+be highlighted. The user can also make disjointed selections using
+E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the
+B<-browsecmd> callback will be called with an undefined
+parameter. It is the responsibility of the B<-browsecmd> callback
+to find out the exact highlighted selection in the HList. The
+B<-command> callback will be called when the user double-clicks
+on a list entry.
+
+=item [5]
+
+B<Arrow key bindings:> E<lt>UpE<gt> arrow key moves the anchor point to the
+item right on top of the current anchor item. E<lt>DownE<gt> arrow key moves
+the anchor point to the item right below the current anchor item.
+E<lt>LeftE<gt> arrow key moves the anchor to the parent item of the current
+anchor item. E<lt>RightE<gt> moves the anchor to the first child of the
+current anchor item. If the current anchor item does not have any
+children, moves the anchor to the item right below the current anchor
+item.
+
+=back
+
+=head1 EXAMPLE
+
+This example demonstrates how to use an HList to store a file
+directory structure and respond to the user's browse events:
+
+ use strict;
+ use Tk;
+ use Tk::Label;
+ use Tk::HList;
+
+ my $mw = MainWindow->new();
+ my $label = $mw->Label(-width=>15);
+ my $hlist = $mw->HList(
+ -itemtype => 'text',
+ -separator => '/',
+ -selectmode => 'single',
+ -browsecmd => sub {
+ my $file = shift;
+ $label->configure(-text=>$file);
+ }
+ );
+
+ foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) {
+ $hlist->add($_, -text=>$_);
+ }
+
+ $hlist->pack;
+ $label->pack;
+
+ MainLoop;
+
+=head1 BUGS
+
+The fact that the display item at column 0 is implicitly associated
+with the whole entry is probably a design bug. This was done for
+backward compatibility purposes. The result is that there is a large
+overlap between the B<item> method and the B<add>,
+B<addchild>, B<entrycget> and B<entryconfigure>
+methods. Whenever multiple columns exist, the programmer should use
+ONLY the B<item> method to create and configure the display items
+in each column; the B<add>, B<addchild>, B<entrycget> and
+B<entryconfigure> should be used ONLY to create and configure
+entries.
+
+=head1 KEYWORDS
+
+Hierarchical Listbox
+
+=head1 SEE ALSO
+
+L<Tk::DItem|Tk::DItem>
+
+=cut
+
+