| 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 |