Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "HLIST 1" | |
132 | .TH HLIST 1 "2000-12-30" "perl v5.8.0" "User Contributed Perl Documentation" | |
133 | .SH "NAME" | |
134 | Tk::HList \- Create and manipulate Tix Hierarchial List widgets | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | \&\fI$hlist\fR = \fI$parent\fR\->\fBHList\fR(?\fIoptions\fR?); | |
138 | .SH "STANDARD OPTIONS" | |
139 | .IX Header "STANDARD OPTIONS" | |
140 | \&\fB\-background\fR \fB\-borderwidth\fR \fB\-cursor\fR \fB\-exportselection\fR | |
141 | \&\fB\-foreground\fR \fB\-font\fR \fB\-height\fR \fB\-highlightcolor\fR | |
142 | \&\fB\-highlightthickness\fR \fB\-relief\fR \fB\-selectbackground\fR | |
143 | \&\fB\-selectforeground\fR \fB\-xscrollcommand\fR \fB\-yscrollcommand\fR | |
144 | \&\fB\-width\fR | |
145 | .PP | |
146 | See Tk::options for details of the standard options. | |
147 | .SH "WIDGET-SPECIFIC OPTIONS" | |
148 | .IX Header "WIDGET-SPECIFIC OPTIONS" | |
149 | .IP "Name: \fBbrowsecmd\fR" 4 | |
150 | .IX Item "Name: browsecmd" | |
151 | .PD 0 | |
152 | .IP "Class: \fBBrowseCmd\fR" 4 | |
153 | .IX Item "Class: BrowseCmd" | |
154 | .IP "Switch: \fB\-browsecmd\fR" 4 | |
155 | .IX Item "Switch: -browsecmd" | |
156 | .PD | |
157 | Specifies a perl/Tk callback to be executed when the user browses through the | |
158 | entries in the HList widget. | |
159 | .IP "Name: \fBcolumns\fR" 4 | |
160 | .IX Item "Name: columns" | |
161 | .PD 0 | |
162 | .IP "Class: \fBColumns\fR" 4 | |
163 | .IX Item "Class: Columns" | |
164 | .IP "Switch: \fB\-columns\fR" 4 | |
165 | .IX Item "Switch: -columns" | |
166 | .PD | |
167 | Specifies the number of columns in this HList widget. This option can | |
168 | only be set during the creation of the HList widget and cannot be | |
169 | changed subsequently. | |
170 | .IP "Name: \fBcommand\fR" 4 | |
171 | .IX Item "Name: command" | |
172 | .PD 0 | |
173 | .IP "Class: \fBCommand\fR" 4 | |
174 | .IX Item "Class: Command" | |
175 | .IP "Switch: \fB\-command\fR" 4 | |
176 | .IX Item "Switch: -command" | |
177 | .PD | |
178 | Specifies the perl/Tk callback to be executed when the user invokes a list | |
179 | entry in the HList widget. Normally the user invokes a list | |
180 | entry by double-clicking it or pressing the Return key. | |
181 | .IP "Name: \fBdrawBranch\fR" 4 | |
182 | .IX Item "Name: drawBranch" | |
183 | .PD 0 | |
184 | .IP "Class: \fBDrawBranch\fR" 4 | |
185 | .IX Item "Class: DrawBranch" | |
186 | .IP "Switch: \fB\-drawbranch\fR" 4 | |
187 | .IX Item "Switch: -drawbranch" | |
188 | .PD | |
189 | A Boolean value to specify whether branch line should be drawn to | |
190 | connect list entries to their parents. | |
191 | .IP "Name: \fBforeground\fR" 4 | |
192 | .IX Item "Name: foreground" | |
193 | .PD 0 | |
194 | .IP "Class: \fBForeground\fR" 4 | |
195 | .IX Item "Class: Foreground" | |
196 | .IP "Switch: \fB\-foreground\fR" 4 | |
197 | .IX Item "Switch: -foreground" | |
198 | .IP "Alias: \fB\-fg\fR" 4 | |
199 | .IX Item "Alias: -fg" | |
200 | .PD | |
201 | \&\fB[\s-1OBSOLETE\s0]\fR Specifies the default foreground color for the list entries. | |
202 | .IP "Name: \fBgap\fR" 4 | |
203 | .IX Item "Name: gap" | |
204 | .PD 0 | |
205 | .IP "Class: \fBGap\fR" 4 | |
206 | .IX Item "Class: Gap" | |
207 | .IP "Switch: \fB\-gap\fR" 4 | |
208 | .IX Item "Switch: -gap" | |
209 | .PD | |
210 | \&\fB[\s-1OBSOLETE\s0]\fR The default distance between the bitmap/image and the | |
211 | text in list entries. | |
212 | .IP "Name: \fBheader\fR" 4 | |
213 | .IX Item "Name: header" | |
214 | .PD 0 | |
215 | .IP "Class: \fBHeader\fR" 4 | |
216 | .IX Item "Class: Header" | |
217 | .IP "Switch: \fB\-header\fR" 4 | |
218 | .IX Item "Switch: -header" | |
219 | .PD | |
220 | A Boolean value specifying whether headers should be displayed for | |
221 | this HList widget (see the \fBheader\fR method below). | |
222 | .IP "Name: \fBheight\fR" 4 | |
223 | .IX Item "Name: height" | |
224 | .PD 0 | |
225 | .IP "Class: \fBHeight\fR" 4 | |
226 | .IX Item "Class: Height" | |
227 | .IP "Switch: \fB\-height\fR" 4 | |
228 | .IX Item "Switch: -height" | |
229 | .PD | |
230 | Specifies the desired height for the window in number of characters. | |
231 | .IP "Name: \fBindent\fR" 4 | |
232 | .IX Item "Name: indent" | |
233 | .PD 0 | |
234 | .IP "Class: \fBIndent\fR" 4 | |
235 | .IX Item "Class: Indent" | |
236 | .IP "Switch: \fB\-indent\fR" 4 | |
237 | .IX Item "Switch: -indent" | |
238 | .PD | |
239 | Specifies the amount of horizontal indentation between a list entry | |
240 | and its children. Must be a valid screen distance value. | |
241 | .IP "Name: \fBindicator\fR" 4 | |
242 | .IX Item "Name: indicator" | |
243 | .PD 0 | |
244 | .IP "Class: \fBIndicator\fR" 4 | |
245 | .IX Item "Class: Indicator" | |
246 | .IP "Switch: \fB\-indicator\fR" 4 | |
247 | .IX Item "Switch: -indicator" | |
248 | .PD | |
249 | Specifies whether the indicators should be displayed inside the HList | |
250 | widget. See the \fBindicator\fR method below. | |
251 | .IP "Name: \fBindicatorCmd\fR" 4 | |
252 | .IX Item "Name: indicatorCmd" | |
253 | .PD 0 | |
254 | .IP "Class: \fBIndicatorCmd\fR" 4 | |
255 | .IX Item "Class: IndicatorCmd" | |
256 | .IP "Switch: \fB\-indicatorcmd\fR" 4 | |
257 | .IX Item "Switch: -indicatorcmd" | |
258 | .PD | |
259 | Specifies a perl/Tk callback to be executed when the user manipulates the | |
260 | indicator of an HList entry. The \fB\-indicatorcmd\fR is triggered | |
261 | when the user press or releases the mouse button over the indicator in | |
262 | an HList entry. By default the perl/Tk \fBcallback\fR specified by | |
263 | \&\fB\-indicatorcmd\fR is executed with two additional arguments, the | |
264 | entryPath of the entry whose indicator has been triggered and additional | |
265 | information about the event. The additional information is one of the | |
266 | following strings: \fB<Arm>\fR, \fB<Disarm>\fR, | |
267 | and \fB<Activate>\fR. | |
268 | .IP "Name: \fBitemType\fR" 4 | |
269 | .IX Item "Name: itemType" | |
270 | .PD 0 | |
271 | .IP "Class: \fBItemType\fR" 4 | |
272 | .IX Item "Class: ItemType" | |
273 | .IP "Switch: \fB\-itemtype\fR" 4 | |
274 | .IX Item "Switch: -itemtype" | |
275 | .PD | |
276 | Specifies the default type of display item for this HList widget. When | |
277 | you call the \fBitemCreate\fR, \fBadd\fR and \fBaddchild\fR methods, display | |
278 | items of this | |
279 | type will be created if the \fB\-itemtype\fR option is not specified . | |
280 | .IP "Name: \fBpadX\fR" 4 | |
281 | .IX Item "Name: padX" | |
282 | .PD 0 | |
283 | .IP "Class: \fBPad\fR" 4 | |
284 | .IX Item "Class: Pad" | |
285 | .IP "Switch: \fB\-padx\fR" 4 | |
286 | .IX Item "Switch: -padx" | |
287 | .PD | |
288 | \&\fB[\s-1OBSOLETE\s0]\fR The default horizontal padding for list entries. | |
289 | .IP "Name: \fBpadY\fR" 4 | |
290 | .IX Item "Name: padY" | |
291 | .PD 0 | |
292 | .IP "Class: \fBPad\fR" 4 | |
293 | .IX Item "Class: Pad" | |
294 | .IP "Switch: \fB\-padx\fR" 4 | |
295 | .IX Item "Switch: -padx" | |
296 | .PD | |
297 | \&\fB[\s-1OBSOLETE\s0]\fR The default vertical padding for list entries. | |
298 | .IP "Name: \fBselectBackground\fR" 4 | |
299 | .IX Item "Name: selectBackground" | |
300 | .PD 0 | |
301 | .IP "Class: \fBSelectBackground\fR" 4 | |
302 | .IX Item "Class: SelectBackground" | |
303 | .IP "Switch: \fB\-selectbackground\fR" 4 | |
304 | .IX Item "Switch: -selectbackground" | |
305 | .PD | |
306 | Specifies the background color for the selected list entries. | |
307 | .IP "Name: \fBselectBorderWidth\fR" 4 | |
308 | .IX Item "Name: selectBorderWidth" | |
309 | .PD 0 | |
310 | .IP "Class: \fBBorderWidth\fR" 4 | |
311 | .IX Item "Class: BorderWidth" | |
312 | .IP "Switch: \fB\-selectborderwidth\fR" 4 | |
313 | .IX Item "Switch: -selectborderwidth" | |
314 | .PD | |
315 | Specifies a non-negative value indicating the width of the 3\-D border | |
316 | to draw around selected items. The value may have any of the forms | |
317 | acceptable to \fBTk_GetPixels\fR. | |
318 | .IP "Name: \fBselectForeground\fR" 4 | |
319 | .IX Item "Name: selectForeground" | |
320 | .PD 0 | |
321 | .IP "Class: \fBSelectForeground\fR" 4 | |
322 | .IX Item "Class: SelectForeground" | |
323 | .IP "Switch: \fB\-selectforeground\fR" 4 | |
324 | .IX Item "Switch: -selectforeground" | |
325 | .PD | |
326 | Specifies the foreground color for the selected list entries. | |
327 | .IP "Name: \fBselectMode\fR" 4 | |
328 | .IX Item "Name: selectMode" | |
329 | .PD 0 | |
330 | .IP "Class: \fBSelectMode\fR" 4 | |
331 | .IX Item "Class: SelectMode" | |
332 | .IP "Switch: \fB\-selectmode\fR" 4 | |
333 | .IX Item "Switch: -selectmode" | |
334 | .PD | |
335 | Specifies one of several styles for manipulating the selection. The | |
336 | value of the option may be arbitrary, but the default bindings expect | |
337 | it to be either \fBsingle\fR, \fBbrowse\fR, \fBmultiple\fR, or | |
338 | \&\fBextended\fR; the default value is \fBsingle\fR. | |
339 | .IP "Name: \fBsizeCmd\fR" 4 | |
340 | .IX Item "Name: sizeCmd" | |
341 | .PD 0 | |
342 | .IP "Class: \fBSizeCmd\fR" 4 | |
343 | .IX Item "Class: SizeCmd" | |
344 | .IP "Switch: \fB\-sizecmd\fR" 4 | |
345 | .IX Item "Switch: -sizecmd" | |
346 | .PD | |
347 | Specifies a perl/Tk callback to be called whenever the HList widget | |
348 | changes its size. This method can be useful to implement ``\fIuser scroll | |
349 | bars when needed\fR'' features. | |
350 | .IP "Name: \fBseparator\fR" 4 | |
351 | .IX Item "Name: separator" | |
352 | .PD 0 | |
353 | .IP "Class: \fBSeparator\fR" 4 | |
354 | .IX Item "Class: Separator" | |
355 | .IP "Switch: \fB\-separator\fR" 4 | |
356 | .IX Item "Switch: -separator" | |
357 | .PD | |
358 | Specifies the character to used as the separator character when | |
359 | intepreting the path-names of list entries. By default the character | |
360 | \&\*(L".\*(R" is used. | |
361 | .IP "Name: \fBwidth\fR" 4 | |
362 | .IX Item "Name: width" | |
363 | .PD 0 | |
364 | .IP "Class: \fBWidth\fR" 4 | |
365 | .IX Item "Class: Width" | |
366 | .IP "Switch: \fB\-width\fR" 4 | |
367 | .IX Item "Switch: -width" | |
368 | .PD | |
369 | Specifies the desired width for the window in characters. | |
370 | .SH "DESCRIPTION" | |
371 | .IX Header "DESCRIPTION" | |
372 | The \fBHList\fR method creates a new window (given by the | |
373 | \&\f(CW$widget\fR argument) and makes it into a HList widget. | |
374 | Additional options, described above, may be specified on the command | |
375 | line or in the option database to configure aspects of the | |
376 | HList widget such as its cursor and relief. | |
377 | .PP | |
378 | The HList widget can be used to display any data that have a | |
379 | hierarchical structure, for example, file system directory trees. The | |
380 | list entries are indented and connected by branch lines according to | |
381 | their places in the hierachy. | |
382 | .PP | |
383 | Each list entry is identified by an \fBentryPath\fR. The entryPath is a | |
384 | sequence of \fBentry names\fR separated by the separator charactor | |
385 | (specified by the \fB\-separator\fR option). An \fBentry name\fR can be | |
386 | any string that does not contain the separator charactor, or it can be | |
387 | the a string that contains only one separator charactor. | |
388 | .PP | |
389 | For example, when \*(L".\*(R" is used as the separator charactor, | |
390 | \&\*(L"one.two.three\*(R" is the entryPath for a list entry whose parent is | |
391 | \&\*(L"one.two\*(R", whose parent is \*(L"one\*(R", which is a toplevel entry (has no | |
392 | parents). | |
393 | .PP | |
394 | Another examples: \*(L".two.three\*(R" is the entryPath for a list entry whose | |
395 | parent is \*(L".two\*(R", whose parent is \*(L".\*(R", which is a toplevel entry. | |
396 | .SH "DISPLAY ITEMS" | |
397 | .IX Header "DISPLAY ITEMS" | |
398 | Each list entry in an HList widget is associated with a \fBdisplay\fR | |
399 | item. The display item determines what visual information should | |
400 | be displayed for this list entry. Please see Tk::DItem | |
401 | for a list of all display items. | |
402 | When a list entry is created by the \fBitemCreate\fR, \fBadd\fR or | |
403 | \&\fBaddchild\fR widget | |
404 | methods, the type of its display item is determined by the | |
405 | \&\fB\-itemtype\fR option passed to these methods. If the | |
406 | \&\fB\-itemtype\fR is omitted, then by default the type specified by | |
407 | this HList widget's \fB\-itemtype\fR option is used. | |
408 | .SH "WIDGET METHODS" | |
409 | .IX Header "WIDGET METHODS" | |
410 | The \fBHList\fR method creates a widget object. | |
411 | This object supports the \fBconfigure\fR and \fBcget\fR methods | |
412 | described in Tk::options which can be used to enquire and | |
413 | modify the options described above. | |
414 | The widget also inherits all the methods provided by the generic | |
415 | Tk::Widget class. | |
416 | .PP | |
417 | The following additional methods are available HList widgets: | |
418 | .IP "\fI$hlist\fR\->\fBadd\fR(\fI$entryPath\fR ?,\fIoption\fR=>\fIvalue\fR, ...?)" 4 | |
419 | .IX Item "$hlist->add($entryPath ?,option=>value, ...?)" | |
420 | Creates a new list entry with the pathname \fI$entryPath\fR. A list | |
421 | entry must be created after its parent is created (unless this entry | |
422 | is a top-level entry, which has no parent). See also \*(L"\s-1BUGS\s0\*(R" below. | |
423 | This method returns the | |
424 | entryPath of the newly created list entry. The following | |
425 | configuration options can be given to configure the list entry: | |
426 | .RS 4 | |
427 | .IP "\fB\-at\fR => \fIposition\fR" 8 | |
428 | .IX Item "-at => position" | |
429 | Insert the new list at the position given by \fIposition\fR. | |
430 | \&\fIposition\fR must be a valid integer. The position \fB0\fR indicates | |
431 | the first position, \fB1\fR indicates the second position, and so on. | |
432 | .IP "\fB\-after\fR => \fIafterWhich\fR" 8 | |
433 | .IX Item "-after => afterWhich" | |
434 | Insert the new list entry after the entry identified by | |
435 | \&\fIafterWhich\fR. \fIafterWhich\fR must be a valid list entry and it | |
436 | mush have the same parent as the new list entry | |
437 | .IP "\fB\-before\fR => \fIbeforeWhich\fR" 8 | |
438 | .IX Item "-before => beforeWhich" | |
439 | Insert the new list entry before the entry identified by | |
440 | \&\fIbeforeWhich\fR. \fIbeforeWhich\fR must be a valid list entry and it | |
441 | mush have the same parent as the new list entry | |
442 | .IP "\fB\-data\fR => \fIstring\fR" 8 | |
443 | .IX Item "-data => string" | |
444 | Specifies a string to associate with this list entry. This string can | |
445 | be queried by the \fBinfo\fR method. The application | |
446 | programmer can use the \fB\-data\fR option to associate the list entry | |
447 | with the data it represents. | |
448 | .IP "\fB\-itemtype\fR => \fItype\fR" 8 | |
449 | .IX Item "-itemtype => type" | |
450 | Specifies the type of display item to be display for the new list | |
451 | entry. \fBtype\fR must be a valid display item type. Currently the | |
452 | available display item types are \fBimagetext\fR, \fBtext\fR, and | |
453 | \&\f(CW$widget\fR. If this option is not specified, then by default the | |
454 | type specified by this HList widget's \fB\-itemtype\fR option is used. | |
455 | .IP "\fB\-state\fR => \fIstate\fR" 8 | |
456 | .IX Item "-state => state" | |
457 | Specifies whether this entry can be selected or invoked by the user. | |
458 | Must be either \fBnormal\fR or \fBdisabled\fR. | |
459 | .RE | |
460 | .RS 4 | |
461 | .Sp | |
462 | The \fBadd\fR method accepts additional configuration options | |
463 | to configure the display item associated with this list entry. The set | |
464 | of additional configuration options depends on the type of the display | |
465 | item given by the \fB\-itemtype\fR option. Please see | |
466 | Tk::DItem for a list of the configuration options for | |
467 | each of the display item types. | |
468 | .RE | |
469 | .IP "\fI$hlist\fR\->\fBaddchild\fR(\fI$parentPath, \fR?\fIoption, value, ..., \fR?)" 4 | |
470 | .IX Item "$hlist->addchild($parentPath, ?option, value, ..., ?)" | |
471 | Adds a new child entry to the children list of the list entry | |
472 | identified by \fI$parentPath\fR. Or, if \fI$parentPath\fR is set to be | |
473 | the empty string, then creates a new toplevel entry. The name of the | |
474 | new list entry will be a unique name automatically generated by the | |
475 | HList widget. Usually if \fI$parentPath\fR is \fBfoo\fR, then the | |
476 | entryPath of the new entry will be \fBfoo.0\fR, \fBfoo.1\fR, ... etc. | |
477 | This method returns the entryPath of the newly created list entry. | |
478 | \&\fIoption\fR can be any option for the \fBadd\fR method. | |
479 | See also \*(L"\s-1BUGS\s0\*(R" below. | |
480 | .IP "\fI$hlist\fR\->\fBanchorSet\fR(\fI$entryPath\fR)" 4 | |
481 | .IX Item "$hlist->anchorSet($entryPath)" | |
482 | Sets the anchor to the list entry identified by \fI$entryPath\fR. The | |
483 | anchor is the end of the selection that is fixed while the user is | |
484 | dragging out a selection with the mouse. | |
485 | .IP "\fI$hlist\fR\->\fBanchorClear\fR" 4 | |
486 | .IX Item "$hlist->anchorClear" | |
487 | Removes the anchor, if any, from this HList widget. This only | |
488 | removes the surrounding highlights of the anchor entry and does not | |
489 | affect its selection status. | |
490 | .IP "\fI$hlist\fR\->\fBcolumnWidth\fR(\fI$col\fR?, \fI\-char\fR?, ?\fIwidth\fR?)" 4 | |
491 | .IX Item "$hlist->columnWidth($col?, -char?, ?width?)" | |
492 | Querys or sets the width of a the column \fI$col\fR in the HList | |
493 | widget. The value of \fI$col\fR is zero\-based: 0 stands for the first | |
494 | column, 1 stands for the second, and so on. If no further parameters | |
495 | are given, returns the current width of this column (in number of | |
496 | pixels). Additional parameters can be given to set the width of this | |
497 | column: | |
498 | .RS 4 | |
499 | .IP "\fI$hlist\fR\->\fBcolumnWidth\fR(\fI$col\fR, \fB''\fR)" 8 | |
500 | .IX Item "$hlist->columnWidth($col, '')" | |
501 | An empty string indicates that the width of the column should be just | |
502 | wide enough to display the widest element in this column. In this | |
503 | case, the width of this column may change as a result of the elements | |
504 | in this column changing their sizes. | |
505 | .IP "\fI$hlist\fR\->\fBcolumnWidth\fR(\fI$col, \fR\fIwidth\fR)" 8 | |
506 | .IX Item "$hlist->columnWidth($col, width)" | |
507 | \&\fIwidth\fR must be in a form accepted by \fBTk_GetPixels\fR. | |
508 | .IP "\fI$hlist\fR\->\fBcolumnWidth\fR(\fI$col, \fR\fB\-char, \fR\fInChars\fR)" 8 | |
509 | .IX Item "$hlist->columnWidth($col, -char, nChars)" | |
510 | The width is set to be the average width occupied by \fInChars\fR | |
511 | number of characters of the font specified by the \fB\-font\fR option | |
512 | of this HList widget. | |
513 | .RE | |
514 | .RS 4 | |
515 | .RE | |
516 | .IP "\fI$hlist\fR\->\fBdelete\fR(\fIoption\fR, \fI$entryPath\fR)" 4 | |
517 | .IX Item "$hlist->delete(option, $entryPath)" | |
518 | Delete one or more list entries. \fIoption\fR may be one of the | |
519 | following: | |
520 | .RS 4 | |
521 | .IP "\fBall\fR" 8 | |
522 | .IX Item "all" | |
523 | Delete all entries in the HList. In this case the \fI$entryPath\fR | |
524 | does not need to be specified. | |
525 | .IP "\fBentry\fR" 8 | |
526 | .IX Item "entry" | |
527 | Delete the entry specified by \fI$entryPath\fR and all its offsprings, | |
528 | if any. | |
529 | .IP "\fBoffsprings\fR" 8 | |
530 | .IX Item "offsprings" | |
531 | Delete all the offsprings, if any, of the entry specified by | |
532 | \&\fI$entryPath\fR. However, \fI$entryPath\fR itself is not deleted. | |
533 | .IP "\fBsiblings\fR" 8 | |
534 | .IX Item "siblings" | |
535 | Delete all the list entries that share the same parent with the entry | |
536 | specified by \fI$entryPath\fR. However, \fI$entryPath\fR itself is not | |
537 | deleted. | |
538 | .RE | |
539 | .RS 4 | |
540 | .RE | |
541 | .IP "\fI$hlist\fR\->\fBdragsiteSet\fR(\fI$entryPath\fR)" 4 | |
542 | .IX Item "$hlist->dragsiteSet($entryPath)" | |
543 | Sets the dragsite to the list entry identified by | |
544 | \&\fI$entryPath\fR. The dragsite is used to indicate the source of a | |
545 | drag-and-drop action. Currently drag-and-drop functionality has not | |
546 | been implemented in Tix yet. | |
547 | .IP "\fI$hlist\fR\->\fBdragsiteClear\fR" 4 | |
548 | .IX Item "$hlist->dragsiteClear" | |
549 | Remove the dragsite, if any, from the this HList widget. This only | |
550 | removes the surrounding highlights of the dragsite entry and does not | |
551 | affect its selection status. | |
552 | .IP "\fI$hlist\fR\->\fBdropsiteSet\fR(\fI$entryPath\fR)" 4 | |
553 | .IX Item "$hlist->dropsiteSet($entryPath)" | |
554 | Sets the dropsite to the list entry identified by \fI$entryPath\fR. The | |
555 | dropsite is used to indicate the target of a drag-and-drop | |
556 | action. Currently drag-and-drop functionality has not been implemented | |
557 | in Tix yet. | |
558 | .IP "\fI$hlist\fR\->\fBdropsiteClear\fR" 4 | |
559 | .IX Item "$hlist->dropsiteClear" | |
560 | Remove the dropsite, if any, from the this HList widget. This only | |
561 | removes the surrounding highlights of the dropsite entry and does not | |
562 | affect its selection status. | |
563 | .IP "\fI$hlist\fR\->\fBentrycget\fR(\fI$entryPath\fR, \fIoption\fR)" 4 | |
564 | .IX Item "$hlist->entrycget($entryPath, option)" | |
565 | Returns the current value of the configuration option given by | |
566 | \&\fIoption\fR for the entry indentfied by \fI$entryPath\fR. \fIOption\fR | |
567 | may have any of the values accepted by the \fBadd\fR method. | |
568 | .IP "\fI$hlist\fR\->\fBentryconfigure\fR(\fI$entryPath\fR ?,\fIoption\fR?, ?\fIvalue\fR=>\fIoption\fR, ...?)" 4 | |
569 | .IX Item "$hlist->entryconfigure($entryPath ?,option?, ?value=>option, ...?)" | |
570 | Query or modify the configuration options of the list entry indentfied | |
571 | by \fI$entryPath\fR. If no \fIoption\fR is specified, returns a list | |
572 | describing all of the available options for \fI$entryPath\fR (see | |
573 | Tk::options for information on the format of this list.) If | |
574 | \&\fIoption\fR is specified with no \fIvalue\fR, then the method | |
575 | returns a list describing the one named option (this list will be | |
576 | identical to the corresponding sublist of the value returned if no | |
577 | \&\fIoption\fR is specified). If one or more \fIoption-value\fR pairs | |
578 | are specified, then the method modifies the given option(s) to have | |
579 | the given value(s); in this case the method returns an empty string. | |
580 | \&\fIOption\fR may have any of the values accepted by the \fBadd\fR or | |
581 | \&\fBaddchild\fR method. The exact set of options depends on the | |
582 | value of the \fB\-itemtype\fR option passed to the the \fBadd\fR or | |
583 | \&\fBaddchild\fR method when this list entry is created. | |
584 | .IP "\fI$hlist\fR\->\fBheader\fR(\fIoption\fR, \fI$col\fR ?,\fIargs\fR, ...?)" 4 | |
585 | .IX Item "$hlist->header(option, $col ?,args, ...?)" | |
586 | Manipulates the header items of this HList widget. If the | |
587 | \&\fB\-header\fR option of this HList widget is set to true, then a | |
588 | header item is displayed at the top of each column. The \fI$col\fR | |
589 | argument for this method must be a valid integer. 0 indicates the | |
590 | first column, 1 the second column, ... and so on. This method | |
591 | supports the following options: | |
592 | .RS 4 | |
593 | .IP "\fI$hlist\fR\->\fBheader\fR(\fBcget\fR, \fI$col\fR, \fIoption\fR)" 8 | |
594 | .IX Item "$hlist->header(cget, $col, option)" | |
595 | If the \fI$col\fR\-th column has a header display item, returns the | |
596 | value of the specified \fIoption\fR of the header item. If the header | |
597 | doesn't exist, returns an error. | |
598 | .IP "\fI$hlist\fR\->\fBheader\fR(\fBconfigure, \fR\fI$col, \fR?\fIoption\fR?, \fI?value, option, value, ...\fR?)" 8 | |
599 | .IX Item "$hlist->header(configure, $col, ?option?, ?value, option, value, ...?)" | |
600 | Query or modify the configuration options of the header display item | |
601 | of the \fI$col\fR\-th column. The header item must exist, or an error | |
602 | will result. If no \fIoption\fR is specified, returns a list | |
603 | describing all of the available options for the header display item | |
604 | (see Tk::options for information on the format of this | |
605 | list.) If \fIoption\fR is specified with no \fIvalue\fR, then the | |
606 | method returns a list describing the one named option (this list will | |
607 | be identical to the corresponding sublist of the value returned if no | |
608 | \&\fIoption\fR is specified). If one or more \fIoption-value\fR pairs | |
609 | are specified, then the method modifies the given option(s) to have | |
610 | the given value(s); in this case the method returns an empty | |
611 | string. \fIOption\fR may have any of the values accepted by the | |
612 | \&\fBheader create\fR method. The exact set of options depends | |
613 | on the value of the \fB\-itemtype\fR option passed to the the \fBheader\fR | |
614 | create method when this display item was created. | |
615 | .IP "\fI$hlist\fR\->\fBheader\fR(\fBcreate, \fR\fI$col, \fR?\fI\-itemtype type\fR? ?\fIoption value ...\fR?" 8 | |
616 | .IX Item "$hlist->header(create, $col, ?-itemtype type? ?option value ...?" | |
617 | Creates a new display item as the header for the \fI$col\fR\-th | |
618 | column. See also \*(L"\s-1BUGS\s0\*(R" below. | |
619 | If an header display item already exists for this column, it | |
620 | will be replaced by the new item. An optional parameter | |
621 | \&\fI\-itemtype\fR can be used to specify what type of display item | |
622 | should be created. If the \fI\-itemtype\fR is not given, then by | |
623 | default the type specified by this HList widget's \fB\-itemtype\fR | |
624 | option is used. Additional parameters, in \fIoption-value\fR pairs, | |
625 | can be passed to configure the appearance of the display item. Each | |
626 | \&\fIoption-value\fR pair must be a valid option for this type of | |
627 | display item or one of the following: | |
628 | .RS 8 | |
629 | .IP "\fB\-borderwidth\fR => \fIcolor\fR" 12 | |
630 | .IX Item "-borderwidth => color" | |
631 | Specifies the border width of this header item. | |
632 | .IP "\fB\-headerbackground\fR => \fIcolor\fR" 12 | |
633 | .IX Item "-headerbackground => color" | |
634 | Specifies the background color of this header item. | |
635 | .IP "\fB\-relief\fR => \fItype\fR" 12 | |
636 | .IX Item "-relief => type" | |
637 | Specifies the relief type of the border of this header item. | |
638 | .RE | |
639 | .RS 8 | |
640 | .RE | |
641 | .IP "\fI$hlist\fR\->\fBheader\fR(\fBdelete, \fR\fI$col\fR)" 8 | |
642 | .IX Item "$hlist->header(delete, $col)" | |
643 | Deletes the header display item for the \fI$col\fR\-th column. | |
644 | .IP "\fI$hlist\fR\->\fBheader\fR(\fBexists, \fR\fI$col\fR)" 8 | |
645 | .IX Item "$hlist->header(exists, $col)" | |
646 | Return true if an header display item exists for the \fI$col\fR\-th | |
647 | column; return false otherwise. | |
648 | .IP "\fI$hlist\fR\->\fBheader\fR(\fBsize\fR, \fI$entryPath\fR)" 8 | |
649 | .IX Item "$hlist->header(size, $entryPath)" | |
650 | If an header display item exists for the \fI$col\fR\-th column , returns | |
651 | its size in pixels in a two element list \fI(width, height)\fR; | |
652 | returns an error if the header display item does not exist. | |
653 | .RE | |
654 | .RS 4 | |
655 | .RE | |
656 | .IP "\fI$hlist\fR\->\fBhide\fR(\fIoption\fR ?,\fI$entryPath\fR?)" 4 | |
657 | .IX Item "$hlist->hide(option ?,$entryPath?)" | |
658 | Makes some of entries invisible without deleting them. | |
659 | \&\fIOption\fR can be one of the following: | |
660 | .RS 4 | |
661 | .IP "\fBentry\fR" 8 | |
662 | .IX Item "entry" | |
663 | Hides the list entry identified by \fI$entryPath\fR. | |
664 | .RE | |
665 | .RS 4 | |
666 | .Sp | |
667 | Currently only the \fBentry\fR option is supported. Other options will | |
668 | be added in the next release. | |
669 | .RE | |
670 | .IP "\fI$hlist\fR\->\fBindicator\fR(\fIoption\fR, \fI$entryPath\fR, ?\fIargs, ...\fR?)" 4 | |
671 | .IX Item "$hlist->indicator(option, $entryPath, ?args, ...?)" | |
672 | Manipulates the indicator on the list entries. An indicator is usually | |
673 | a small display item (such as an image) that is displayed to the left | |
674 | to an entry to indicate the status of the entry. For example, it may | |
675 | be used to indicate whether a directory is opened or | |
676 | closed. \fIOption\fR can be one of the following: | |
677 | .RS 4 | |
678 | .IP "\fI$hlist\fR\->\fBindicator\fR(\fBcget\fR, \fI$entryPath\fR, \fIoption\fR)" 8 | |
679 | .IX Item "$hlist->indicator(cget, $entryPath, option)" | |
680 | If the list entry given by \fI$entryPath\fR has an indicator, returns | |
681 | the value of the specified \fIoption\fR of the indicator. If the | |
682 | indicator doesn't exist, returns an error. | |
683 | .IP "\fI$hlist\fR\->\fBindicator\fR(\fBconfigure\fR, \fI$entryPath\fR, ?\fIoption\fR?, \fI?value, option, value, ...\fR?)" 8 | |
684 | .IX Item "$hlist->indicator(configure, $entryPath, ?option?, ?value, option, value, ...?)" | |
685 | Query or modify the configuration options of the indicator display | |
686 | item of the entry specified by \fI$entryPath\fR. The indicator item | |
687 | must exist, or an error will result. If no \fIoption\fR is specified, | |
688 | returns a list describing all of the available options for the | |
689 | indicator display item (see Tk::options for information | |
690 | on the format of this list). If \fIoption\fR is specified with no | |
691 | \&\fIvalue\fR, then the method returns a list describing the one named | |
692 | option (this list will be identical to the corresponding sublist of | |
693 | the value returned if no \fIoption\fR is specified). If one or more | |
694 | \&\fIoption-value\fR pairs are specified, then the method modifies the | |
695 | given option(s) to have the given value(s); in this case the method | |
696 | returns an empty string. \fIOption\fR may have any of the values | |
697 | accepted by the \fBindicator create\fR method. The exact set | |
698 | of options depends on the value of the \fB\-itemtype\fR option passed | |
699 | to the the \fBindicator create\fR method when this display item | |
700 | was created. | |
701 | .IP "\fI$hlist\fR\->\fBindicator\fR(\fBcreate, \fR\fI$entryPath, \fR?, \fI\-itemtype type\fR? ?\fIoption value ...\fR?)" 8 | |
702 | .IX Item "$hlist->indicator(create, $entryPath, ?, -itemtype type? ?option value ...?)" | |
703 | Creates a new display item as the indicator for the entry specified by | |
704 | \&\fI$entryPath\fR. If an indicator display item already exists for this | |
705 | entry, it will be replaced by the new item. An optional parameter | |
706 | \&\fI\-itemtype\fR can be used to specify what type of display item | |
707 | should be created. If the \fI\-itemtype\fR is not given, then by | |
708 | default the type specified by this HList widget's \fB\-itemtype\fR | |
709 | option is used. Additional parameters, in \fIoption-value\fR pairs, | |
710 | can be passed to configure the appearance of the display item. Each | |
711 | \&\fIoption-value\fR pair must be a valid option for this type of | |
712 | display item. | |
713 | .IP "\fI$hlist\fR\->\fBindicator\fR(\fBdelete\fR, \fI$entryPath\fR)" 8 | |
714 | .IX Item "$hlist->indicator(delete, $entryPath)" | |
715 | Deletes the indicator display item for the entry given by \fI$entryPath\fR. | |
716 | .IP "\fI$hlist\fR\->\fBindicator\fR(\fBexists\fR, \fI$entryPath\fR)" 8 | |
717 | .IX Item "$hlist->indicator(exists, $entryPath)" | |
718 | Return true if an indicator display item exists for the entry given by | |
719 | \&\fI$entryPath\fR; return false otherwise. | |
720 | .IP "\fI$hlist\fR\->\fBindicator\fR(\fBsize\fR, \fI$entryPath\fR)" 8 | |
721 | .IX Item "$hlist->indicator(size, $entryPath)" | |
722 | If an indicator display item exists for the entry given by | |
723 | \&\fI$entryPath\fR, returns its size in a two element list of the form | |
724 | {\fIwidth height\fR}; returns an error if the indicator display item | |
725 | does not exist. | |
726 | .RE | |
727 | .RS 4 | |
728 | .RE | |
729 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fIoption\fR, \fIarg, ...\fR)" 4 | |
730 | .IX Item "$hlist->info(option, arg, ...)" | |
731 | Query information about the HList widget. \fIoption\fR can be one | |
732 | of the following: | |
733 | .RS 4 | |
734 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBanchor\fR)" 8 | |
735 | .IX Item "$hlist->info(anchor)" | |
736 | Returns the entryPath of the current anchor, if any, of the HList | |
737 | widget. If the anchor is not set, returns the empty string. | |
738 | .IP "\fI$hlist\fR\->\fBinfoBbox\fR(\fI$entryPath\fR)" 8 | |
739 | .IX Item "$hlist->infoBbox($entryPath)" | |
740 | Returns a list of four numbers describing the visible bounding box of | |
741 | the entry given \fI$entryPath\fR. The first two elements of the list | |
742 | give the x and y coordinates of the upper-left corner of the screen | |
743 | area covered by the entry (specified in pixels relative to the widget) | |
744 | and the last two elements give the lower-right corner of the area, in | |
745 | pixels. If no part of the entry given by index is visible on the | |
746 | screen then the result is an empty string; if the entry is partially | |
747 | visible, the result gives the only the visible area of the entry. | |
748 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBchildren\fR ?,\fI$entryPath\fR?)" 8 | |
749 | .IX Item "$hlist->info(children ?,$entryPath?)" | |
750 | If \fI$entryPath\fR is given, returns a list of the entryPath's of its | |
751 | children entries. Otherwise returns a list of the toplevel | |
752 | entryPath's. | |
753 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBdata\fR ?,\fI$entryPath\fR?)" 8 | |
754 | .IX Item "$hlist->info(data ?,$entryPath?)" | |
755 | Returns the data associated with \fI$entryPath\fR. | |
756 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBdragsite\fR)" 8 | |
757 | .IX Item "$hlist->info(dragsite)" | |
758 | Returns the entryPath of the current dragsite, if any, of the HList | |
759 | widget. If the dragsite is not set, returns the empty string. | |
760 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBdropsite\fR)" 8 | |
761 | .IX Item "$hlist->info(dropsite)" | |
762 | Returns the entryPath of the current dropsite, if any, of the HList | |
763 | widget. If the dropsite is not set, returns the empty string. | |
764 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBexists\fR, \fI$entryPath\fR)" 8 | |
765 | .IX Item "$hlist->info(exists, $entryPath)" | |
766 | Returns a boolean value indicating whether the list entry | |
767 | \&\fI$entryPath\fR exists. | |
768 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBhidden\fR, \fI$entryPath\fR)" 8 | |
769 | .IX Item "$hlist->info(hidden, $entryPath)" | |
770 | Returns a boolean value indicating whether the list entry | |
771 | \&\fB$entryPath\fR is hidden or not. | |
772 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBnext\fR, \fI$entryPath\fR)" 8 | |
773 | .IX Item "$hlist->info(next, $entryPath)" | |
774 | Returns the entryPath of the list entry, if any, immediately below | |
775 | this list entry. If this entry is already at the bottom of the HList | |
776 | widget, returns an empty string. | |
777 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBparent\fR, \fI$entryPath\fR)" 8 | |
778 | .IX Item "$hlist->info(parent, $entryPath)" | |
779 | Returns the name of the parent of the list entry identified by | |
780 | \&\fI$entryPath\fR. If \fIentryPath\fR is a toplevel list entry, | |
781 | returns the empty string. | |
782 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBprev\fR, \fI$entryPath\fR)" 8 | |
783 | .IX Item "$hlist->info(prev, $entryPath)" | |
784 | Returns the entryPath of the list entry, if any, immediately above | |
785 | this list entry. If this entry is already at the top of the HList | |
786 | widget, returns an empty string. | |
787 | .IP "\fI$hlist\fR\->\fBinfo\fR(\fBselection\fR)" 8 | |
788 | .IX Item "$hlist->info(selection)" | |
789 | Returns a list of selected entries in the HList widget. If no entries | |
790 | are selected, returns an empty string. | |
791 | .RE | |
792 | .RS 4 | |
793 | .RE | |
794 | .IP "\fI$hlist\fR\->\fBitem\fR(\fIoption, \fR?\fIargs, ...\fR?)" 4 | |
795 | .IX Item "$hlist->item(option, ?args, ...?)" | |
796 | Creates and configures the display items at individual columns the | |
797 | entries. The form of additional of arguments depends on the choice of | |
798 | \&\fIoption\fR: | |
799 | .RS 4 | |
800 | .IP "\fI$hlist\fR\->\fBitemCget\fR(\fI$entryPath\fR, \fI$col\fR, \fIoption\fR)" 8 | |
801 | .IX Item "$hlist->itemCget($entryPath, $col, option)" | |
802 | Returns the current value of the configure \fIoption\fR of the display | |
803 | item at the column designated by \fI$col\fR of the entry specified by | |
804 | \&\fI$entryPath\fR. | |
805 | .IP "\fI$hlist\fR\->\fBitemConfigure\fR(\fI$entryPath\fR, \fI$col\fR ?,\fIoption\fR?, \fI?value, option, value, ...\fR?)" 8 | |
806 | .IX Item "$hlist->itemConfigure($entryPath, $col ?,option?, ?value, option, value, ...?)" | |
807 | Query or modify the configuration options of the display item at the | |
808 | column designated by \fI$col\fR of the entry specified by | |
809 | \&\fI$entryPath\fR. If no \fIoption\fR is specified, returns a list | |
810 | describing all of the available options for \fI$entryPath\fR (see | |
811 | Tk::options for information on the format of this | |
812 | list). If \fIoption\fR is specified with no \fIvalue\fR, then the | |
813 | method returns a list describing the one named option (this list will | |
814 | be identical to the corresponding sublist of the value returned if no | |
815 | \&\fIoption\fR is specified). If one or more \fIoption-value\fR pairs | |
816 | are specified, then the method modifies the given option(s) to have | |
817 | the given value(s); in this case the method returns an empty string. | |
818 | \&\fIOption\fR may have any of the values accepted by the \fBitem\fR | |
819 | create method. The exact set of options depends on the | |
820 | value of the \fB\-itemtype\fR option passed to the the \fBitem\fR | |
821 | create method when this display item was created. | |
822 | .IP "\fI$hlist\fR\->\fBitemCreate\fR(\fI$entryPath\fR, \fI$col\fR ?,\fI\-itemtype\fR=>\fItype\fR? ?,\fIoption value ...\fR?)" 8 | |
823 | .IX Item "$hlist->itemCreate($entryPath, $col ?,-itemtype=>type? ?,option value ...?)" | |
824 | Creates a new display item at the column designated by \fI$col\fR of | |
825 | the entry specified by \fI$entryPath\fR. An optional parameter | |
826 | \&\fI\-itemtype\fR can be used to specify what type of display items | |
827 | should be created. If the \fI\-itemtype\fR is not specified, then by | |
828 | default the type specified by this HList widget's \fB\-itemtype\fR | |
829 | option is used. Additional parameters, in \fIoption-value\fR pairs, | |
830 | can be passed to configure the appearance of the display item. Each | |
831 | \&\fIoption\- value\fR pair must be a valid option for this type of | |
832 | display item. | |
833 | .IP "\fI$hlist\fR\->\fBitemDelete\fR(\fI$entryPath\fR, \fI$col\fR)" 8 | |
834 | .IX Item "$hlist->itemDelete($entryPath, $col)" | |
835 | Deletes the display item at the column designated by \fI$col\fR of | |
836 | the entry specified by \fI$entryPath\fR. | |
837 | .IP "\fI$hlist\fR\->\fBitemExists\fR(\fI$entryPath\fR, \fI$col\fR)" 8 | |
838 | .IX Item "$hlist->itemExists($entryPath, $col)" | |
839 | Returns true if there is a display item at the column designated by | |
840 | \&\fI$col\fR of the entry specified by \fI$entryPath\fR; returns false | |
841 | otherwise. | |
842 | .RE | |
843 | .RS 4 | |
844 | .RE | |
845 | .IP "\fI$hlist\fR\->\fBnearest\fR(\fIy\fR)" 4 | |
846 | .IX Item "$hlist->nearest(y)" | |
847 | \&\fI$hlist\fR\->\fBnearest\fR(\fIy\fR) | |
848 | Given a y\-coordinate within the HList window, this method returns | |
849 | the entryPath of the (visible) HList element nearest to that | |
850 | y\-coordinate. | |
851 | .IP "\fI$hlist\fR\->\fBsee\fR(\fI$entryPath\fR)" 4 | |
852 | .IX Item "$hlist->see($entryPath)" | |
853 | Adjust the view in the HList so that the entry given by \fI$entryPath\fR is | |
854 | visible. If the entry is already visible then the method has no | |
855 | effect; if the entry is near one edge of the window then the HList | |
856 | scrolls to bring the element into view at the edge; otherwise the | |
857 | HList widget scrolls to center the entry. | |
858 | .IP "\fI$hlist\fR\->\fBselection\fR(\fIoption\fR, \fIarg\fR, ...)" 4 | |
859 | .IX Item "$hlist->selection(option, arg, ...)" | |
860 | .PD 0 | |
861 | .IP "\fI$hlist\fR\->\fBselection\fR\fIOption\fR(\fIarg\fR, ...)" 4 | |
862 | .IX Item "$hlist->selectionOption(arg, ...)" | |
863 | .PD | |
864 | This method is used to adjust the selection within a HList widget. It | |
865 | has several forms, depending on \fIoption\fR: | |
866 | .RS 4 | |
867 | .IP "\fI$hlist\fR\->\fBselectionClear\fR(?\fIfrom\fR?, ?\fIto\fR?)" 8 | |
868 | .IX Item "$hlist->selectionClear(?from?, ?to?)" | |
869 | When no extra arguments are given, deselects all of the list entrie(s) | |
870 | in this HList widget. When only \fIfrom\fR is given, only the list | |
871 | entry identified by \fIfrom\fR is deselected. When both \fIfrom\fR and | |
872 | \&\fIto\fR are given, deselects all of the list entrie(s) between | |
873 | between \fIfrom\fR and \fIto\fR, inclusive, without affecting the | |
874 | selection state of elements outside that range. | |
875 | .IP "\fI$hlist\fR\->\fBselectionGet\fR" 8 | |
876 | .IX Item "$hlist->selectionGet" | |
877 | This is an alias for the \fBinfoSelection\fR method. | |
878 | .IP "\fI$hlist\fR\->\fBselectionIncludes\fR(\fI$entryPath\fR)" 8 | |
879 | .IX Item "$hlist->selectionIncludes($entryPath)" | |
880 | Returns 1 if the list entry indicated by \fI$entryPath\fR is currently | |
881 | selected; returns 0 otherwise. | |
882 | .IP "\fI$hlist\fR\->\fBselectionSet\fR(\fIfrom\fR?, \fIto\fR?)" 8 | |
883 | .IX Item "$hlist->selectionSet(from?, to?)" | |
884 | Selects all of the list entrie(s) between between \fIfrom\fR and | |
885 | \&\fIto\fR, inclusive, without affecting the selection state of entries | |
886 | outside that range. When only \fIfrom\fR is given, only the list entry | |
887 | identified by \fIfrom\fR is selected. | |
888 | .RE | |
889 | .RS 4 | |
890 | .RE | |
891 | .IP "\fI$hlist\fR\->\fBshow\fR(\fIoption\fR ?,\fI$entryPath\fR?)" 4 | |
892 | .IX Item "$hlist->show(option ?,$entryPath?)" | |
893 | Show the entries that are hidden by the \fBhide\fR method, | |
894 | \&\fIoption\fR can be one of the following: | |
895 | .RS 4 | |
896 | .IP "\fBentry\fR" 8 | |
897 | .IX Item "entry" | |
898 | Shows the list entry identified by \fI$entryPath\fR. | |
899 | .RE | |
900 | .RS 4 | |
901 | .Sp | |
902 | Currently only the \fBentry\fR option is supported. Other options will | |
903 | be added in future releases. | |
904 | .RE | |
905 | .IP "\fI$hlist\fR\->\fBxview\fR(\fIargs\fR)" 4 | |
906 | .IX Item "$hlist->xview(args)" | |
907 | This method is used to query and change the horizontal position of the | |
908 | information in the widget's window. It can take any of the following | |
909 | forms: | |
910 | .RS 4 | |
911 | .IP "\fI$hlist\fR\->\fBxview\fR" 8 | |
912 | .IX Item "$hlist->xview" | |
913 | Returns a list containing two elements. Each element is a real | |
914 | fraction between 0 and 1; together they describe the horizontal span | |
915 | that is visible in the window. For example, if the first element is | |
916 | \&.2 and the second element is .6, 20% of the HList entry is | |
917 | off-screen to the left, the middle 40% is visible in the window, and | |
918 | 40% of the entry is off-screen to the right. These are the same values | |
919 | passed to scrollbars via the \fB\-xscrollcommand\fR option. | |
920 | .IP "\fI$hlist\fR\->\fBxview\fR(\fI$entryPath\fR)" 8 | |
921 | .IX Item "$hlist->xview($entryPath)" | |
922 | Adjusts the view in the window so that the list entry identified by | |
923 | \&\fI$entryPath\fR is aligned to the left edge of the window. | |
924 | .IP "\fI$hlist\fR\->\fBxview\fR(\fBmoveto\fR => \fIfraction\fR)" 8 | |
925 | .IX Item "$hlist->xview(moveto => fraction)" | |
926 | Adjusts the view in the window so that \fIfraction\fR of the total | |
927 | width of the HList is off-screen to the left. \fIfraction\fR must be | |
928 | a fraction between 0 and 1. | |
929 | .IP "\fI$hlist\fR\->\fBxview\fR(\fBscroll\fR => \fInumber, what\fR)" 8 | |
930 | .IX Item "$hlist->xview(scroll => number, what)" | |
931 | This method shifts the view in the window left or right according to | |
932 | \&\fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer. | |
933 | \&\fIWhat\fR must be either \fBunits\fR or \fBpages\fR or an | |
934 | abbreviation of one of these. If \fIwhat\fR is \fBunits\fR, the view | |
935 | adjusts left or right by \fInumber\fR character units (the width of | |
936 | the \fB0\fR character) on the display; if it is \fBpages\fR then the | |
937 | view adjusts by \fInumber\fR screenfuls. If \fInumber\fR is negative | |
938 | then characters farther to the left become visible; if it is positive | |
939 | then characters farther to the right become visible. | |
940 | .RE | |
941 | .RS 4 | |
942 | .RE | |
943 | .IP "\fI$hlist\fR\->\fByview\fR(\fI?args\fR?)" 4 | |
944 | .IX Item "$hlist->yview(?args?)" | |
945 | This method is used to query and change the vertical position of the | |
946 | entries in the widget's window. It can take any of the following forms: | |
947 | .RS 4 | |
948 | .IP "\fI$hlist\fR\->\fByview\fR" 8 | |
949 | .IX Item "$hlist->yview" | |
950 | Returns a list containing two elements, both of which are real | |
951 | fractions between 0 and 1. The first element gives the position of | |
952 | the list element at the top of the window, relative to the HList as a | |
953 | whole (0.5 means it is halfway through the HList, for example). The | |
954 | second element gives the position of the list entry just after the | |
955 | last one in the window, relative to the HList as a whole. These are | |
956 | the same values passed to scrollbars via the \fB\-yscrollcommand\fR | |
957 | option. | |
958 | .IP "\fI$hlist\fR\->\fByview\fR(\fI$entryPath\fR)" 8 | |
959 | .IX Item "$hlist->yview($entryPath)" | |
960 | Adjusts the view in the window so that the list entry given by | |
961 | \&\fI$entryPath\fR is displayed at the top of the window. | |
962 | .IP "\fI$hlist\fR\->\fByview\fR(\fBmoveto\fR => \fIfraction\fR)" 8 | |
963 | .IX Item "$hlist->yview(moveto => fraction)" | |
964 | Adjusts the view in the window so that the list entry given by | |
965 | \&\fIfraction\fR appears at the top of the window. \fIFraction\fR is a | |
966 | fraction between 0 and 1; 0 indicates the first entry in the | |
967 | HList, 0.33 indicates the entry one-third the way through the | |
968 | HList, and so on. | |
969 | .IP "\fI$hlist\fR\->\fByview\fR(\fBscroll\fR => \fInumber, what\fR)" 8 | |
970 | .IX Item "$hlist->yview(scroll => number, what)" | |
971 | This method adjust the view in the window up or down according to | |
972 | \&\fInumber\fR and \fIwhat\fR. \fINumber\fR must be an integer. | |
973 | \&\fIWhat\fR must be either \fBunits\fR or \fBpages\fR. If \fIwhat\fR | |
974 | is \fBunits\fR, the view adjusts up or down by \fInumber\fR lines; if | |
975 | it is \fBpages\fR then the view adjusts by \fInumber\fR screenfuls. | |
976 | If \fInumber\fR is negative then earlier entries become visible; if | |
977 | it is positive then later entries become visible. | |
978 | .RE | |
979 | .RS 4 | |
980 | .RE | |
981 | .SH "BINDINGS" | |
982 | .IX Header "BINDINGS" | |
983 | .IP "[1]" 4 | |
984 | .IX Item "[1]" | |
985 | If the \fB\-selectmode\fR is \*(L"browse\*(R", when the user drags the mouse | |
986 | pointer over the list entries, the entry under the pointer will be | |
987 | highlighted and the \fB\-browsecmd\fR callback will be called with | |
988 | one parameter, the entryPath of the highlighted entry. Only one entry | |
989 | can be highlighted at a time. The \fB\-command\fR callback will be | |
990 | called when the user double-clicks on a list entry. | |
991 | .IP "[2]" 4 | |
992 | .IX Item "[2]" | |
993 | If the \fB\-selectmode\fR is \*(L"single\*(R", the entries will only be | |
994 | highlighted by mouse <ButtonRelease\-1> events. When a new list entry | |
995 | is highlighted, the \fB\-browsecmd\fR callback will be called with | |
996 | one parameter indicating the highlighted list entry. The | |
997 | \&\fB\-command\fR callback will be called when the user double-clicks | |
998 | on a list entry. | |
999 | .IP "[3]" 4 | |
1000 | .IX Item "[3]" | |
1001 | If the \fB\-selectmode\fR is \*(L"multiple\*(R", when the user drags the mouse | |
1002 | pointer over the list entries, all the entries under the pointer will | |
1003 | be highlighted. However, only a contiguous region of list entries can | |
1004 | be selected. When the highlighted area is changed, the | |
1005 | \&\fB\-browsecmd\fR callback will be called with an undefined | |
1006 | parameter. It is the responsibility of the \fB\-browsecmd\fR callback | |
1007 | to find out the exact highlighted selection in the HList. The | |
1008 | \&\fB\-command\fR callback will be called when the user double-clicks | |
1009 | on a list entry. | |
1010 | .IP "[4]" 4 | |
1011 | .IX Item "[4]" | |
1012 | If the \fB\-selectmode\fR is \*(L"extended\*(R", when the user drags the mouse | |
1013 | pointer over the list entries, all the entries under the pointer will | |
1014 | be highlighted. The user can also make disjointed selections using | |
1015 | <Control\-ButtonPress\-1>. When the highlighted area is changed, the | |
1016 | \&\fB\-browsecmd\fR callback will be called with an undefined | |
1017 | parameter. It is the responsibility of the \fB\-browsecmd\fR callback | |
1018 | to find out the exact highlighted selection in the HList. The | |
1019 | \&\fB\-command\fR callback will be called when the user double-clicks | |
1020 | on a list entry. | |
1021 | .IP "[5]" 4 | |
1022 | .IX Item "[5]" | |
1023 | \&\fBArrow key bindings:\fR <Up> arrow key moves the anchor point to the | |
1024 | item right on top of the current anchor item. <Down> arrow key moves | |
1025 | the anchor point to the item right below the current anchor item. | |
1026 | <Left> arrow key moves the anchor to the parent item of the current | |
1027 | anchor item. <Right> moves the anchor to the first child of the | |
1028 | current anchor item. If the current anchor item does not have any | |
1029 | children, moves the anchor to the item right below the current anchor | |
1030 | item. | |
1031 | .SH "EXAMPLE" | |
1032 | .IX Header "EXAMPLE" | |
1033 | This example demonstrates how to use an HList to store a file | |
1034 | directory structure and respond to the user's browse events: | |
1035 | .PP | |
1036 | .Vb 4 | |
1037 | \& use strict; | |
1038 | \& use Tk; | |
1039 | \& use Tk::Label; | |
1040 | \& use Tk::HList; | |
1041 | .Ve | |
1042 | .PP | |
1043 | .Vb 11 | |
1044 | \& my $mw = MainWindow->new(); | |
1045 | \& my $label = $mw->Label(-width=>15); | |
1046 | \& my $hlist = $mw->HList( | |
1047 | \& -itemtype => 'text', | |
1048 | \& -separator => '/', | |
1049 | \& -selectmode => 'single', | |
1050 | \& -browsecmd => sub { | |
1051 | \& my $file = shift; | |
1052 | \& $label->configure(-text=>$file); | |
1053 | \& } | |
1054 | \& ); | |
1055 | .Ve | |
1056 | .PP | |
1057 | .Vb 3 | |
1058 | \& foreach ( qw(/ /home /home/ioi /home/foo /usr /usr/lib) ) { | |
1059 | \& $hlist->add($_, -text=>$_); | |
1060 | \& } | |
1061 | .Ve | |
1062 | .PP | |
1063 | .Vb 2 | |
1064 | \& $hlist->pack; | |
1065 | \& $label->pack; | |
1066 | .Ve | |
1067 | .PP | |
1068 | .Vb 1 | |
1069 | \& MainLoop; | |
1070 | .Ve | |
1071 | .SH "BUGS" | |
1072 | .IX Header "BUGS" | |
1073 | The fact that the display item at column 0 is implicitly associated | |
1074 | with the whole entry is probably a design bug. This was done for | |
1075 | backward compatibility purposes. The result is that there is a large | |
1076 | overlap between the \fBitem\fR method and the \fBadd\fR, | |
1077 | \&\fBaddchild\fR, \fBentrycget\fR and \fBentryconfigure\fR | |
1078 | methods. Whenever multiple columns exist, the programmer should use | |
1079 | \&\s-1ONLY\s0 the \fBitem\fR method to create and configure the display items | |
1080 | in each column; the \fBadd\fR, \fBaddchild\fR, \fBentrycget\fR and | |
1081 | \&\fBentryconfigure\fR should be used \s-1ONLY\s0 to create and configure | |
1082 | entries. | |
1083 | .SH "KEYWORDS" | |
1084 | .IX Header "KEYWORDS" | |
1085 | Hierarchical Listbox | |
1086 | .SH "SEE ALSO" | |
1087 | .IX Header "SEE ALSO" | |
1088 | Tk::DItem |