blib/lib/Tk/HListbox.pm untested

filter: Statementstmt 0.0% 0 / 1300 Branchbran 0.0% 0 / 722 Conditioncond 0.0% 0 / 380 MC/DCmcdc 0.0% 0 / 233 Subroutinesub 0.0% 0 / 99 Podpod 0.0% 0 / 90 totaltotal 0.0% 0 / 2824 CC 359 SCAR 48.9
CC
359
Cov
0%
insert
600.0
_getwidth
342.0
foreground
306.0
CRAP 133.6
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__