| 1 | =head1 NAME | ||
| 2 | |||
| 3 | Tk::HListbox - Tk Listbox widget supporting images and text entries, Tk::HList-based drop-in replacement for Tk::Listbox. | ||
| 4 | |||
| 5 | =for category Tk Widget Classes | ||
| 6 | |||
| 7 | =head1 SYNOPSIS | ||
| 8 | |||
| 9 | I<$listbox> = I<$parent>-E<gt>B<HListbox>(?I<options>?); | ||
| 10 | |||
| 11 | =head1 DESCRIPTION | ||
| 12 | |||
| 13 | The B<HListbox> method creates a new window (given by the | ||
| 14 | $widget argument) and makes it into an HListbox widget. | ||
| 15 | Additional options, described above, may be specified on | ||
| 16 | the command line or in the option database | ||
| 17 | to configure aspects of the listbox such as its colors, font, | ||
| 18 | text, and relief. The B<HListbox> command returns its | ||
| 19 | $widget argument. At the time this command is invoked, | ||
| 20 | there must not exist a window named $widget, but | ||
| 21 | $widget's parent must exist. | ||
| 22 | |||
| 23 | An HListbox is a widget that displays a list of strings, images, or both | ||
| 24 | one per line. When first created, a new HListbox has no elements. | ||
| 25 | Elements may be added or deleted using methods described | ||
| 26 | below. In addition, one or more elements may be selected as described | ||
| 27 | below. If an HListbox is exporting its selection (see B<exportSelection> | ||
| 28 | option), then it will observe the standard X11 protocols | ||
| 29 | for handling the selection. | ||
| 30 | HListbox selections are available as type B<STRING>; | ||
| 31 | the value of the selection will be the "text" of the selected elements, | ||
| 32 | returned as an array of zero or more elements. | ||
| 33 | |||
| 34 | It is not necessary for all the elements to be | ||
| 35 | displayed in the HListbox window at once; commands described below | ||
| 36 | may be used to change the view in the window. HListboxes allow | ||
| 37 | scrolling in both directions using the standard B<xScrollCommand> | ||
| 38 | and B<yScrollCommand> options. They also support scanning, as described below. | ||
| 39 | |||
| 40 | =head1 STANDARD OPTIONS | ||
| 41 | |||
| 42 | B<-background> B<-borderwidth> B<-cursor> B<-disabledforeground> | ||
| 43 | B<-exportselection> B<-font> B<-foreground> B<-height> | ||
| 44 | B<-highlightbackground> B<-highlightcolor> B<-highlightthickness> | ||
| 45 | B<-offset> B<-relief> B<-selectbackground> B<-selectborderwidth> | ||
| 46 | B<-selectforeground> B<-setgrid> B<-state> B<-takefocus> | ||
| 47 | B<-width> B<-xscrollcommand> B<-yscrollcommand> | ||
| 48 | |||
| 49 | See L<Tk::options> for details of the standard options. | ||
| 50 | |||
| 51 | =head1 WIDGET-SPECIFIC OPTIONS | ||
| 52 | |||
| 53 | =over | ||
| 54 | |||
| 55 | =item Name: B<Entries> | ||
| 56 | |||
| 57 | Entries (rows) are added to HListbox vertically as rows, one per row (line) | ||
| 58 | using either the B<insert> method or inserting into a tied array. | ||
| 59 | Entries can be either a text string (just like a standard L<Tk::Listbox> | ||
| 60 | entry), an image (a L<Tk::Photo> object), or a hashref containing options | ||
| 61 | specifying both, along with any other desired L<Tk::HList>-valid I<options> | ||
| 62 | (see below). | ||
| 63 | Example: $listbox->insert('end', {-image => $image, -text => 'string'}); | ||
| 64 | Options for the referenced hash include: | ||
| 65 | |||
| 66 | =over | ||
| 67 | |||
| 68 | =item B<-hidden> => 1 | 0 | ||
| 69 | |||
| 70 | Specifies whether or not the entry should be visible or hidden: (0 (false) | ||
| 71 | for visible, 1 (true) for hidden). | ||
| 72 | |||
| 73 | Default: B<0> (visible). | ||
| 74 | |||
| 75 | =item B<-indicatoritemtype> => ['text' | 'image' | 'imagetext'] | ||
| 76 | |||
| 77 | Specify an "indicator" of this type. | ||
| 78 | |||
| 79 | =item B<-indicatorimage => $image | ||
| 80 | |||
| 81 | Special image to be displayed next to entry (in addition to any other image | ||
| 82 | specified in the entry). | ||
| 83 | |||
| 84 | =item B<-indicatortext => 'text' | ||
| 85 | |||
| 86 | Special text to be displayed next to entry (in addition to any other image | ||
| 87 | specified in the entry). | ||
| 88 | |||
| 89 | =item B<-itemtype> => ['text' | 'image' | 'imagetext'] | ||
| 90 | |||
| 91 | Specifies the type of display item of this entry. Can be | ||
| 92 | I<"text">, I<"image">, or I<"imagetext">. | ||
| 93 | |||
| 94 | Default: Whatever is specified, if anything, for the widget, (see B<-itemtype> | ||
| 95 | under B<WIDGET OPTIONS> below). If not specified there, then the default is | ||
| 96 | I<"text">, though I<"imagetext"> allows for either or both an image or text. | ||
| 97 | |||
| 98 | =item B<-textanchor> => ['n', 's', 'e', 'w'] | ||
| 99 | |||
| 100 | Side of text the IMAGE is displayed on. | ||
| 101 | |||
| 102 | Default: I<'w'> (West / left, ie. image before text) | ||
| 103 | |||
| 104 | =item B<-style> => $ImageStyleObject | ||
| 105 | |||
| 106 | Use an already-defined HList B<ItemStyle> object | ||
| 107 | (see Tk::ItemStyle and Tk::DItem) | ||
| 108 | |||
| 109 | =item B<-sort> => 'value', B<-user> => 'value' | ||
| 110 | |||
| 111 | Specifies user-specific data to be kept stored with the entry but not | ||
| 112 | displayed. Such data would most likely be a string, but could be a reference | ||
| 113 | to pretty much anything. Tk::HMListbox makes use of the B<-sort> field for | ||
| 114 | user-control of column sorting, refer to it's documentation for examples. | ||
| 115 | |||
| 116 | =item B<-text> $string | ||
| 117 | |||
| 118 | Specifies a "text" entry. $string represents the text to be displayed in | ||
| 119 | the entry. | ||
| 120 | |||
| 121 | These options are not passed to functions, but retained with data, useful for | ||
| 122 | saving info with an entry for one's own use. | ||
| 123 | |||
| 124 | For example, one could put text in a I<-sort> option of say, an image-only | ||
| 125 | entry and then retrieve it in a sort function | ||
| 126 | like "sort { $a->{-sort} cmp $b->{-sort} }". | ||
| 127 | |||
| 128 | Any other option, other than these or the standard applicable widget options, | ||
| 129 | such as B<-background>, etc. are treated as "Style" options and sent to the | ||
| 130 | default B<ItemStyle> for the data type. NOTE: Under the current | ||
| 131 | implementation any "Style" options supplied with an entry will be applied to | ||
| 132 | ALL entries of that "type" (ie. "image", "imagetext", or "text") in | ||
| 133 | the listbox. To force a specific entry to have a different "style", define | ||
| 134 | an B<ItemStyle> object and use the B<-style> option. | ||
| 135 | |||
| 136 | =back | ||
| 137 | |||
| 138 | =item Name: B<activeForeground> | ||
| 139 | |||
| 140 | =item Class: B<activeForeground> | ||
| 141 | |||
| 142 | =item Switch: B<-activeforeground> | ||
| 143 | |||
| 144 | Specifies an alternate color for the foreground of the "active" entry (the one | ||
| 145 | the text cursor is on). This entry is also shown with a hashed box around it. | ||
| 146 | The "activebackground" color, however, is always fixed as the same color as the | ||
| 147 | the widget's background. | ||
| 148 | |||
| 149 | Default: Same color as the widget's foreground color. | ||
| 150 | |||
| 151 | =item Name: B<browsecmd> | ||
| 152 | |||
| 153 | =item Class: B<BrowseCmd> | ||
| 154 | |||
| 155 | =item Switch: B<-browsecmd> | ||
| 156 | |||
| 157 | Specifies a perl/Tk L<callback|Tk::callbacks> to be executed when the user | ||
| 158 | browses through the entries in the HList widget. | ||
| 159 | |||
| 160 | =item Name: B<command> | ||
| 161 | |||
| 162 | =item Class: B<Command> | ||
| 163 | |||
| 164 | =item Switch: B<-command> | ||
| 165 | |||
| 166 | Specifies the perl/Tk L<callback|Tk::callbacks> to be executed when the user | ||
| 167 | invokes a list entry in the HList widget. Normally the user invokes a list | ||
| 168 | entry by double-clicking it or pressing the Return key. | ||
| 169 | |||
| 170 | =item Switch: B<-gap> value | ||
| 171 | |||
| 172 | The amount of space between the image and text in rows that have both. | ||
| 173 | |||
| 174 | Default: B<4> (pixels) | ||
| 175 | |||
| 176 | =item Name: B<height> | ||
| 177 | |||
| 178 | =item Class: B<Height> | ||
| 179 | |||
| 180 | =item Switch: B<-height> | ||
| 181 | |||
| 182 | Specifies the desired height for the window, in number of characters. | ||
| 183 | If zero or less, then the desired height for the window is based on the | ||
| 184 | default for HList, which seems to be about 7 lines. WARNING: This is NOT | ||
| 185 | accurate, ie. specifying a -height of 8 will typically display about 6-6 1/2 | ||
| 186 | rows of text in the default font. Sorry, but this is a bug in the underlying | ||
| 187 | Tk::HList widget. | ||
| 188 | |||
| 189 | =item Name: B<indicator> | ||
| 190 | |||
| 191 | =item Class: B<Indicator> | ||
| 192 | |||
| 193 | =item Switch B<-indicator> | ||
| 194 | |||
| 195 | Reserves space for and allows for another image next to the entry, which | ||
| 196 | HList calls an "indicator", which, unlike a normal "image" in an entry, | ||
| 197 | can be attached to a callback routine (-indicatorcmd) to be invoked when | ||
| 198 | the indicator image is clicked with the mouse, rather than the entry | ||
| 199 | simply being selected. By default (if no I<-textanchor> option given, | ||
| 200 | the indicator image will appear to the left of the entry. | ||
| 201 | |||
| 202 | =item Name: B<indicatorCmd> | ||
| 203 | |||
| 204 | =item Class: B<IndicatorCmd> | ||
| 205 | |||
| 206 | =item Switch B<-indicatorcmd> | ||
| 207 | |||
| 208 | Subroutine reference to be invoked when an indicator image is clicked. | ||
| 209 | |||
| 210 | =item Name: B<-ipadx> | ||
| 211 | |||
| 212 | Specify horizontal padding style in pixels around the image | ||
| 213 | for the rows in the listbox which are type I<image> or I<imagetext>. | ||
| 214 | |||
| 215 | Default: B<0> (no padding added) | ||
| 216 | |||
| 217 | =item Name: B<-ipady> | ||
| 218 | |||
| 219 | Specify vertical padding style in pixels around the image | ||
| 220 | for the rows in the listbox which are type I<image> or I<imagetext>. | ||
| 221 | NOTE: This changes the height of the affected rows. | ||
| 222 | |||
| 223 | Default: B<1> (pixels added to both top and bottom, and setting to B<0> | ||
| 224 | is the same as B<1>). | ||
| 225 | |||
| 226 | =item Name: B<itemType> | ||
| 227 | |||
| 228 | =item Class: B<ItemType> | ||
| 229 | |||
| 230 | =item Switch: B<-itemtype> | ||
| 231 | |||
| 232 | Specifies the default type of display item. Can be "text", "image", or | ||
| 233 | "imagetext". | ||
| 234 | |||
| 235 | Default: B<"text">, though I<"imagetext"> allows for either or both an image | ||
| 236 | or text. | ||
| 237 | |||
| 238 | =item Name: B<listVariable> | ||
| 239 | |||
| 240 | =item Class: B<Variable> | ||
| 241 | |||
| 242 | =item Switch: B<-listvariable> | ||
| 243 | |||
| 244 | Specifies the reference of a variable. The value of the variable is an array | ||
| 245 | to be displayed inside the widget; if the variable value changes then the | ||
| 246 | widget will automatically update itself to reflect the new value. Attempts | ||
| 247 | to unset a variable in use as a -listvariable may fail without error. | ||
| 248 | |||
| 249 | The listvariable reference is "TIEd" to the HListbox widget just as if one | ||
| 250 | has done: "tie @listvariable, 'Tk::HListbox', $HListboxwidget, | ||
| 251 | (ReturnType => 'index);" immediately after defining $HListboxwidget using the | ||
| 252 | "tie @array" feature. | ||
| 253 | |||
| 254 | =item Name: B<selectBackground> | ||
| 255 | |||
| 256 | =item Class: B<SelectBackground> | ||
| 257 | |||
| 258 | =item Switch: B<-selectbackground> | ||
| 259 | |||
| 260 | Specifies an alternate background color for item(s) currently "selected". | ||
| 261 | |||
| 262 | Default: A slightly brighter shade of the widget's current background color. | ||
| 263 | |||
| 264 | =item Name: B<selectForeground> | ||
| 265 | |||
| 266 | =item Class: B<SelectForeground> | ||
| 267 | |||
| 268 | =item Switch: B<-selectforeground> | ||
| 269 | |||
| 270 | Specifies an alternate foreground color for item(s) currently "selected". | ||
| 271 | |||
| 272 | Default: The widget's current foreground color. | ||
| 273 | |||
| 274 | =item Name: B<selectMode> | ||
| 275 | |||
| 276 | =item Class: B<SelectMode> | ||
| 277 | |||
| 278 | =item Switch: B<-selectmode> | ||
| 279 | |||
| 280 | Specifies one of several styles for manipulating the selection. | ||
| 281 | The value of the option may be arbitrary, but the default bindings | ||
| 282 | expect it to be either B<single>, B<browse>, B<multiple>, | ||
| 283 | B<extended> or B<dragdrop>; the default value is B<browse>. | ||
| 284 | |||
| 285 | =item Name: B<-showcursoralways> | ||
| 286 | |||
| 287 | =item Class: B<-showcursoralways> | ||
| 288 | |||
| 289 | =item Switch: B<-showcursoralways> | ||
| 290 | |||
| 291 | Starting with version 2.4, Tk::HListbox no longer displays the keyboard | ||
| 292 | cursor (active element) when the HListbox widget does not have the | ||
| 293 | keyboard focus, in order to be consistent with the behaviour of | ||
| 294 | Tk::Listbox. This option, when set to 1 (or a "true" value) restores | ||
| 295 | the pre-v2.4 behaviour of always showing the keyboard cursor. | ||
| 296 | Default I<0> (False). | ||
| 297 | |||
| 298 | =item Name: B<state> | ||
| 299 | |||
| 300 | =item Class: B<State> | ||
| 301 | |||
| 302 | =item Switch: B<-state> | ||
| 303 | |||
| 304 | Specifies one of two states for the listbox: B<normal> or B<disabled>. | ||
| 305 | If the listbox is disabled then items may not be inserted or deleted, items | ||
| 306 | are drawn in the B<-disabledforeground> color, and selection cannot be | ||
| 307 | modified and is not shown (though selection information is retained). | ||
| 308 | |||
| 309 | =item Name: B<takeFocus> | ||
| 310 | |||
| 311 | =item Class: B<TakeFocus> | ||
| 312 | |||
| 313 | =item Switch: B<-takefocus> | ||
| 314 | |||
| 315 | There are actually three different focusing options: Specify B<1> to both | ||
| 316 | allow the widget to take keyboard focus itself and to enable grabbing the | ||
| 317 | keyboard focus when a user clicks on a row in the listbox. Specify B<''> | ||
| 318 | to allow the widget to take focus (via the <TAB> circulate order) but do | ||
| 319 | not grab the focus when a user clicks on (selects) a row. This is the | ||
| 320 | default focusing model. Specify B<0> to not allow the widget to receive | ||
| 321 | the keyboard focus. | ||
| 322 | |||
| 323 | =item Name: B<-tpadx> => I<number> | ||
| 324 | |||
| 325 | Specify horizontal padding style in pixels around the text for the rows in | ||
| 326 | the listbox which are type I<text>. | ||
| 327 | |||
| 328 | Default: B<2> (pixels - added to both left and right side) | ||
| 329 | |||
| 330 | =item Name: B<-tpady> => I<number> | ||
| 331 | |||
| 332 | Specify vertical padding style in pixels around the text for the rows in the | ||
| 333 | listbox which are type I<text>. NOTE: This changes the height of the | ||
| 334 | affected rows. | ||
| 335 | |||
| 336 | Default (seems to be): B<2> (and setting to B<0> is the same as B<2>). | ||
| 337 | |||
| 338 | =item Name: B<width> | ||
| 339 | |||
| 340 | =item Class: B<Width> | ||
| 341 | |||
| 342 | =item Switch: B<-width> | ||
| 343 | |||
| 344 | Specifies the desired width for the window in characters. If the font | ||
| 345 | doesn't have a uniform width then the width of the character "0" is used in | ||
| 346 | translating from character units to screen units. If zero or less, then the | ||
| 347 | desired width for the window is made just large enough to hold all the | ||
| 348 | elements in the listbox. | ||
| 349 | |||
| 350 | =back | ||
| 351 | |||
| 352 | =head1 LISTBOX OPTIONS AND METHODS NOT (YET?) SUPPORTED BY HLISTBOX | ||
| 353 | |||
| 354 | =over | ||
| 355 | |||
| 356 | =item Name: B<activeStyle> | ||
| 357 | |||
| 358 | =item Class: B<ActiveStyle> | ||
| 359 | |||
| 360 | =item Switch: B<-activestyle> | ||
| 361 | |||
| 362 | Ignored (not implemented in HList). | ||
| 363 | |||
| 364 | For the most part, Tk::HListbox can be used as drop-in replacement | ||
| 365 | for the Tk::Listbox widget when you need to use images instead of or | ||
| 366 | in addition to text values, or need other Tk::HListbox - specific | ||
| 367 | features such as hidden or disabled entries, callbacks, etc. | ||
| 368 | |||
| 369 | =back | ||
| 370 | |||
| 371 | =head1 INDICES | ||
| 372 | |||
| 373 | Many of the methods for HListboxes take one or more indices as arguments. | ||
| 374 | An index specifies a particular element of the listbox, in any of | ||
| 375 | the following ways: | ||
| 376 | |||
| 377 | =over | ||
| 378 | |||
| 379 | =item I<number> | ||
| 380 | |||
| 381 | Specifies the element as a numerical index, where 0 corresponds to the first | ||
| 382 | element in the listbox. | ||
| 383 | |||
| 384 | =item B<active> | ||
| 385 | |||
| 386 | Indicates the element that has the location cursor. This element will be | ||
| 387 | displayed with a dashed-line frame border when the listbox has the keyboard | ||
| 388 | focus, and it is specified with the B<activate> method. | ||
| 389 | |||
| 390 | =item B<anchor> | ||
| 391 | |||
| 392 | Indicates the anchor point for the selection, which is set with the | ||
| 393 | B<selection anchor> method. | ||
| 394 | |||
| 395 | =item B<end> | ||
| 396 | |||
| 397 | Indicates the end (last element) of the HListbox. | ||
| 398 | For most commands this refers to the last element in the HListbox, | ||
| 399 | but for a few commands such as B<index> and B<insert> | ||
| 400 | it refers to the element just after the last one. | ||
| 401 | |||
| 402 | =item B<@>I<x>B<,>I<y> | ||
| 403 | |||
| 404 | Indicates the element that covers the point in the HListbox window | ||
| 405 | specified by I<x> and I<y> (in pixel coordinates). If no | ||
| 406 | element covers that point, then the closest element to that | ||
| 407 | point is used. | ||
| 408 | |||
| 409 | =back | ||
| 410 | |||
| 411 | In the method descriptions below, arguments named I<index>, I<first-index>, | ||
| 412 | and I<last-index> always contain text indices in one of the above forms. | ||
| 413 | |||
| 414 | =head1 WIDGET METHODS | ||
| 415 | |||
| 416 | The B<HListbox> method creates a widget object. This object supports the | ||
| 417 | B<configure> and B<cget> methods described in L<Tk::options> which can be used | ||
| 418 | to enquire and modify the options described above. The widget also inherits | ||
| 419 | all the methods provided by the generic L<Tk::Widget|Tk::Widget> class. | ||
| 420 | |||
| 421 | The following additional methods are available for HListbox widgets: | ||
| 422 | |||
| 423 | =over | ||
| 424 | |||
| 425 | =item I<$listbox>-E<gt>B<activate>(I<index>) | ||
| 426 | |||
| 427 | Sets the active element and the selection anchor to the one indicated | ||
| 428 | by I<index>. If I<index> is outside the range of elements in the listbox then | ||
| 429 | the closest element is activated. The active element is drawn similar to a | ||
| 430 | "selected" element with a thin hashed border (similar to an underlined element | ||
| 431 | in I<Tk::Listbox>, and its index may be retrieved with the index B<"active">. | ||
| 432 | |||
| 433 | NOTE: Not supported by I<Tk::HList>. | ||
| 434 | |||
| 435 | =item I<$listbox>-E<gt>B<add>(I<$entryPath ?,option> => I<value, ...?index>) | ||
| 436 | |||
| 437 | Creates a new list entry with the pathname $entryPath. A list entry must be | ||
| 438 | created after its parent is created (unless this entry is a top-level entry, | ||
| 439 | which has no parent). See also "BUGS" below. This method returns the entryPath | ||
| 440 | of the newly created list entry. The following configuration options can be | ||
| 441 | given to configure the list entry: | ||
| 442 | |||
| 443 | =over | ||
| 444 | |||
| 445 | =item B<-at> => I<position> | ||
| 446 | |||
| 447 | Insert the new list at the position given by position. position must be a | ||
| 448 | valid integer. The position 0 indicates the first position, 1 indicates | ||
| 449 | the second position, and so on. | ||
| 450 | |||
| 451 | =item B<-after> => I<afterWhich> | ||
| 452 | |||
| 453 | Insert the new list entry after the entry identified by I<afterWhich>, | ||
| 454 | which must be a valid list entry and it mush have the same parent as the | ||
| 455 | new list entry. | ||
| 456 | |||
| 457 | =item B<-before> => I<beforeWhich> | ||
| 458 | |||
| 459 | Insert the new list entry before the entry identified by I<beforeWhich>, | ||
| 460 | which must be a valid list entry and it mush have the same parent as the | ||
| 461 | new list entry. | ||
| 462 | |||
| 463 | =item B<-data> => I<string> | ||
| 464 | |||
| 465 | Specifies a string to associate with this list entry. This string can be | ||
| 466 | queried by the info method. The application programmer can use the I<-data> | ||
| 467 | option to associate the list entry with the data it represents. | ||
| 468 | |||
| 469 | =item B<-itemtype> => I<type> | ||
| 470 | |||
| 471 | Specifies the type of display item to be display for the new list entry. | ||
| 472 | I<type> must be a valid display item type. Currently the available | ||
| 473 | display item types are imagetext, text, and $widget. If this option is | ||
| 474 | not specified, then by default the type specified by this HList widget's | ||
| 475 | I<-itemtype> option is used. | ||
| 476 | |||
| 477 | =item B<-state> => I<state> | ||
| 478 | |||
| 479 | Specifies whether this entry can be selected or invoked by the user. | ||
| 480 | Must be either normal or disabled. | ||
| 481 | |||
| 482 | =back | ||
| 483 | |||
| 484 | The I<add()> method accepts additional configuration options to configure the | ||
| 485 | display item associated with this list entry. The set of additional | ||
| 486 | configuration options depends on the type of the display item given by the | ||
| 487 | I<-itemtype> option. Please see L<Tk::DItem> for a list of the configuration | ||
| 488 | options for each of the display item types. This method is associated with | ||
| 489 | L<Tk::HList> and will accept strings as I<entryPath>s. Unlike HList, | ||
| 490 | entrypaths containing dots are not added as "children" because Tk::HListbox | ||
| 491 | does not support "tree" lists (multi-level lists). | ||
| 492 | |||
| 493 | =item I<$listbox>-E<gt>B<bbox>(I<index>) | ||
| 494 | |||
| 495 | Returns a list of four numbers describing the bounding box of the text in the | ||
| 496 | element given by I<index>. The first two elements of the list give the x and | ||
| 497 | y coordinates of the upper-left corner of the screen area covered by the text | ||
| 498 | (specified in pixels relative to the widget) and the last two elements give | ||
| 499 | the width and height of the area, in pixels. If no part of the element given | ||
| 500 | by I<index> is visible on the screen, or if I<index> refers to a non-existent | ||
| 501 | element, then the result is an empty string; if the element is partially | ||
| 502 | visible, the result gives the full area of the element, including any parts | ||
| 503 | that are not visible. | ||
| 504 | |||
| 505 | =item I<$listbox>-E<gt>B<curselection> | ||
| 506 | |||
| 507 | Returns a list containing the numerical indices of all of the elements in the | ||
| 508 | HListbox that are currently selected. If there are no elements selected in | ||
| 509 | the listbox then an empty list is returned. This method is the complement | ||
| 510 | (opposite) of I<selectionSet()> in functionality. | ||
| 511 | |||
| 512 | NOTE: Not supported by I<Tk::HList>. | ||
| 513 | |||
| 514 | =item I<$listbox>-E<gt>B<delete>(I<first-index, >?I<last-index>?) | ||
| 515 | |||
| 516 | Deletes one or more elements of the HListbox. I<First-index> and I<last-index> | ||
| 517 | are indices specifying the first and last elements in the range to delete. | ||
| 518 | If I<last-index> isn't specified it defaults to I<first-index>, | ||
| 519 | i.e. a single element is deleted. | ||
| 520 | |||
| 521 | =item I<$listbox>-E<gt>B<findIndex>(I<string>?) | ||
| 522 | |||
| 523 | Given the text of an entry, return the index of the first | ||
| 524 | entry whose text matches the string, or I<<undef>> if no matches. | ||
| 525 | |||
| 526 | NOTE: Not supported by I<Tk::Listbox>. | ||
| 527 | |||
| 528 | =item I<$listbox>-E<gt>B<fixListSize>(I<width>, I<height>) | ||
| 529 | |||
| 530 | Will fix the height and width of the B<HListbox>, caused by the underlying | ||
| 531 | B<HList>, when non-default fonts are used. | ||
| 532 | |||
| 533 | The B<I<width>> and B<I<height>> values are the required character width and | ||
| 534 | the number of rows in the listbox. | ||
| 535 | |||
| 536 | NOTE: Not supported by I<Tk::HList> or I<Tk::Listbox>. | ||
| 537 | |||
| 538 | =item I<$listbox>-E<gt>B<fixPalette>() | ||
| 539 | |||
| 540 | Under certain situations, changing the color theme via | ||
| 541 | $mainwin->setPalette(...) does not always update do to the myriad of | ||
| 542 | subwidgets and color options supported. Calling this method should fully | ||
| 543 | update everything in the widget that have not been individually set by | ||
| 544 | the user. | ||
| 545 | |||
| 546 | =item I<$listbox>-E<gt>B<get>(I<first-index, >?I<last-index>?) | ||
| 547 | |||
| 548 | If I<last-index> is omitted, returns the contents of the listbox element | ||
| 549 | indicated by I<first-index>, or an empty string if I<first-index> refers to a | ||
| 550 | non-existent element. If I<last-index> is specified, the command returns a | ||
| 551 | list whose elements are all of the listbox elements between I<first-index> | ||
| 552 | and I<last-index>, inclusive. Both I<first-index> and I<last-index> may have | ||
| 553 | any of the standard forms for indices. | ||
| 554 | |||
| 555 | =item I<$listbox>-E<gt>B<getEntry>(I<index>?) | ||
| 556 | |||
| 557 | Given an index, returns the HList "entry" value, only useful with | ||
| 558 | lower-level HList functions. Returns I<<undef>> if no matches. | ||
| 559 | This method is the complement (opposite) of I<indexOf()> in functionality. | ||
| 560 | |||
| 561 | NOTE: Not supported by I<Tk::HList> or I<Tk::Listbox>. | ||
| 562 | |||
| 563 | =item I<$listbox>-E<gt>B<getListHeight>(I<height>) | ||
| 564 | |||
| 565 | Will return the correct height in pixels, of the B<HListbox>, | ||
| 566 | when a non-default B<-listfont> is used. | ||
| 567 | |||
| 568 | B<I<height>> is the required number of rows for the listbox. | ||
| 569 | |||
| 570 | NOTE: Not supported by I<Tk::HList> or I<Tk::Listbox>. | ||
| 571 | |||
| 572 | =item I<$listbox>-E<gt>B<getListWidth>(I<width>) | ||
| 573 | |||
| 574 | Will return the correct width, in pixels, of the B<HListbox>, | ||
| 575 | when a non-default B<-listfont> is used. | ||
| 576 | |||
| 577 | B<I<width>> is the required width in characters for the listbox. | ||
| 578 | |||
| 579 | NOTE: Not supported by I<Tk::HList> or I<Tk::Listbox>. | ||
| 580 | |||
| 581 | =item I<$listbox>-E<gt>B<hide>([I<-entry> => ] I<index>) | ||
| 582 | |||
| 583 | Given an index, sets the entry to "hidden" so that it does not | ||
| 584 | display in the listbox (but maintains it's index. The "-entry" | ||
| 585 | argument is unnecessary, but retained for Tk::HList compatability. | ||
| 586 | |||
| 587 | NOTE: Not supported by I<Tk::Listbox>. | ||
| 588 | |||
| 589 | =item I<$listbox>-E<gt>B<show>([I<-entry> => ] I<index>) | ||
| 590 | |||
| 591 | Given an index, sets the entry to "not hidden" (the default) so | ||
| 592 | that it is displayed in the listbox. | ||
| 593 | |||
| 594 | NOTE: Not supported by I<Tk::Listbox>. | ||
| 595 | |||
| 596 | =item I<$listbox>-E<gt>B<index>(I<index>) | ||
| 597 | |||
| 598 | Returns the integer index value that corresponds to I<index>. | ||
| 599 | If I<index> is B<end> the return value is a count of the number | ||
| 600 | of elements in the listbox (not the index of the last element). | ||
| 601 | If the index is out of range or invalid, I<undef> is returned. | ||
| 602 | If the index is I<"end"> and the list is empty, I<-1> is returned. | ||
| 603 | |||
| 604 | =item I<$listbox>-E<gt>B<indexOf>(I<entry-path>) | ||
| 605 | |||
| 606 | Returns the integer index value that corresponds to I<entry-path>, | ||
| 607 | or I<undef> if the I<entry-path> does not exist. This method is | ||
| 608 | the complement (opposite) of I<getEntry()> in functionality. | ||
| 609 | |||
| 610 | NOTE: Not supported by I<Tk::HList> or I<Tk::Listbox>. | ||
| 611 | |||
| 612 | =item I<$listbox>-E<gt>B<insert>(I<index, >?I<element, element, ...>?) | ||
| 613 | |||
| 614 | Inserts zero or more new elements (entries) in the list just before the | ||
| 615 | element given by I<index>. If I<index> is specified as B<"end"> then the new | ||
| 616 | elements are added to the end of the list. Returns an empty string. If the | ||
| 617 | I<index> is not "end", the list will be automatically inserted in reverse | ||
| 618 | order so that the entire list is inserted in the proper order before the | ||
| 619 | element currently identified by the I<index>. | ||
| 620 | |||
| 621 | =item I<$listbox>-E<gt>B<item>(I<option, index, >?I<arg(s), ...>?) | ||
| 622 | |||
| 623 | Creates and configures the display items at individual columns the entries. | ||
| 624 | The form of additional of arguments depends on the choice of option: | ||
| 625 | |||
| 626 | NOTE: Not supported by I<Tk::Listbox>. | ||
| 627 | |||
| 628 | =over | ||
| 629 | |||
| 630 | =item I<$listbox>-E<gt>B<itemcget>(I<index>, I<option>) | ||
| 631 | |||
| 632 | Returns the current value of the item configuration option given by | ||
| 633 | I<option>. Option may have any of the values accepted by the listbox | ||
| 634 | B<itemconfigure> command or by HList, including ItemStyles. | ||
| 635 | |||
| 636 | =item I<$listbox>-E<gt>B<itemconfigure>(I<index, >?I<option, value, | ||
| 637 | option, value, ...>?) | ||
| 638 | |||
| 639 | Query or modify the configuration options of an item in the HListbox. | ||
| 640 | If no option is specified, returns a list describing all of the | ||
| 641 | available options for the item (see Tk_ConfigureInfo for information | ||
| 642 | on the format of this list). If option is specified with no value, | ||
| 643 | then the command returns a list describing the one named option (this | ||
| 644 | list will be identical to the corresponding sublist of the value | ||
| 645 | returned if no option is specified). If one or more option-value pairs | ||
| 646 | are specified, then the command modifies the given widget option(s) to | ||
| 647 | have the given value(s); in this case the command returns an empty | ||
| 648 | string. The following options are currently supported for items: | ||
| 649 | |||
| 650 | =item I<$listbox>-E<gt>B<ItemStyle>(I<itemtype, >?I<option, value, ...>?) | ||
| 651 | |||
| 652 | HList method to create a display style for the I<-style> entry option. | ||
| 653 | NOTE: It's better to change most display properties by listing them | ||
| 654 | and their values when inserting entries since any HListbox-wide style | ||
| 655 | options specified when creating the HListbox widget, ie. I<-foreground>, | ||
| 656 | etc. are NOT copied over into the style object. | ||
| 657 | |||
| 658 | =over | ||
| 659 | |||
| 660 | =item B<-background> =E<gt> I<color> | ||
| 661 | |||
| 662 | I<Color> specifies the background color to use when displaying the item. | ||
| 663 | It may have any of the forms accepted by Tk_GetColor. | ||
| 664 | |||
| 665 | =item B<-foreground> =E<gt> I<color> | ||
| 666 | |||
| 667 | I<Color> specifies the foreground color to use when displaying the | ||
| 668 | item. It may have any of the forms accepted by Tk_GetColor. NOTE: | ||
| 669 | may be returned as "-fg". | ||
| 670 | |||
| 671 | =item B<-selectbackground> =E<gt> I<color> | ||
| 672 | |||
| 673 | I<Color> specifies the background color to use when displaying the item while | ||
| 674 | it is selected. It may have any of the forms accepted by Tk_GetColor. | ||
| 675 | |||
| 676 | =item B<-selectforeground> =E<gt> I<color> | ||
| 677 | |||
| 678 | I<Color> specifies the foreground color to use when displaying the item while | ||
| 679 | it is selected. It may have any of the forms accepted by Tk_GetColor. | ||
| 680 | |||
| 681 | =back | ||
| 682 | |||
| 683 | =back | ||
| 684 | |||
| 685 | =item I<$listbox>-E<gt>B<nearest>(I<y>) | ||
| 686 | |||
| 687 | Given a y-coordinate within the listbox window, this command returns | ||
| 688 | the index of the (visible) listbox element nearest to that y-coordinate. | ||
| 689 | |||
| 690 | NOTE: Not supported by I<Tk::Listbox>. | ||
| 691 | |||
| 692 | =item $listbox-E<gt>nearestToIndex(I<index>) | ||
| 693 | |||
| 694 | Given a zero based B<I<index>> within the listbox window, this command returns | ||
| 695 | the index of the (visible) listbox element nearest to the B<I<index>>. | ||
| 696 | |||
| 697 | If there is no visible bounding box associated with the | ||
| 698 | zero-based B<I<index>>, then I<undef> is returned. | ||
| 699 | |||
| 700 | NOTE: Not supported by I<Tk::HList> or I<Tk::Listbox>. | ||
| 701 | |||
| 702 | =item I<$listbox>-E<gt>B<scan>(I<option, >?I<arg(s), ...>?) | ||
| 703 | |||
| 704 | This command is used to implement scanning on listboxes. It has two forms, | ||
| 705 | depending on I<option>: | ||
| 706 | |||
| 707 | NOTE: Not supported by I<Tk::HList>. | ||
| 708 | |||
| 709 | =over | ||
| 710 | |||
| 711 | =item I<$listbox>-E<gt>B<scanMark>(I<x, y>) | ||
| 712 | |||
| 713 | Records I<x> and I<y> and the current view in the listbox | ||
| 714 | window; used in conjunction with later B<scan dragto> commands. | ||
| 715 | Typically this command is associated with a mouse button press in | ||
| 716 | the widget. It returns an empty string. | ||
| 717 | |||
| 718 | =item I<$listbox>-E<gt>B<scanDragto>(I<x, y>) | ||
| 719 | |||
| 720 | This command computes the difference between its I<x> and I<y> arguments and | ||
| 721 | the I<x> and I<y> arguments to the last B<scan mark> command for the widget. | ||
| 722 | It then adjusts the view by 10 times the difference in coordinates. | ||
| 723 | This command is typically associated with mouse motion events in the widget, | ||
| 724 | to produce the effect of dragging the list at high speed through the window. | ||
| 725 | The return value is an empty string. | ||
| 726 | |||
| 727 | =back | ||
| 728 | |||
| 729 | =item I<$listbox>-E<gt>B<see>(I<index>) | ||
| 730 | |||
| 731 | Adjust the view in the HListbox so that the element given by I<index> | ||
| 732 | is visible. If the element is already visible then the command has no effect; | ||
| 733 | if the element is near one edge of the window then the listbox scrolls to | ||
| 734 | bring the element into view at the edge; otherwise the listbox scrolls to | ||
| 735 | center the element. | ||
| 736 | |||
| 737 | =item I<$listbox>-E<gt>B<selection>(I<option, >?I<arg(s), ...>?) | ||
| 738 | |||
| 739 | This command is used to adjust the selection within a listbox. It has several | ||
| 740 | forms, depending on I<option>: | ||
| 741 | |||
| 742 | =over | ||
| 743 | |||
| 744 | =item I<$listbox>-E<gt>B<selectionAnchor>(I<index>) | ||
| 745 | |||
| 746 | Sets the selection anchor to the element given by I<index>. | ||
| 747 | If I<index> refers to a non-existent element, then the closest | ||
| 748 | element is used. The selection anchor is the end of the selection that is | ||
| 749 | fixed while dragging out a selection with the mouse. The index B<anchor> | ||
| 750 | may be used to refer to the anchor element. | ||
| 751 | |||
| 752 | =item I<$listbox>-E<gt>B<selectionClear>(I<first-index, >?I<last-index>?) | ||
| 753 | |||
| 754 | If any of the elements between I<first-index> and I<last-index> | ||
| 755 | (inclusive) are selected, they are deselected. The selection state is not | ||
| 756 | changed for elements outside this range. | ||
| 757 | |||
| 758 | =item I<$listbox>-E<gt>B<selectionGet> | ||
| 759 | |||
| 760 | NOTE: Not recommended, nor supported by I<Tk::Listbox>. | ||
| 761 | |||
| 762 | Returns a list containing the actual I<elements> of all of the elements in | ||
| 763 | the HListbox that are currently selected. If there are no elements selected | ||
| 764 | in the listbox then an empty list is returned. NOTE: The opposite method | ||
| 765 | of this (I<selectionSet()>) is called with I<indices>. Reason is that | ||
| 766 | I<selectionGet> is not supported by L<Tk::Listbox>, but is a direct call to | ||
| 767 | the corresponding method in L<Tk::HList>. | ||
| 768 | |||
| 769 | The recommended method for fetching back the indicies selected | ||
| 770 | (either by the user or by I<selectionSet()>) is to call the | ||
| 771 | I<curselection()> method provided both here and in I<Tk::Listbox>. | ||
| 772 | |||
| 773 | =item I<$listbox>-E<gt>B<selectionIncludes>(I<index>) | ||
| 774 | |||
| 775 | Returns 1 (true) if the element indicated by I<index> is currently selected, | ||
| 776 | 0 (false) if it isn't. | ||
| 777 | |||
| 778 | The recommended method for fetching back the indicies selected | ||
| 779 | (either by the user or by I<selectionSet()>) is to call the | ||
| 780 | I<curselection()> method provided both here and in I<Tk::Listbox>. | ||
| 781 | |||
| 782 | =item I<$listbox>-E<gt>B<selectionSet>(I<first-index, >?I<last-index>?) | ||
| 783 | |||
| 784 | Selects all of the elements in the range between | ||
| 785 | I<first-index> and I<last-index>, inclusive, without affecting | ||
| 786 | the selection state of elements outside that range. This is the complement | ||
| 787 | (opposite) of I<curselection()> in functionality. | ||
| 788 | |||
| 789 | NOTE: Prior to v2.7, if more than two indices were passed | ||
| 790 | to I<selectionSet()>, then the element of each index in the list | ||
| 791 | would be selected. Starting with v2.7, the list is limited to | ||
| 792 | one or two indices (as is the case with both I<Tk::Listbox> and | ||
| 793 | I<Tk::HList>). Two indices represents a range, causing all elements | ||
| 794 | with indices between the two specified (inclusive) being selected. | ||
| 795 | |||
| 796 | =back | ||
| 797 | |||
| 798 | =item I<$listbox>-E<gt>B<size> | ||
| 799 | |||
| 800 | Returns a decimal string indicating the total number of elements in | ||
| 801 | the listbox. | ||
| 802 | |||
| 803 | =item I<$listbox>-E<gt>B<xview>(I<option, >?I<arg(s), ...>?) | ||
| 804 | |||
| 805 | This command is used to query and change the horizontal position of the | ||
| 806 | information in the widget's window. It can take any of the | ||
| 807 | following forms: | ||
| 808 | |||
| 809 | =over | ||
| 810 | |||
| 811 | =item I<$listbox>-E<gt>B<xview> | ||
| 812 | |||
| 813 | Returns a list containing two elements. Each element is a real fraction | ||
| 814 | between 0 and 1; together they describe the horizontal span that is visible | ||
| 815 | in the window. For example, if the first element is .2 and the second element | ||
| 816 | is .6, 20% of the listbox's text is off-screen to the left, the middle 40% is | ||
| 817 | visible in the window, and 40% of the text is off-screen to the right. These | ||
| 818 | are the same values passed to scrollbars via the B<-xscrollcommand> option. | ||
| 819 | |||
| 820 | =item I<$listbox>-E<gt>B<xview>(I<index>) | ||
| 821 | |||
| 822 | Adjusts the view in the window so that the character position given by | ||
| 823 | I<index> is displayed at the left edge of the window. | ||
| 824 | Character positions are defined by the width of the character B<0>. | ||
| 825 | |||
| 826 | =item I<$listbox>-E<gt>B<xviewMoveto>(I<fraction>); | ||
| 827 | |||
| 828 | Adjusts the view in the window so that I<fraction> of the | ||
| 829 | total width of the listbox text is off-screen to the left. | ||
| 830 | I<fraction> must be a fraction between 0 and 1. | ||
| 831 | |||
| 832 | =item I<$listbox>-E<gt>B<xviewScroll>(I<number, what>); | ||
| 833 | |||
| 834 | This command shifts the view in the window left or right according to | ||
| 835 | I<number> and I<what>. I<Number> must be an integer. I<What> must be either | ||
| 836 | B<units> or B<pages> or an abbreviation of one of these. If I<what> is | ||
| 837 | B<units>, the view adjusts left or right by I<number> character units | ||
| 838 | (the width of the B<0> character) on the display; if it is B<pages> then the | ||
| 839 | view adjusts by I<number> screenfuls. If I<number> is negative then | ||
| 840 | characters farther to the left become visible; if it is positive then | ||
| 841 | characters farther to the right become visible. | ||
| 842 | |||
| 843 | =back | ||
| 844 | |||
| 845 | =item I<$listbox>-E<gt>B<yview>(I<option, >?I<arg(s), ...>?) | ||
| 846 | |||
| 847 | This command is used to query and change the vertical position of the | ||
| 848 | text in the widget's window. It can take any of the following forms: | ||
| 849 | |||
| 850 | =over | ||
| 851 | |||
| 852 | =item I<$listbox>-E<gt>B<yview> | ||
| 853 | |||
| 854 | Returns a list containing two elements, both of which are real fractions | ||
| 855 | between 0 and 1. The first element gives the position of the listbox element | ||
| 856 | at the top of the window, relative to the listbox as a whole (0.5 means it is | ||
| 857 | halfway through the listbox, for example). The second element gives the | ||
| 858 | position of the listbox element just after the last one in the window, | ||
| 859 | relative to the listbox as a whole. These are the same values passed to | ||
| 860 | scrollbars via the B<-yscrollcommand> option. | ||
| 861 | |||
| 862 | =item I<$listbox>-E<gt>B<yview>(I<index>) | ||
| 863 | |||
| 864 | Adjusts the view in the window so that the element given by | ||
| 865 | I<index> is displayed at the top of the window. | ||
| 866 | |||
| 867 | =item I<$listbox>-E<gt>B<yviewMoveto>(I<fraction>); | ||
| 868 | |||
| 869 | Adjusts the view in the window so that the element given by I<fraction> | ||
| 870 | appears at the top of the window. I<Fraction> is a fraction between 0 and 1; | ||
| 871 | 0 indicates the first element in the listbox, 0.33 indicates the element | ||
| 872 | one-third the way through the listbox, and so on. | ||
| 873 | |||
| 874 | =item I<$listbox>-E<gt>B<yviewScroll>(I<number, what>); | ||
| 875 | |||
| 876 | This command adjusts the view in the window up or down according to I<number> | ||
| 877 | and I<what>. I<Number> must be an integer. I<What> must be either B<units> | ||
| 878 | or B<pages>. If I<what> is B<units>, the view adjusts up or down by I<number> | ||
| 879 | lines; if it is B<pages> then the view adjusts by I<number> screenfuls. | ||
| 880 | If I<number> is negative then earlier elements become visible; if it is | ||
| 881 | positive then later elements become visible. | ||
| 882 | |||
| 883 | =back | ||
| 884 | |||
| 885 | =back | ||
| 886 | |||
| 887 | =head1 EXAMPLES | ||
| 888 | |||
| 889 | #!/usr/bin/perl | ||
| 890 | |||
| 891 | use Tk; | ||
| 892 | use Tk::HListbox; | ||
| 893 | |||
| 894 | my ( @array, $scalar, $other ); | ||
| 895 | my %options = ( ReturnType => "index" ); | ||
| 896 | |||
| 897 | my $MW = MainWindow->new(); | ||
| 898 | my $licon=$MW->Photo(-file => '/usr/share/pixmaps/smallicons/Penguin.xpm'); #ICON IMAGE | ||
| 899 | my $wicon=$MW->Photo(-file => '/usr/share/pixmaps/smallicons/tiny_windowsxp.xpm'); #ICON IMAGE | ||
| 900 | my $lbox = $MW->Scrolled('HListbox', | ||
| 901 | -scrollbars => 'se', | ||
| 902 | -selectmode => 'extended', | ||
| 903 | -itemtype => 'imagetext', | ||
| 904 | -indicator => 1, | ||
| 905 | -indicatorcmd => sub { | ||
| 906 | print STDERR "---indicator clicked---(".join('|',@_).")\n"; | ||
| 907 | }, | ||
| 908 | -browsecmd => sub { | ||
| 909 | print STDERR "---browsecmd!---(".join('|',@_).")\n"; | ||
| 910 | }, | ||
| 911 | )->pack(-fill => 'y', -expand => 1); | ||
| 912 | |||
| 913 | $MW->Button( #MAIN WINDOW BUTTON TO QUIT. | ||
| 914 | -text => 'Bonus Tests', | ||
| 915 | -underline => 0, | ||
| 916 | -command => sub | ||
| 917 | { | ||
| 918 | #FETCH AND PRINT OUT THE SELECTED ITEMS: | ||
| 919 | my @v = $lbox->curselection; | ||
| 920 | print "--SELECTED=".join('|', @v)."= vcnt=$#v= MODE=".$lbox->cget('-selectmode')."=\n"; | ||
| 921 | for (my $i=0;$i<=$#v;$i++) | ||
| 922 | { | ||
| 923 | print "--selected($i)=".$lbox->get($v[$i])."=\n"; | ||
| 924 | } | ||
| 925 | #PRINT WHETHER THE LAST ITEM IS CURRENTLY SELECTED (2 WAYS): | ||
| 926 | print "--select includes last one =".$lbox->selectionIncludes('end')."=\n"; | ||
| 927 | print "--select includes last one =".$lbox->selection('includes','end')."=\n"; | ||
| 928 | #FETCH THE OLD ANCHOR AND SET THE ANCHOR TO THE 2ND ITEM: | ||
| 929 | my $anchorWas = $lbox->index('anchor'); | ||
| 930 | $lbox->selectionAnchor(8); | ||
| 931 | my $anchorNow = $lbox->index('anchor'); | ||
| 932 | #DELETE THE 4TH ITEM & ****TURN OFF INDICATORS!**** TO SHOW NORMAL VIEW: | ||
| 933 | $lbox->delete(4); | ||
| 934 | $lbox->configure(-indicator => 0); | ||
| 935 | #SET THE VIEWPORT TO SHOW THE FIRST SELECTED ITEM: | ||
| 936 | $lbox->yview($v[0]); | ||
| 937 | #PRINT THE DATA RETURNED BY yview() AND THE LAST ITEM; | ||
| 938 | my @yview = $lbox->yview; | ||
| 939 | my $last = $lbox->index('end'); | ||
| 940 | print "--YVIEW=".join('|',@yview)."= last=$last=\n"; | ||
| 941 | #FETCH THE INDEX OF THE LAST ITEM: | ||
| 942 | #FETCH AND DISPLAY SOME ATTRIBUTES: | ||
| 943 | print "--anchor was=$anchorWas= now=$anchorNow= yview=".join('|',@yview)."=\n"; | ||
| 944 | print "-reqheight=".$lbox->reqheight."= height=".$lbox->cget('-height')."= size=".$lbox->size."=\n"; | ||
| 945 | #PRINT OUT THE VALUES OF THE TIED VARIABLES: | ||
| 946 | print "-scalar=".join('|',@{$scalar})."= array=".join('|',@array)."= other=".join('|',@{$other})."=\n"; | ||
| 947 | #RECONFIGURE 2ND ITEM TO FOREGROUND:=GREEN: | ||
| 948 | $lbox->itemconfigure(1,'-fg', 'green'); | ||
| 949 | #FETCH THE HList STYLE OBJECT FOR 2ND ITEM: | ||
| 950 | print "-itemcget(1)=".$lbox->itemcget(1, '-style')."=\n"; | ||
| 951 | #FETCH JUST THE Listbox FOREGROUND COLOR FOR 2ND ITEM: | ||
| 952 | print "-itemcget(2)=".$lbox->itemcget(1, '-fg')."=\n"; | ||
| 953 | #FETCH THE "NEAREST" INDEX TO THE 2ND ITEM: | ||
| 954 | print "-nearest(1)=".$lbox->nearest(1)."=\n"; | ||
| 955 | #ADD AN ELEMENT VIA THE TIED ARRAY: | ||
| 956 | push @array, {-image => $licon, -text => 'ArrayAdd!'}; | ||
| 957 | #DELETE THE LAST ITEM USING THE TIED ARRAY: | ||
| 958 | pop @array; | ||
| 959 | #FIND AND DISPLAY THE INDEX OF THE TEXT ENTRY "Y": | ||
| 960 | print "-Index of 'Y' =".$lbox->findIndex('Y')."=\n"; | ||
| 961 | } | ||
| 962 | )->pack( | ||
| 963 | -side => 'bottom' | ||
| 964 | ); | ||
| 965 | $MW->Button( #MAIN WINDOW BUTTON TO QUIT. | ||
| 966 | -text => 'Quit', | ||
| 967 | -underline => 0, | ||
| 968 | -command => sub { print "ok 5\n..done: 5 tests completed.\n"; exit(0) } | ||
| 969 | )->pack( | ||
| 970 | -side => 'bottom' | ||
| 971 | ); | ||
| 972 | |||
| 973 | #ADD SOME ITEMS (IMAGE+TEXT) TO OUR LISTBOX THE TRADITIONAL WAY: | ||
| 974 | my @list = ( | ||
| 975 | {-image => $licon, -text => 'a' }, | ||
| 976 | {-image => $wicon, -text => 'bbbbbbbbbbbbbbbbbbbB', -foreground => '#0000FF' }, | ||
| 977 | {-text => 'c', -image => $licon }, | ||
| 978 | {-text => 'd:image & indicator!', -image => $licon, -indicatoritemtype, 'image', -indicatorimage => $wicon }, | ||
| 979 | {-image => $licon, -text => 'e' }, | ||
| 980 | {-image => $licon, -text => 'f:Switch sides!', -textanchor => 'w' }, | ||
| 981 | {-image => $licon, -text => 'z:Next is Image Only!' }, | ||
| 982 | $licon | ||
| 983 | ); | ||
| 984 | $lbox->insert('end', @list ); | ||
| 985 | @list = (); | ||
| 986 | #ADD A BUNCH MORE JUST BEFORE THE 7TH ITEM (" | ||
| 987 | foreach my $i ('G'..'Y') | ||
| 988 | { | ||
| 989 | push @list, {-image => $licon, -text => $i}; | ||
| 990 | } | ||
| 991 | $lbox->insert(6, @list ); | ||
| 992 | |||
| 993 | #FETCH THE 2ND ITEM AND DISPLAY IT'S TEXT: | ||
| 994 | $_ = $lbox->get(1); | ||
| 995 | if (ref $_) { | ||
| 996 | print "-2nd value=$_= TEXT=".$_->{'-text'}."=\n"; | ||
| 997 | } else { | ||
| 998 | print "-2nd value=$_=\n"; | ||
| 999 | } | ||
| 1000 | #SET THE 3RD AND 5TH ITEMS AS INITIALLY-SELECTED: | ||
| 1001 | $lbox->selectionSet(2,4); | ||
| 1002 | #AND ONE WITH AN "INDICATOR IMAGE" JUST BEFORE THE 4TH ITEM: | ||
| 1003 | $lbox->insert(3, 'TextOnly at 3', | ||
| 1004 | {'-text' => '<Click Indicator Icon', '-indicatoritemtype', 'image', '-indicatorimage' => $wicon}); | ||
| 1005 | #DISPLAY A LIST OF ALL THE CURRENT ITEMS IN THE LISTBOX: | ||
| 1006 | print "--current choices=".join('|',$lbox->get(0, 'end'))."=\n"; | ||
| 1007 | |||
| 1008 | #TIE SOME VARIABLES TO THE LISTBOX: | ||
| 1009 | tie @array, "Tk::HListbox", $lbox; | ||
| 1010 | tie $scalar, "Tk::HListbox", $lbox; | ||
| 1011 | tie $other, "Tk::HListbox", $lbox, %options; | ||
| 1012 | |||
| 1013 | MainLoop; | ||
| 1014 | |||
| 1015 | __END__ |