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, 0 insertions, 1050 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/HList.pod b/Master/tlpkg/tlperl/lib/Tk/HList.pod
deleted file mode 100644
index 0843e689843..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/HList.pod
+++ /dev/null
@@ -1,1050 +0,0 @@
-# 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
-
-