home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _607e680ac4cd0dbf63e2f7d05e6d6722 < prev    next >
Text File  |  2004-06-01  |  37KB  |  1,051 lines
  1. #  Copyright (c) 1996, Expert Interface Technologies
  2. #  See the file "license.terms" for information on usage and redistribution
  3. #  of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  4. #
  5. #  The file man.macros and some of the macros used by this file are
  6. #  copyrighted: (c) 1990 The Regents of the University of California.
  7. #               (c) 1994-1995 Sun Microsystems, Inc.
  8. #  The license terms of the Tcl/Tk distribution are in the file
  9. #  license.tcl.
  10.  
  11. =head1 NAME
  12.  
  13. Tk::HList - Create and manipulate Tix Hierarchial List widgets
  14.  
  15. =for category  Tk Widget Classes
  16.  
  17. =head1 SYNOPSIS
  18.  
  19. I<$hlist> = I<$parent>-E<gt>B<HList>(?I<options>?);
  20.  
  21. =head1 STANDARD OPTIONS
  22.  
  23. B<-background>    B<-borderwidth>    B<-cursor>    B<-exportselection>
  24. B<-foreground>    B<-font>    B<-height>    B<-highlightcolor>
  25. B<-highlightthickness>    B<-relief>    B<-selectbackground>
  26. B<-selectforeground>    B<-xscrollcommand>    B<-yscrollcommand>
  27. B<-width>
  28.  
  29. See L<Tk::options> for details of the standard options.
  30.  
  31. =head1 WIDGET-SPECIFIC OPTIONS
  32.  
  33. =over 4
  34.  
  35. =item Name:    B<browsecmd>
  36.  
  37. =item Class:    B<BrowseCmd>
  38.  
  39. =item Switch:    B<-browsecmd>
  40.  
  41. Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user browses through the
  42. entries in the HList widget.
  43.  
  44. =item Name:    B<columns>
  45.  
  46. =item Class:    B<Columns>
  47.  
  48. =item Switch:    B<-columns>
  49.  
  50. Specifies the number of columns in this HList widget. This option can
  51. only be set during the creation of the HList widget and cannot be
  52. changed subsequently.
  53.  
  54. =item Name:    B<command>
  55.  
  56. =item Class:    B<Command>
  57.  
  58. =item Switch:    B<-command>
  59.  
  60. Specifies the perl/Tk L<callback|Tk::callbacks> to be executed when the user invokes a list
  61. entry in the HList widget. Normally the user invokes a list
  62. entry by double-clicking it or pressing the Return key.
  63.  
  64. =item Name:    B<drawBranch>
  65.  
  66. =item Class:    B<DrawBranch>
  67.  
  68. =item Switch:    B<-drawbranch>
  69.  
  70. A Boolean value to specify whether branch line should be drawn to
  71. connect list entries to their parents.
  72.  
  73. =item Name:    B<foreground>
  74.  
  75. =item Class:    B<Foreground>
  76.  
  77. =item Switch:    B<-foreground>
  78.  
  79. =item Alias:    B<-fg>
  80.  
  81. B<[OBSOLETE]> Specifies the default foreground color for the list entries.
  82.  
  83. =item Name:    B<gap>
  84.  
  85. =item Class:    B<Gap>
  86.  
  87. =item Switch:    B<-gap>
  88.  
  89. B<[OBSOLETE]> The default distance between the bitmap/image and the
  90. text in list entries.
  91.  
  92. =item Name:    B<header>
  93.  
  94. =item Class:    B<Header>
  95.  
  96. =item Switch:    B<-header>
  97.  
  98. A Boolean value specifying whether headers should be displayed for
  99. this HList widget (see the B<header> method below).
  100.  
  101. =item Name:    B<height>
  102.  
  103. =item Class:    B<Height>
  104.  
  105. =item Switch:    B<-height>
  106.  
  107. Specifies the desired height for the window in number of characters.
  108.  
  109. =item Name:    B<indent>
  110.  
  111. =item Class:    B<Indent>
  112.  
  113. =item Switch:    B<-indent>
  114.  
  115. Specifies the amount of horizontal indentation between a list entry
  116. and its children. Must be a valid screen distance value.
  117.  
  118. =item Name:    B<indicator>
  119.  
  120. =item Class:    B<Indicator>
  121.  
  122. =item Switch:    B<-indicator>
  123.  
  124. Specifies whether the indicators should be displayed inside the HList
  125. widget. See the B<indicator> method below.
  126.  
  127. =item Name:    B<indicatorCmd>
  128.  
  129. =item Class:    B<IndicatorCmd>
  130.  
  131. =item Switch:    B<-indicatorcmd>
  132.  
  133. Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user manipulates the
  134. indicator of an HList entry. The B<-indicatorcmd> is triggered
  135. when the user press or releases the mouse button over the indicator in
  136. an HList entry. By default the perl/Tk B<callback> specified by
  137. B<-indicatorcmd> is executed with two additional arguments, the
  138. entryPath of the entry whose indicator has been triggered and additional
  139. information about the event.  The additional information is one of the
  140. following strings:  B<E<lt>ArmE<gt>>, B<E<lt>DisarmE<gt>>,
  141. and B<E<lt>ActivateE<gt>>.
  142.  
  143. =item Name:    B<itemType>
  144.  
  145. =item Class:    B<ItemType>
  146.  
  147. =item Switch:    B<-itemtype>
  148.  
  149. Specifies the default type of display item for this HList widget. When
  150. you call the B<itemCreate>, B<add> and B<addchild> methods, display
  151. items of this
  152. type will be created if the B<-itemtype> option is not specified .
  153.  
  154. =item Name:    B<padX>
  155.  
  156. =item Class:    B<Pad>
  157.  
  158. =item Switch:    B<-padx>
  159.  
  160. B<[OBSOLETE]> The default horizontal padding for list entries.
  161.  
  162. =item Name:    B<padY>
  163.  
  164. =item Class:    B<Pad>
  165.  
  166. =item Switch:    B<-padx>
  167.  
  168. B<[OBSOLETE]> The default vertical padding for list entries.
  169.  
  170. =item Name:    B<selectBackground>
  171.  
  172. =item Class:    B<SelectBackground>
  173.  
  174. =item Switch:    B<-selectbackground>
  175.  
  176. Specifies the background color for the selected list entries.
  177.  
  178. =item Name:    B<selectBorderWidth>
  179.  
  180. =item Class:    B<BorderWidth>
  181.  
  182. =item Switch:    B<-selectborderwidth>
  183.  
  184. Specifies a non-negative value indicating the width of the 3-D border
  185. to draw around selected items.  The value may have any of the forms
  186. acceptable to B<Tk_GetPixels>.
  187.  
  188. =item Name:    B<selectForeground>
  189.  
  190. =item Class:    B<SelectForeground>
  191.  
  192. =item Switch:    B<-selectforeground>
  193.  
  194. Specifies the foreground color for the selected list entries.
  195.  
  196. =item Name:    B<selectMode>
  197.  
  198. =item Class:    B<SelectMode>
  199.  
  200. =item Switch:    B<-selectmode>
  201.  
  202. Specifies one of several styles for manipulating the selection.  The
  203. value of the option may be arbitrary, but the default bindings expect
  204. it to be either B<single>, B<browse>, B<multiple>, or
  205. B<extended>; the default value is B<single>.
  206.  
  207. =item Name:    B<sizeCmd>
  208.  
  209. =item Class:    B<SizeCmd>
  210.  
  211. =item Switch:    B<-sizecmd>
  212.  
  213. Specifies a perl/Tk L<callback|Tk::callbacks> to be called whenever the HList widget
  214. changes its size.  This method can be useful to implement ``I<user scroll
  215. bars when needed>'' features.
  216.  
  217. =item Name:    B<separator>
  218.  
  219. =item Class:    B<Separator>
  220.  
  221. =item Switch:    B<-separator>
  222.  
  223. Specifies the character to used as the separator character when
  224. intepreting the path-names of list entries. By default the character
  225. "." is used.
  226.  
  227. =item Name:    B<width>
  228.  
  229. =item Class:    B<Width>
  230.  
  231. =item Switch:    B<-width>
  232.  
  233. Specifies the desired width for the window in characters.
  234.  
  235. =back
  236.  
  237. =head1 DESCRIPTION
  238.  
  239. The B<HList> method creates a new window (given by the
  240. $widget argument) and makes it into a HList widget.
  241. Additional options, described above, may be specified on the command
  242. line or in the option database to configure aspects of the
  243. HList widget such as its cursor and relief.
  244.  
  245. The HList widget can be used to display any data that have a
  246. hierarchical structure, for example, file system directory trees. The
  247. list entries are indented and connected by branch lines according to
  248. their places in the hierachy.
  249.  
  250. Each list entry is identified by an B<entryPath>. The entryPath is a
  251. sequence of B<entry names> separated by the separator charactor
  252. (specified by the B<-separator> option). An B<entry name> can be
  253. any string that does not contain the separator charactor, or it can be
  254. the a string that contains only one separator charactor.
  255.  
  256. For example, when "." is used as the separator charactor,
  257. "one.two.three" is the entryPath for a list entry whose parent is
  258. "one.two", whose parent is "one", which is a toplevel entry (has no
  259. parents).
  260.  
  261. Another examples: ".two.three" is the entryPath for a list entry whose
  262. parent is ".two", whose parent is ".", which is a toplevel entry.
  263.  
  264. =head1 DISPLAY ITEMS
  265.  
  266. Each list entry in an HList widget is associated with a B<display>
  267. item.  The display item determines what visual information should
  268. be displayed for this list entry. Please see L<Tk::DItem>
  269. for a list of all display items.
  270. When a list entry is created by the B<itemCreate>, B<add> or
  271. B<addchild> widget
  272. methods, the type of its display item is determined by the
  273. B<-itemtype> option passed to these methods. If the
  274. B<-itemtype> is omitted, then by default the type specified by
  275. this HList widget's B<-itemtype> option is used.
  276.  
  277. =head1 WIDGET METHODS
  278.  
  279. The B<HList> method creates a widget object.
  280. This object supports the B<configure> and B<cget> methods
  281. described in L<Tk::options> which can be used to enquire and
  282. modify the options described above.
  283. The widget also inherits all the methods provided by the generic
  284. L<Tk::Widget|Tk::Widget> class.
  285.  
  286. The following additional methods are available HList widgets:
  287.  
  288. =over 4
  289.  
  290. =item I<$hlist>-E<gt>B<add>(I<$entryPath> ?,I<option>=E<gt>I<value>, ...?)
  291.  
  292. Creates a new list entry with the pathname I<$entryPath>. A list
  293. entry must be created after its parent is created (unless this entry
  294. is a top-level entry, which has no parent).  See also L<"BUGS"> below.
  295. This method returns the
  296. entryPath of the newly created list entry. The following
  297. configuration options can be given to configure the list entry:
  298.  
  299. =over 8
  300.  
  301. =item B<-at> =E<gt> I<position>
  302.  
  303. Insert the new list at the position given by I<position>.
  304. I<position> must be a valid integer. The position B<0> indicates
  305. the first position, B<1> indicates the second position, and so on.
  306.  
  307. =item B<-after> =E<gt> I<afterWhich>
  308.  
  309. Insert the new list entry after the entry identified by
  310. I<afterWhich>. I<afterWhich> must be a valid list entry and it
  311. mush have the same parent as the new list entry
  312.  
  313. =item B<-before> =E<gt> I<beforeWhich>
  314.  
  315. Insert the new list entry before the entry identified by
  316. I<beforeWhich>. I<beforeWhich> must be a valid list entry and it
  317. mush have the same parent as the new list entry
  318.  
  319. =item B<-data> =E<gt> I<string>
  320.  
  321. Specifies a string to associate with this list entry. This string can
  322. be queried by the B<info> method. The application
  323. programmer can use the B<-data> option to associate the list entry
  324. with the data it represents.
  325.  
  326. =item B<-itemtype> =E<gt> I<type>
  327.  
  328. Specifies the type of display item to be display for the new list
  329. entry. B<type> must be a valid display item type. Currently the
  330. available display item types are B<imagetext>, B<text>, and
  331. $widget. If this option is not specified, then by default the
  332. type specified by this HList widget's B<-itemtype> option is used.
  333.  
  334. =item B<-state> =E<gt> I<state>
  335.  
  336. Specifies whether this entry can be selected or invoked by the user.
  337. Must be either B<normal> or B<disabled>.
  338.  
  339. =back
  340.  
  341. The B<add> method accepts additional configuration options
  342. to configure the display item associated with this list entry. The set
  343. of additional configuration options depends on the type of the display
  344. item given by the B<-itemtype> option. Please see
  345. L<Tk::DItem> for a list of the configuration options for
  346. each of the display item types.
  347.  
  348. =item I<$hlist>-E<gt>B<addchild>(I<$parentPath, >?I<option, value, ..., >?)
  349.  
  350. Adds a new child entry to the children list of the list entry
  351. identified by I<$parentPath>. Or, if I<$parentPath> is set to be
  352. the empty string, then creates a new toplevel entry. The name of the
  353. new list entry will be a unique name automatically generated by the
  354. HList widget. Usually if I<$parentPath> is B<foo>, then the
  355. entryPath of the new entry will be B<foo.0>, B<foo.1>, ... etc.
  356. This method returns the entryPath of the newly created list entry.
  357. I<option> can be any option for the B<add> method.
  358. See also L<"BUGS"> below.
  359.  
  360. =item I<$hlist>-E<gt>B<anchorSet>(I<$entryPath>)
  361.  
  362. Sets the anchor to the list entry identified by I<$entryPath>.  The
  363. anchor is the end of the selection that is fixed while the user is
  364. dragging out a selection with the mouse.
  365.  
  366. =item I<$hlist>-E<gt>B<anchorClear>
  367.  
  368. Removes the anchor, if any, from this HList widget. This only
  369. removes the surrounding highlights of the anchor entry and does not
  370. affect its selection status.
  371.  
  372. =item I<$hlist>-E<gt>B<columnWidth>(I<$col>?, I<-char>?, ?I<width>?)
  373.  
  374. Querys or sets the width of a the column I<$col> in the HList
  375. widget. The value of I<$col> is zero-based: 0 stands for the first
  376. column, 1 stands for the second, and so on. If no further parameters
  377. are given, returns the current width of this column (in number of
  378. pixels). Additional parameters can be given to set the width of this
  379. column:
  380.  
  381. =over 8
  382.  
  383. =item I<$hlist>-E<gt>B<columnWidth>(I<$col>, B<''>)
  384.  
  385. An empty string indicates that the width of the column should be just
  386. wide enough to display the widest element in this column. In this
  387. case, the width of this column may change as a result of the elements
  388. in this column changing their sizes.
  389.  
  390. =item I<$hlist>-E<gt>B<columnWidth>(I<$col, >I<width>)
  391.  
  392. I<width> must be in a form accepted by B<Tk_GetPixels>.
  393.  
  394. =item I<$hlist>-E<gt>B<columnWidth>(I<$col, >B<-char, >I<nChars>)
  395.  
  396. The width is set to be the average width occupied by I<nChars>
  397. number of characters of the font specified by the B<-font> option
  398. of this HList widget.
  399.  
  400. =back
  401.  
  402. =item I<$hlist>-E<gt>B<delete>(I<option>, I<$entryPath>)
  403.  
  404. Delete one or more list entries. I<option> may be one of the
  405. following:
  406.  
  407. =over 8
  408.  
  409. =item B<all>
  410.  
  411. Delete all entries in the HList. In this case the I<$entryPath>
  412. does not need to be specified.
  413.  
  414. =item B<entry>
  415.  
  416. Delete the entry specified by I<$entryPath> and all its offsprings,
  417. if any.
  418.  
  419. =item B<offsprings>
  420.  
  421. Delete all the offsprings, if any, of the entry specified by
  422. I<$entryPath>. However, I<$entryPath> itself is not deleted.
  423.  
  424. =item B<siblings>
  425.  
  426. Delete all the list entries that share the same parent with the entry
  427. specified by I<$entryPath>. However, I<$entryPath> itself is not
  428. deleted.
  429.  
  430. =back
  431.  
  432. =item I<$hlist>-E<gt>B<dragsiteSet>(I<$entryPath>)
  433.  
  434. Sets the dragsite to the list entry identified by
  435. I<$entryPath>. The dragsite is used to indicate the source of a
  436. drag-and-drop action. Currently drag-and-drop functionality has not
  437. been implemented in Tix yet.
  438.  
  439. =item I<$hlist>-E<gt>B<dragsiteClear>
  440.  
  441. Remove the dragsite, if any, from the this HList widget. This only
  442. removes the surrounding highlights of the dragsite entry and does not
  443. affect its selection status.
  444.  
  445. =item I<$hlist>-E<gt>B<dropsiteSet>(I<$entryPath>)
  446.  
  447. Sets the dropsite to the list entry identified by I<$entryPath>. The
  448. dropsite is used to indicate the target of a drag-and-drop
  449. action. Currently drag-and-drop functionality has not been implemented
  450. in Tix yet.
  451.  
  452. =item I<$hlist>-E<gt>B<dropsiteClear>
  453.  
  454. Remove the dropsite, if any, from the this HList widget. This only
  455. removes the surrounding highlights of the dropsite entry and does not
  456. affect its selection status.
  457.  
  458. =item I<$hlist>-E<gt>B<entrycget>(I<$entryPath>, I<option>)
  459.  
  460. Returns the current value of the configuration option given by
  461. I<option> for the entry indentfied by I<$entryPath>. I<Option>
  462. may have any of the values accepted by the B<add> method.
  463.  
  464. =item I<$hlist>-E<gt>B<entryconfigure>(I<$entryPath> ?,I<option>?, ?I<value>=E<gt>I<option>, ...?)
  465.  
  466. Query or modify the configuration options of the list entry indentfied
  467. by I<$entryPath>. If no I<option> is specified, returns a list
  468. describing all of the available options for I<$entryPath> (see
  469. L<Tk::options> for information on the format of this list.) If
  470. I<option> is specified with no I<value>, then the method
  471. returns a list describing the one named option (this list will be
  472. identical to the corresponding sublist of the value returned if no
  473. I<option> is specified). If one or more I<option-value> pairs
  474. are specified, then the method modifies the given option(s) to have
  475. the given value(s); in this case the method returns an empty string.
  476. I<Option> may have any of the values accepted by the B<add> or
  477. B<addchild> method. The exact set of options depends on the
  478. value of the B<-itemtype> option passed to the the B<add> or
  479. B<addchild> method when this list entry is created.
  480.  
  481. =item I<$hlist>-E<gt>B<header>(I<option>, I<$col> ?,I<args>, ...?)
  482.  
  483. Manipulates the header items of this HList widget. If the
  484. B<-header> option of this HList widget is set to true, then a
  485. header item is displayed at the top of each column. The I<$col>
  486. argument for this method must be a valid integer. 0 indicates the
  487. first column, 1 the second column, ... and so on. This method
  488. supports the following options:
  489.  
  490. =over 8
  491.  
  492. =item I<$hlist>-E<gt>B<header>(B<cget>, I<$col>, I<option>)
  493.  
  494. If the I<$col>-th column has a header display item, returns the
  495. value of the specified I<option> of the header item. If the header
  496. doesn't exist, returns an error.
  497.  
  498. =item I<$hlist>-E<gt>B<header>(B<configure, >I<$col, >?I<option>?, I<?value, option, value, ...>?)
  499.  
  500. Query or modify the configuration options of the header display item
  501. of the I<$col>-th column. The header item must exist, or an error
  502. will result.  If no I<option> is specified, returns a list
  503. describing all of the available options for the header display item
  504. (see L<Tk::options> for information on the format of this
  505. list.) If I<option> is specified with no I<value>, then the
  506. method returns a list describing the one named option (this list will
  507. be identical to the corresponding sublist of the value returned if no
  508. I<option> is specified). If one or more I<option-value> pairs
  509. are specified, then the method modifies the given option(s) to have
  510. the given value(s); in this case the method returns an empty
  511. string. I<Option> may have any of the values accepted by the
  512. B<header create> method. The exact set of options depends
  513. on the value of the B<-itemtype> option passed to the the B<header>
  514. create method when this display item was created.
  515.  
  516. =item I<$hlist>-E<gt>B<header>(B<create, >I<$col, >?I<-itemtype type>? ?I<option value ...>?
  517.  
  518. Creates a new display item as the header for the I<$col>-th
  519. column. See also L<"BUGS"> below.
  520. If an header display item already exists for this column, it
  521. will be replaced by the new item.  An optional parameter
  522. I<-itemtype> can be used to specify what type of display item
  523. should be created. If the I<-itemtype> is not given, then by
  524. default the type specified by this HList widget's B<-itemtype>
  525. option is used. Additional parameters, in I<option-value> pairs,
  526. can be passed to configure the appearance of the display item. Each
  527. I<option-value> pair must be a valid option for this type of
  528. display item or one of the following:
  529.  
  530. =over 12
  531.  
  532. =item B<-borderwidth> =E<gt> I<color>
  533.  
  534. Specifies the border width of this header item.
  535.  
  536. =item B<-headerbackground> =E<gt> I<color>
  537.  
  538. Specifies the background color of this header item.
  539.  
  540. =item B<-relief> =E<gt> I<type>
  541.  
  542. Specifies the relief type of the border of this header item.
  543.  
  544. =back
  545.  
  546. =item I<$hlist>-E<gt>B<header>(B<delete, >I<$col>)
  547.  
  548. Deletes the header display item for the I<$col>-th column.
  549.  
  550. =item I<$hlist>-E<gt>B<header>(B<exists, >I<$col>)
  551.  
  552. Return true if an header display item exists for the I<$col>-th
  553. column; return false otherwise.
  554.  
  555. =item I<$hlist>-E<gt>B<header>(B<size>, I<$entryPath>)
  556.  
  557. If an header display item exists for the I<$col>-th column , returns
  558. its size in pixels in a two element list I<(width, height)>;
  559. returns an error if the header display item does not exist.
  560.  
  561. =back
  562.  
  563. =item I<$hlist>-E<gt>B<hide>(I<option> ?,I<$entryPath>?)
  564.  
  565. Makes some of entries invisible without deleting them.
  566. I<Option> can be one of the following:
  567.  
  568. =over 8
  569.  
  570. =item B<entry>
  571.  
  572. Hides the list entry identified by I<$entryPath>.
  573.  
  574. =back
  575.  
  576. Currently only the B<entry> option is supported. Other options will
  577. be added in the next release.
  578.  
  579. =item I<$hlist>-E<gt>B<indicator>(I<option>, I<$entryPath>, ?I<args, ...>?)
  580.  
  581. Manipulates the indicator on the list entries. An indicator is usually
  582. a small display item (such as an image) that is displayed to the left
  583. to an entry to indicate the status of the entry.  For example, it may
  584. be used to indicate whether a directory is opened or
  585. closed.  I<Option> can be one of the following:
  586.  
  587. =over 8
  588.  
  589. =item I<$hlist>-E<gt>B<indicator>(B<cget>, I<$entryPath>, I<option>)
  590.  
  591. If the list entry given by I<$entryPath> has an indicator, returns
  592. the value of the specified I<option> of the indicator. If the
  593. indicator doesn't exist, returns an error.
  594.  
  595. =item I<$hlist>-E<gt>B<indicator>(B<configure>, I<$entryPath>, ?I<option>?, I<?value, option, value, ...>?)
  596.  
  597. Query or modify the configuration options of the indicator display
  598. item of the entry specified by I<$entryPath>. The indicator item
  599. must exist, or an error will result.  If no I<option> is specified,
  600. returns a list describing all of the available options for the
  601. indicator display item (see L<Tk::options> for information
  602. on the format of this list). If I<option> is specified with no
  603. I<value>, then the method returns a list describing the one named
  604. option (this list will be identical to the corresponding sublist of
  605. the value returned if no I<option> is specified). If one or more
  606. I<option-value> pairs are specified, then the method modifies the
  607. given option(s) to have the given value(s); in this case the method
  608. returns an empty string.  I<Option> may have any of the values
  609. accepted by the B<indicator create> method. The exact set
  610. of options depends on the value of the B<-itemtype> option passed
  611. to the the B<indicator create> method when this display item
  612. was created.
  613.  
  614. =item I<$hlist>-E<gt>B<indicator>(B<create, >I<$entryPath, >?, I<-itemtype type>? ?I<option value ...>?)
  615.  
  616. Creates a new display item as the indicator for the entry specified by
  617. I<$entryPath>. If an indicator display item already exists for this
  618. entry, it will be replaced by the new item.  An optional parameter
  619. I<-itemtype> can be used to specify what type of display item
  620. should be created. If the I<-itemtype> is not given, then by
  621. default the type specified by this HList widget's B<-itemtype>
  622. option is used. Additional parameters, in I<option-value> pairs,
  623. can be passed to configure the appearance of the display item. Each
  624. I<option-value> pair must be a valid option for this type of
  625. display item.
  626.  
  627. =item I<$hlist>-E<gt>B<indicator>(B<delete>, I<$entryPath>)
  628.  
  629. Deletes the indicator display item for the entry given by I<$entryPath>.
  630.  
  631. =item I<$hlist>-E<gt>B<indicator>(B<exists>, I<$entryPath>)
  632.  
  633. Return true if an indicator display item exists for the entry given by
  634. I<$entryPath>; return false otherwise.
  635.  
  636. =item I<$hlist>-E<gt>B<indicator>(B<size>, I<$entryPath>)
  637.  
  638. If an indicator display item exists for the entry given by
  639. I<$entryPath>, returns its size in a two element list of the form
  640. {I<width height>}; returns an error if the indicator display item
  641. does not exist.
  642.  
  643. =back
  644.  
  645. =item I<$hlist>-E<gt>B<info>(I<option>, I<arg, ...>)
  646.  
  647. Query information about the HList widget. I<option> can be one
  648. of the following:
  649.  
  650. =over 8
  651.  
  652. =item I<$hlist>-E<gt>B<info>(B<anchor>)
  653.  
  654. Returns the entryPath of the current anchor, if any, of the HList
  655. widget. If the anchor is not set, returns the empty string.
  656.  
  657. =item I<$hlist>-E<gt>B<infoBbox>(I<$entryPath>)
  658.  
  659. Returns a list of four numbers describing the visible bounding box of
  660. the entry given I<$entryPath>. The first two elements of the list
  661. give the x and y coordinates of the upper-left corner of the screen
  662. area covered by the entry (specified in pixels relative to the widget)
  663. and the last two elements give the lower-right corner of the area, in
  664. pixels. If no part of the entry given by index is visible on the
  665. screen then the result is an empty string; if the entry is partially
  666. visible, the result gives the only the visible area of the entry.
  667.  
  668. =item I<$hlist>-E<gt>B<info>(B<children> ?,I<$entryPath>?)
  669.  
  670. If I<$entryPath> is given, returns a list of the entryPath's of its
  671. children entries. Otherwise returns a list of the toplevel
  672. entryPath's.
  673.  
  674. =item I<$hlist>-E<gt>B<info>(B<data> ?,I<$entryPath>?)
  675.  
  676. Returns the data associated with I<$entryPath>.
  677.  
  678. =item I<$hlist>-E<gt>B<info>(B<dragsite>)
  679.  
  680. Returns the entryPath of the current dragsite, if any, of the HList
  681. widget. If the dragsite is not set, returns the empty string.
  682.  
  683. =item I<$hlist>-E<gt>B<info>(B<dropsite>)
  684.  
  685. Returns the entryPath of the current dropsite, if any, of the HList
  686. widget. If the dropsite is not set, returns the empty string.
  687.  
  688. =item I<$hlist>-E<gt>B<info>(B<exists>, I<$entryPath>)
  689.  
  690. Returns a boolean value indicating whether the list entry
  691. I<$entryPath> exists.
  692.  
  693. =item I<$hlist>-E<gt>B<info>(B<hidden>, I<$entryPath>)
  694.  
  695. Returns a boolean value indicating whether the list entry
  696. B<$entryPath> is hidden or not.
  697.  
  698. =item I<$hlist>-E<gt>B<info>(B<next>, I<$entryPath>)
  699.  
  700. Returns the entryPath of the list entry, if any, immediately below
  701. this list entry. If this entry is already at the bottom of the HList
  702. widget, returns an empty string.
  703.  
  704. =item I<$hlist>-E<gt>B<info>(B<parent>, I<$entryPath>)
  705.  
  706. Returns the name of the parent of the list entry identified by
  707. I<$entryPath>. If I<entryPath> is a toplevel list entry,
  708. returns the empty string.
  709.  
  710. =item I<$hlist>-E<gt>B<info>(B<prev>, I<$entryPath>)
  711.  
  712. Returns the entryPath of the list entry, if any, immediately above
  713. this list entry. If this entry is already at the top of the HList
  714. widget, returns an empty string.
  715.  
  716. =item I<$hlist>-E<gt>B<info>(B<selection>)
  717.  
  718. Returns a list of selected entries in the HList widget. In scalar
  719. context, returns an anonymous list of the selected entries.
  720. If no entries are selected, undef is returned in scalar context, and
  721. an empty list otherwise.
  722.  
  723. =back
  724.  
  725. =item I<$hlist>-E<gt>B<item>(I<option, >?I<args, ...>?)
  726.  
  727. Creates and configures the display items at individual columns the
  728. entries. The form of additional of arguments depends on the choice of
  729. I<option>:
  730.  
  731. =over 8
  732.  
  733. =item I<$hlist>-E<gt>B<itemCget>(I<$entryPath>, I<$col>, I<option>)
  734.  
  735. Returns the current value of the configure I<option> of the display
  736. item at the column designated by I<$col> of the entry specified by
  737. I<$entryPath>.
  738.  
  739. =item I<$hlist>-E<gt>B<itemConfigure>(I<$entryPath>, I<$col> ?,I<option>?, I<?value, option, value, ...>?)
  740.  
  741. Query or modify the configuration options of the display item at the
  742. column designated by I<$col> of the entry specified by
  743. I<$entryPath>. If no I<option> is specified, returns a list
  744. describing all of the available options for I<$entryPath> (see
  745. L<Tk::options> for information on the format of this
  746. list). If I<option> is specified with no I<value>, then the
  747. method returns a list describing the one named option (this list will
  748. be identical to the corresponding sublist of the value returned if no
  749. I<option> is specified). If one or more I<option-value> pairs
  750. are specified, then the method modifies the given option(s) to have
  751. the given value(s); in this case the method returns an empty string.
  752. I<Option> may have any of the values accepted by the B<item>
  753. create method. The exact set of options depends on the
  754. value of the B<-itemtype> option passed to the the B<item>
  755. create method when this display item was created.
  756.  
  757. =item I<$hlist>-E<gt>B<itemCreate>(I<$entryPath>, I<$col> ?,I<-itemtype>=E<gt>I<type>? ?,I<option value ...>?)
  758.  
  759. Creates a new display item at the column designated by I<$col> of
  760. the entry specified by I<$entryPath>. An optional parameter
  761. I<-itemtype> can be used to specify what type of display items
  762. should be created. If the I<-itemtype> is not specified, then by
  763. default the type specified by this HList widget's B<-itemtype>
  764. option is used.  Additional parameters, in I<option-value> pairs,
  765. can be passed to configure the appearance of the display item. Each
  766. I<option- value> pair must be a valid option for this type of
  767. display item.
  768.  
  769. =item I<$hlist>-E<gt>B<itemDelete>(I<$entryPath>, I<$col>)
  770.  
  771. Deletes the display item at the column designated by I<$col> of
  772. the entry specified by I<$entryPath>.
  773.  
  774. =item I<$hlist>-E<gt>B<itemExists>(I<$entryPath>, I<$col>)
  775.  
  776. Returns true if there is a display item at the column designated by
  777. I<$col> of the entry specified by I<$entryPath>; returns false
  778. otherwise.
  779.  
  780. =back
  781.  
  782. =item I<$hlist>-E<gt>B<nearest>(I<y>)
  783.  
  784. I<$hlist>-E<gt>B<nearest>(I<y>)
  785. Given a y-coordinate within the HList window, this method returns
  786. the entryPath of the (visible) HList element nearest to that
  787. y-coordinate.
  788.  
  789. =item I<$hlist>-E<gt>B<see>(I<$entryPath>)
  790.  
  791. Adjust the view in the HList so that the entry given by I<$entryPath> is
  792. visible. If the entry is already visible then the method has no
  793. effect; if the entry is near one edge of the window then the HList
  794. scrolls to bring the element into view at the edge; otherwise the
  795. HList widget scrolls to center the entry.
  796.  
  797. =item I<$hlist>-E<gt>B<selection>(I<option>, I<arg>, ...)
  798.  
  799. =item I<$hlist>-E<gt>B<selection>I<Option>(I<arg>, ...)
  800.  
  801. This method is used to adjust the selection within a HList widget. It
  802. has several forms, depending on I<option>:
  803.  
  804. =over 8
  805.  
  806. =item I<$hlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?)
  807.  
  808. When no extra arguments are given, deselects all of the list entrie(s)
  809. in this HList widget. When only I<from> is given, only the list
  810. entry identified by I<from> is deselected. When both I<from> and
  811. I<to> are given, deselects all of the list entrie(s) between
  812. between I<from> and I<to>, inclusive, without affecting the
  813. selection state of elements outside that range.
  814.  
  815. =item I<$hlist>-E<gt>B<selectionGet>
  816.  
  817. This is an alias for the B<infoSelection> method.
  818.  
  819. =item I<$hlist>-E<gt>B<selectionIncludes>(I<$entryPath>)
  820.  
  821. Returns 1 if the list entry indicated by I<$entryPath> is currently
  822. selected; returns 0 otherwise.
  823.  
  824. =item I<$hlist>-E<gt>B<selectionSet>(I<from>?, I<to>?)
  825.  
  826. Selects all of the list entrie(s) between between I<from> and
  827. I<to>, inclusive, without affecting the selection state of entries
  828. outside that range. When only I<from> is given, only the list entry
  829. identified by I<from> is selected.
  830.  
  831. =back
  832.  
  833. =item I<$hlist>-E<gt>B<show>(I<option> ?,I<$entryPath>?)
  834.  
  835. Show the entries that are hidden by the B<hide> method,
  836. I<option> can be one of the following:
  837.  
  838. =over 8
  839.  
  840. =item B<entry>
  841.  
  842. Shows the list entry identified by I<$entryPath>.
  843.  
  844. =back
  845.  
  846. Currently only the B<entry> option is supported. Other options will
  847. be added in future releases.
  848.  
  849. =item I<$hlist>-E<gt>B<xview>(I<args>)
  850.  
  851. This method is used to query and change the horizontal position of the
  852. information in the widget's window. It can take any of the following
  853. forms:
  854.  
  855. =over 8
  856.  
  857. =item I<$hlist>-E<gt>B<xview>
  858.  
  859. Returns a list containing two elements.  Each element is a real
  860. fraction between 0 and 1; together they describe the horizontal span
  861. that is visible in the window.  For example, if the first element is
  862. .2 and the second element is .6, 20% of the HList entry is
  863. off-screen to the left, the middle 40% is visible in the window, and
  864. 40% of the entry is off-screen to the right. These are the same values
  865. passed to scrollbars via the B<-xscrollcommand> option.
  866.  
  867. =item I<$hlist>-E<gt>B<xview>(I<$entryPath>)
  868.  
  869. Adjusts the view in the window so that the list entry identified by
  870. I<$entryPath> is aligned to the left edge of the window.
  871.  
  872. =item I<$hlist>-E<gt>B<xview>(B<moveto> =E<gt> I<fraction>)
  873.  
  874. Adjusts the view in the window so that I<fraction> of the total
  875. width of the HList is off-screen to the left. I<fraction> must be
  876. a fraction between 0 and 1.
  877.  
  878. =item I<$hlist>-E<gt>B<xview>(B<scroll> =E<gt> I<number, what>)
  879.  
  880. This method shifts the view in the window left or right according to
  881. I<number> and I<what>. I<Number> must be an integer.
  882. I<What> must be either B<units> or B<pages> or an
  883. abbreviation of one of these. If I<what> is B<units>, the view
  884. adjusts left or right by I<number> character units (the width of
  885. the B<0> character) on the display; if it is B<pages> then the
  886. view adjusts by I<number> screenfuls. If I<number> is negative
  887. then characters farther to the left become visible; if it is positive
  888. then characters farther to the right become visible.
  889.  
  890. =back
  891.  
  892. =item I<$hlist>-E<gt>B<yview>(I<?args>?)
  893.  
  894. This method is used to query and change the vertical position of the
  895. entries in the widget's window. It can take any of the following forms:
  896.  
  897. =over 8
  898.  
  899. =item I<$hlist>-E<gt>B<yview>
  900.  
  901. Returns a list containing two elements, both of which are real
  902. fractions between 0 and 1.  The first element gives the position of
  903. the list element at the top of the window, relative to the HList as a
  904. whole (0.5 means it is halfway through the HList, for example).  The
  905. second element gives the position of the list entry just after the
  906. last one in the window, relative to the HList as a whole.  These are
  907. the same values passed to scrollbars via the B<-yscrollcommand>
  908. option.
  909.  
  910. =item I<$hlist>-E<gt>B<yview>(I<$entryPath>)
  911.  
  912. Adjusts the view in the window so that the list entry given by
  913. I<$entryPath> is displayed at the top of the window.
  914.  
  915. =item I<$hlist>-E<gt>B<yview>(B<moveto> =E<gt> I<fraction>)
  916.  
  917. Adjusts the view in the window so that the list entry given by
  918. I<fraction> appears at the top of the window. I<Fraction> is a
  919. fraction between 0 and 1; 0 indicates the first entry in the
  920. HList, 0.33 indicates the entry one-third the way through the
  921. HList, and so on.
  922.  
  923. =item I<$hlist>-E<gt>B<yview>(B<scroll> =E<gt> I<number, what>)
  924.  
  925. This method adjust the view in the window up or down according to
  926. I<number> and I<what>.  I<Number> must be an integer.
  927. I<What> must be either B<units> or B<pages>.  If I<what>
  928. is B<units>, the view adjusts up or down by I<number> lines; if
  929. it is B<pages> then the view adjusts by I<number> screenfuls.
  930. If I<number> is negative then earlier entries become visible; if
  931. it is positive then later entries become visible.
  932.  
  933. =back
  934.  
  935. =back
  936.  
  937. =head1 BINDINGS
  938.  
  939. =over 4
  940.  
  941. =item [1]
  942.  
  943. If the B<-selectmode> is "browse", when the user drags the mouse
  944. pointer over the list entries, the entry under the pointer will be
  945. highlighted and the B<-browsecmd> callback will be called with
  946. one parameter, the entryPath of the highlighted entry. Only one entry
  947. can be highlighted at a time. The B<-command> callback will be
  948. called when the user double-clicks on a list entry.
  949.  
  950. =item [2]
  951.  
  952. If the B<-selectmode> is "single", the entries will only be
  953. highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry
  954. is highlighted, the B<-browsecmd> callback will be called with
  955. one parameter indicating the highlighted list entry. The
  956. B<-command> callback will be called when the user double-clicks
  957. on a list entry.
  958.  
  959. =item [3]
  960.  
  961. If the B<-selectmode> is "multiple", when the user drags the mouse
  962. pointer over the list entries, all the entries under the pointer will
  963. be highlighted. However, only a contiguous region of list entries can
  964. be selected. When the highlighted area is changed, the
  965. B<-browsecmd> callback will be called with an undefined
  966. parameter. It is the responsibility of the B<-browsecmd> callback
  967. to find out the exact highlighted selection in the HList. The
  968. B<-command> callback will be called when the user double-clicks
  969. on a list entry.
  970.  
  971. =item [4]
  972.  
  973. If the B<-selectmode> is "extended", when the user drags the mouse
  974. pointer over the list entries, all the entries under the pointer will
  975. be highlighted. The user can also make disjointed selections using
  976. E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the
  977. B<-browsecmd> callback will be called with an undefined
  978. parameter. It is the responsibility of the B<-browsecmd> callback
  979. to find out the exact highlighted selection in the HList. The
  980. B<-command> callback will be called when the user double-clicks
  981. on a list entry.
  982.  
  983. =item [5]
  984.  
  985. B<Arrow key bindings:> E<lt>UpE<gt> arrow key moves the anchor point to the
  986. item right on top of the current anchor item. E<lt>DownE<gt> arrow key moves
  987. the anchor point to the item right below the current anchor item.
  988. E<lt>LeftE<gt> arrow key moves the anchor to the parent item of the current
  989. anchor item. E<lt>RightE<gt> moves the anchor to the first child of the
  990. current anchor item. If the current anchor item does not have any
  991. children, moves the anchor to the item right below the current anchor
  992. item.
  993.  
  994. =back
  995.  
  996. =head1 EXAMPLE
  997.  
  998. This example demonstrates how to use an HList to store a file
  999. directory structure and respond to the user's browse events:
  1000.  
  1001.    use strict;
  1002.    use Tk;
  1003.    use Tk::Label;
  1004.    use Tk::HList;
  1005.  
  1006.    my $mw = MainWindow->new();
  1007.    my $label = $mw->Label(-width=>15);
  1008.    my $hlist = $mw->HList(
  1009.                        -itemtype   => 'text',
  1010.                        -separator  => '/',
  1011.                        -selectmode => 'single',
  1012.                        -browsecmd  => sub {
  1013.                                  my $file = shift;
  1014.                                  $label->configure(-text=>$file);
  1015.                               }
  1016.                        );
  1017.  
  1018.    foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) {
  1019.        $hlist->add($_, -text=>$_);
  1020.    }
  1021.  
  1022.    $hlist->pack;
  1023.    $label->pack;
  1024.  
  1025.    MainLoop;
  1026.  
  1027. =head1 BUGS
  1028.  
  1029. The fact that the display item at column 0 is implicitly associated
  1030. with the whole entry is probably a design bug. This was done for
  1031. backward compatibility purposes. The result is that there is a large
  1032. overlap between the B<item> method and the B<add>,
  1033. B<addchild>, B<entrycget> and B<entryconfigure>
  1034. methods.  Whenever multiple columns exist, the programmer should use
  1035. ONLY the B<item> method to create and configure the display items
  1036. in each column; the B<add>, B<addchild>, B<entrycget> and
  1037. B<entryconfigure> should be used ONLY to create and configure
  1038. entries.
  1039.  
  1040. =head1 KEYWORDS
  1041.  
  1042. Hierarchical Listbox
  1043.  
  1044. =head1 SEE ALSO
  1045.  
  1046. L<Tk::DItem|Tk::DItem>
  1047.  
  1048. =cut
  1049.  
  1050.  
  1051.