diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/HList.pod')
| -rw-r--r-- | Master/tlpkg/tlperl/lib/Tk/HList.pod | 1050 |
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 + + |