Commit | Line | Data |
---|---|---|
86530b38 AT |
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. If no entries | |
719 | are selected, returns an empty string. | |
720 | ||
721 | =back | |
722 | ||
723 | =item I<$hlist>-E<gt>B<item>(I<option, >?I<args, ...>?) | |
724 | ||
725 | Creates and configures the display items at individual columns the | |
726 | entries. The form of additional of arguments depends on the choice of | |
727 | I<option>: | |
728 | ||
729 | =over 8 | |
730 | ||
731 | =item I<$hlist>-E<gt>B<itemCget>(I<$entryPath>, I<$col>, I<option>) | |
732 | ||
733 | Returns the current value of the configure I<option> of the display | |
734 | item at the column designated by I<$col> of the entry specified by | |
735 | I<$entryPath>. | |
736 | ||
737 | =item I<$hlist>-E<gt>B<itemConfigure>(I<$entryPath>, I<$col> ?,I<option>?, I<?value, option, value, ...>?) | |
738 | ||
739 | Query or modify the configuration options of the display item at the | |
740 | column designated by I<$col> of the entry specified by | |
741 | I<$entryPath>. If no I<option> is specified, returns a list | |
742 | describing all of the available options for I<$entryPath> (see | |
743 | L<Tk::options> for information on the format of this | |
744 | list). If I<option> is specified with no I<value>, then the | |
745 | method returns a list describing the one named option (this list will | |
746 | be identical to the corresponding sublist of the value returned if no | |
747 | I<option> is specified). If one or more I<option-value> pairs | |
748 | are specified, then the method modifies the given option(s) to have | |
749 | the given value(s); in this case the method returns an empty string. | |
750 | I<Option> may have any of the values accepted by the B<item> | |
751 | create method. The exact set of options depends on the | |
752 | value of the B<-itemtype> option passed to the the B<item> | |
753 | create method when this display item was created. | |
754 | ||
755 | =item I<$hlist>-E<gt>B<itemCreate>(I<$entryPath>, I<$col> ?,I<-itemtype>=E<gt>I<type>? ?,I<option value ...>?) | |
756 | ||
757 | Creates a new display item at the column designated by I<$col> of | |
758 | the entry specified by I<$entryPath>. An optional parameter | |
759 | I<-itemtype> can be used to specify what type of display items | |
760 | should be created. If the I<-itemtype> is not specified, then by | |
761 | default the type specified by this HList widget's B<-itemtype> | |
762 | option is used. Additional parameters, in I<option-value> pairs, | |
763 | can be passed to configure the appearance of the display item. Each | |
764 | I<option- value> pair must be a valid option for this type of | |
765 | display item. | |
766 | ||
767 | =item I<$hlist>-E<gt>B<itemDelete>(I<$entryPath>, I<$col>) | |
768 | ||
769 | Deletes the display item at the column designated by I<$col> of | |
770 | the entry specified by I<$entryPath>. | |
771 | ||
772 | =item I<$hlist>-E<gt>B<itemExists>(I<$entryPath>, I<$col>) | |
773 | ||
774 | Returns true if there is a display item at the column designated by | |
775 | I<$col> of the entry specified by I<$entryPath>; returns false | |
776 | otherwise. | |
777 | ||
778 | =back | |
779 | ||
780 | =item I<$hlist>-E<gt>B<nearest>(I<y>) | |
781 | ||
782 | I<$hlist>-E<gt>B<nearest>(I<y>) | |
783 | Given a y-coordinate within the HList window, this method returns | |
784 | the entryPath of the (visible) HList element nearest to that | |
785 | y-coordinate. | |
786 | ||
787 | =item I<$hlist>-E<gt>B<see>(I<$entryPath>) | |
788 | ||
789 | Adjust the view in the HList so that the entry given by I<$entryPath> is | |
790 | visible. If the entry is already visible then the method has no | |
791 | effect; if the entry is near one edge of the window then the HList | |
792 | scrolls to bring the element into view at the edge; otherwise the | |
793 | HList widget scrolls to center the entry. | |
794 | ||
795 | =item I<$hlist>-E<gt>B<selection>(I<option>, I<arg>, ...) | |
796 | ||
797 | =item I<$hlist>-E<gt>B<selection>I<Option>(I<arg>, ...) | |
798 | ||
799 | This method is used to adjust the selection within a HList widget. It | |
800 | has several forms, depending on I<option>: | |
801 | ||
802 | =over 8 | |
803 | ||
804 | =item I<$hlist>-E<gt>B<selectionClear>(?I<from>?, ?I<to>?) | |
805 | ||
806 | When no extra arguments are given, deselects all of the list entrie(s) | |
807 | in this HList widget. When only I<from> is given, only the list | |
808 | entry identified by I<from> is deselected. When both I<from> and | |
809 | I<to> are given, deselects all of the list entrie(s) between | |
810 | between I<from> and I<to>, inclusive, without affecting the | |
811 | selection state of elements outside that range. | |
812 | ||
813 | =item I<$hlist>-E<gt>B<selectionGet> | |
814 | ||
815 | This is an alias for the B<infoSelection> method. | |
816 | ||
817 | =item I<$hlist>-E<gt>B<selectionIncludes>(I<$entryPath>) | |
818 | ||
819 | Returns 1 if the list entry indicated by I<$entryPath> is currently | |
820 | selected; returns 0 otherwise. | |
821 | ||
822 | =item I<$hlist>-E<gt>B<selectionSet>(I<from>?, I<to>?) | |
823 | ||
824 | Selects all of the list entrie(s) between between I<from> and | |
825 | I<to>, inclusive, without affecting the selection state of entries | |
826 | outside that range. When only I<from> is given, only the list entry | |
827 | identified by I<from> is selected. | |
828 | ||
829 | =back | |
830 | ||
831 | =item I<$hlist>-E<gt>B<show>(I<option> ?,I<$entryPath>?) | |
832 | ||
833 | Show the entries that are hidden by the B<hide> method, | |
834 | I<option> can be one of the following: | |
835 | ||
836 | =over 8 | |
837 | ||
838 | =item B<entry> | |
839 | ||
840 | Shows the list entry identified by I<$entryPath>. | |
841 | ||
842 | =back | |
843 | ||
844 | Currently only the B<entry> option is supported. Other options will | |
845 | be added in future releases. | |
846 | ||
847 | =item I<$hlist>-E<gt>B<xview>(I<args>) | |
848 | ||
849 | This method is used to query and change the horizontal position of the | |
850 | information in the widget's window. It can take any of the following | |
851 | forms: | |
852 | ||
853 | =over 8 | |
854 | ||
855 | =item I<$hlist>-E<gt>B<xview> | |
856 | ||
857 | Returns a list containing two elements. Each element is a real | |
858 | fraction between 0 and 1; together they describe the horizontal span | |
859 | that is visible in the window. For example, if the first element is | |
860 | .2 and the second element is .6, 20% of the HList entry is | |
861 | off-screen to the left, the middle 40% is visible in the window, and | |
862 | 40% of the entry is off-screen to the right. These are the same values | |
863 | passed to scrollbars via the B<-xscrollcommand> option. | |
864 | ||
865 | =item I<$hlist>-E<gt>B<xview>(I<$entryPath>) | |
866 | ||
867 | Adjusts the view in the window so that the list entry identified by | |
868 | I<$entryPath> is aligned to the left edge of the window. | |
869 | ||
870 | =item I<$hlist>-E<gt>B<xview>(B<moveto> =E<gt> I<fraction>) | |
871 | ||
872 | Adjusts the view in the window so that I<fraction> of the total | |
873 | width of the HList is off-screen to the left. I<fraction> must be | |
874 | a fraction between 0 and 1. | |
875 | ||
876 | =item I<$hlist>-E<gt>B<xview>(B<scroll> =E<gt> I<number, what>) | |
877 | ||
878 | This method shifts the view in the window left or right according to | |
879 | I<number> and I<what>. I<Number> must be an integer. | |
880 | I<What> must be either B<units> or B<pages> or an | |
881 | abbreviation of one of these. If I<what> is B<units>, the view | |
882 | adjusts left or right by I<number> character units (the width of | |
883 | the B<0> character) on the display; if it is B<pages> then the | |
884 | view adjusts by I<number> screenfuls. If I<number> is negative | |
885 | then characters farther to the left become visible; if it is positive | |
886 | then characters farther to the right become visible. | |
887 | ||
888 | =back | |
889 | ||
890 | =item I<$hlist>-E<gt>B<yview>(I<?args>?) | |
891 | ||
892 | This method is used to query and change the vertical position of the | |
893 | entries in the widget's window. It can take any of the following forms: | |
894 | ||
895 | =over 8 | |
896 | ||
897 | =item I<$hlist>-E<gt>B<yview> | |
898 | ||
899 | Returns a list containing two elements, both of which are real | |
900 | fractions between 0 and 1. The first element gives the position of | |
901 | the list element at the top of the window, relative to the HList as a | |
902 | whole (0.5 means it is halfway through the HList, for example). The | |
903 | second element gives the position of the list entry just after the | |
904 | last one in the window, relative to the HList as a whole. These are | |
905 | the same values passed to scrollbars via the B<-yscrollcommand> | |
906 | option. | |
907 | ||
908 | =item I<$hlist>-E<gt>B<yview>(I<$entryPath>) | |
909 | ||
910 | Adjusts the view in the window so that the list entry given by | |
911 | I<$entryPath> is displayed at the top of the window. | |
912 | ||
913 | =item I<$hlist>-E<gt>B<yview>(B<moveto> =E<gt> I<fraction>) | |
914 | ||
915 | Adjusts the view in the window so that the list entry given by | |
916 | I<fraction> appears at the top of the window. I<Fraction> is a | |
917 | fraction between 0 and 1; 0 indicates the first entry in the | |
918 | HList, 0.33 indicates the entry one-third the way through the | |
919 | HList, and so on. | |
920 | ||
921 | =item I<$hlist>-E<gt>B<yview>(B<scroll> =E<gt> I<number, what>) | |
922 | ||
923 | This method adjust the view in the window up or down according to | |
924 | I<number> and I<what>. I<Number> must be an integer. | |
925 | I<What> must be either B<units> or B<pages>. If I<what> | |
926 | is B<units>, the view adjusts up or down by I<number> lines; if | |
927 | it is B<pages> then the view adjusts by I<number> screenfuls. | |
928 | If I<number> is negative then earlier entries become visible; if | |
929 | it is positive then later entries become visible. | |
930 | ||
931 | =back | |
932 | ||
933 | =back | |
934 | ||
935 | =head1 BINDINGS | |
936 | ||
937 | =over 4 | |
938 | ||
939 | =item [1] | |
940 | ||
941 | If the B<-selectmode> is "browse", when the user drags the mouse | |
942 | pointer over the list entries, the entry under the pointer will be | |
943 | highlighted and the B<-browsecmd> callback will be called with | |
944 | one parameter, the entryPath of the highlighted entry. Only one entry | |
945 | can be highlighted at a time. The B<-command> callback will be | |
946 | called when the user double-clicks on a list entry. | |
947 | ||
948 | =item [2] | |
949 | ||
950 | If the B<-selectmode> is "single", the entries will only be | |
951 | highlighted by mouse E<lt>ButtonRelease-1E<gt> events. When a new list entry | |
952 | is highlighted, the B<-browsecmd> callback will be called with | |
953 | one parameter indicating the highlighted list entry. The | |
954 | B<-command> callback will be called when the user double-clicks | |
955 | on a list entry. | |
956 | ||
957 | =item [3] | |
958 | ||
959 | If the B<-selectmode> is "multiple", when the user drags the mouse | |
960 | pointer over the list entries, all the entries under the pointer will | |
961 | be highlighted. However, only a contiguous region of list entries can | |
962 | be selected. When the highlighted area is changed, the | |
963 | B<-browsecmd> callback will be called with an undefined | |
964 | parameter. It is the responsibility of the B<-browsecmd> callback | |
965 | to find out the exact highlighted selection in the HList. The | |
966 | B<-command> callback will be called when the user double-clicks | |
967 | on a list entry. | |
968 | ||
969 | =item [4] | |
970 | ||
971 | If the B<-selectmode> is "extended", when the user drags the mouse | |
972 | pointer over the list entries, all the entries under the pointer will | |
973 | be highlighted. The user can also make disjointed selections using | |
974 | E<lt>Control-ButtonPress-1E<gt>. When the highlighted area is changed, the | |
975 | B<-browsecmd> callback will be called with an undefined | |
976 | parameter. It is the responsibility of the B<-browsecmd> callback | |
977 | to find out the exact highlighted selection in the HList. The | |
978 | B<-command> callback will be called when the user double-clicks | |
979 | on a list entry. | |
980 | ||
981 | =item [5] | |
982 | ||
983 | B<Arrow key bindings:> E<lt>UpE<gt> arrow key moves the anchor point to the | |
984 | item right on top of the current anchor item. E<lt>DownE<gt> arrow key moves | |
985 | the anchor point to the item right below the current anchor item. | |
986 | E<lt>LeftE<gt> arrow key moves the anchor to the parent item of the current | |
987 | anchor item. E<lt>RightE<gt> moves the anchor to the first child of the | |
988 | current anchor item. If the current anchor item does not have any | |
989 | children, moves the anchor to the item right below the current anchor | |
990 | item. | |
991 | ||
992 | =back | |
993 | ||
994 | =head1 EXAMPLE | |
995 | ||
996 | This example demonstrates how to use an HList to store a file | |
997 | directory structure and respond to the user's browse events: | |
998 | ||
999 | use strict; | |
1000 | use Tk; | |
1001 | use Tk::Label; | |
1002 | use Tk::HList; | |
1003 | ||
1004 | my $mw = MainWindow->new(); | |
1005 | my $label = $mw->Label(-width=>15); | |
1006 | my $hlist = $mw->HList( | |
1007 | -itemtype => 'text', | |
1008 | -separator => '/', | |
1009 | -selectmode => 'single', | |
1010 | -browsecmd => sub { | |
1011 | my $file = shift; | |
1012 | $label->configure(-text=>$file); | |
1013 | } | |
1014 | ); | |
1015 | ||
1016 | foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) { | |
1017 | $hlist->add($_, -text=>$_); | |
1018 | } | |
1019 | ||
1020 | $hlist->pack; | |
1021 | $label->pack; | |
1022 | ||
1023 | MainLoop; | |
1024 | ||
1025 | =head1 BUGS | |
1026 | ||
1027 | The fact that the display item at column 0 is implicitly associated | |
1028 | with the whole entry is probably a design bug. This was done for | |
1029 | backward compatibility purposes. The result is that there is a large | |
1030 | overlap between the B<item> method and the B<add>, | |
1031 | B<addchild>, B<entrycget> and B<entryconfigure> | |
1032 | methods. Whenever multiple columns exist, the programmer should use | |
1033 | ONLY the B<item> method to create and configure the display items | |
1034 | in each column; the B<add>, B<addchild>, B<entrycget> and | |
1035 | B<entryconfigure> should be used ONLY to create and configure | |
1036 | entries. | |
1037 | ||
1038 | =head1 KEYWORDS | |
1039 | ||
1040 | Hierarchical Listbox | |
1041 | ||
1042 | =head1 SEE ALSO | |
1043 | ||
1044 | L<Tk::DItem|Tk::DItem> | |
1045 | ||
1046 | =cut | |
1047 | ||
1048 |