1Listbox(3) User Contributed Perl Documentation Listbox(3)
2
6 Tk::Listbox - Create and manipulate Listbox widgets
7
9 $listbox = $parent->Listbox(?options?);
10
12 -background -borderwidth -cursor -disabledforeground -exportselection
13 -font -foreground -height -highlightbackground -highlightcolor -high‐
14 lightthickness -offset -relief -selectbackground -selectborderwidth
15 -selectforeground -setgrid -state -takefocus -tile -width -xscrollcom‐
16 mand -yscrollcommand
17 See Tk::options for details of the standard options.
19
21 Name: activeStyle
22 Class: ActiveStyle
23 Switch: -activestyle
24 Specifies the style in which to draw the active element. This must
25 be one of dotbox (show a focus ring around the active element),
26 none (no special indication of active element) or underline (under‐
27 line the active element). The default is underline.
28 Name: height
30 Class: Height
31 Switch: -height
32 Specifies the desired height for the window, in lines. If zero or
33 less, then the desired height for the window is made just large
34 enough to hold all the elements in the listbox.
35 Name: listVariable
37 Class: Variable
38 Switch: -listvariable
39 The following is only partially implemented in Perl/Tk:
40 Specifies the reference of a variable. The value of the variable is
42 an array to be displayed inside the widget; if the variable value
43 changes then the widget will automatically update itself to reflect
44 the new value. Attempts to assign a variable with an invalid list
45 value to -listvariable will cause an error. Attempts to unset a
46 variable in use as a -listvariable will fail but will not generate
47 an error.
48 Name: selectMode
50 Class: SelectMode
51 Switch: -selectmode
52 Specifies one of several styles for manipulating the selection.
53 The value of the option may be arbitrary, but the default bindings
54 expect it to be either single, browse, multiple, or extended; the
55 default value is browse.
56 Name: state
58 Class: State
59 Switch: -state
60 Specifies one of two states for the listbox: normal or disabled.
61 If the listbox is disabled then items may not be inserted or
62 deleted, items are drawn in the -disabledforeground color, and
63 selection cannot be modified and is not shown (though selection
64 information is retained).
65 Name: width
67 Class: Width
68 Switch: -width
69 Specifies the desired width for the window in characters. If the
70 font doesn't have a uniform width then the width of the character
71 ``0'' is used in translating from character units to screen units.
72 If zero or less, then the desired width for the window is made just
73 large enough to hold all the elements in the listbox.
74
76 The Listbox method creates a new window (given by the $widget argument)
77 and makes it into a listbox widget. Additional options, described
78 above, may be specified on the command line or in the option database
79 to configure aspects of the listbox such as its colors, font, text, and
80 relief. The listbox command returns its $widget argument. At the time
81 this command is invoked, there must not exist a window named $widget,
82 but $widget's parent must exist.
83 A listbox is a widget that displays a list of strings, one per line.
85 When first created, a new listbox has no elements. Elements may be
86 added or deleted using methods described below. In addition, one or
87 more elements may be selected as described below. If a listbox is
88 exporting its selection (see exportSelection option), then it will
89 observe the standard X11 protocols for handling the selection. Listbox
90 selections are available as type STRING; the value of the selection
91 will be the text of the selected elements, with newlines separating the
92 elements.
93 It is not necessary for all the elements to be displayed in the listbox
95 window at once; commands described below may be used to change the
96 view in the window. Listboxes allow scrolling in both directions using
97 the standard xScrollCommand and yScrollCommand options. They also sup‐
98 port scanning, as described below.
99
101 Many of the methods for listboxes take one or more indices as argu‐
102 ments. An index specifies a particular element of the listbox, in any
103 of the following ways:
104 number
106 Specifies the element as a numerical index, where 0 corresponds to
107 the first element in the listbox.
108 active
110 Indicates the element that has the location cursor. This element
111 will be displayed with an underline when the listbox has the key‐
112 board focus, and it is specified with the activate method.
113 anchor
115 Indicates the anchor point for the selection, which is set with the
116 selection anchor method.
117 end Indicates the end of the listbox. For most commands this refers to
119 the last element in the listbox, but for a few commands such as
120 index and insert it refers to the element just after the last one.
121 @x,y
123 Indicates the element that covers the point in the listbox window
124 specified by x and y (in pixel coordinates). If no element covers
125 that point, then the closest element to that point is used.
126 In the method descriptions below, arguments named index, first, and
128 last always contain text indices in one of the above forms.
129
131 The Listbox method creates a widget object. This object supports the
132 configure and cget methods described in Tk::options which can be used
133 to enquire and modify the options described above. The widget also
134 inherits all the methods provided by the generic Tk::Widget class.
135 The following additional methods are available for listbox widgets:
137 $listbox->activate(index)
139 Sets the active element to the one indicated by index. If index is
140 outside the range of elements in the listbox then the closest ele‐
141 ment is activated. The active element is drawn with an underline
142 when the widget has the input focus, and its index may be retrieved
143 with the index active.
144 $listbox->bbox(index)
146 Returns a list of four numbers describing the bounding box of the
147 text in the element given by index. The first two elements of the
148 list give the x and y coordinates of the upper-left corner of the
149 screen area covered by the text (specified in pixels relative to
150 the widget) and the last two elements give the width and height of
151 the area, in pixels. If no part of the element given by index is
152 visible on the screen, or if index refers to a non-existent ele‐
153 ment, then the result is an empty string; if the element is par‐
154 tially visible, the result gives the full area of the element,
155 including any parts that are not visible.
156 $listbox->curselection
158 Returns a list containing the numerical indices of all of the ele‐
159 ments in the listbox that are currently selected. If there are no
160 elements selected in the listbox then an empty string is returned.
161 $listbox->delete(first, ?last?)
163 Deletes one or more elements of the listbox. First and last are
164 indices specifying the first and last elements in the range to
165 delete. If last isn't specified it defaults to first, i.e. a sin‐
166 gle element is deleted.
167 $listbox->get(first, ?last?)
169 If last is omitted, returns the contents of the listbox element
170 indicated by first, or an empty string if first refers to a non-
171 existent element. If last is specified, the command returns a list
172 whose elements are all of the listbox elements between first and
173 last, inclusive. Both first and last may have any of the standard
174 forms for indices.
175 $listbox->index(index)
177 Returns the integer index value that corresponds to index. If
178 index is end the return value is a count of the number of elements
179 in the listbox (not the index of the last element).
180 $listbox->insert(index, ?element, element, ...?)
182 Inserts zero or more new elements in the list just before the ele‐
183 ment given by index. If index is specified as end then the new
184 elements are added to the end of the list. Returns an empty
185 string.
186 $listbox->itemcget(index, option)
188 Returns the current value of the item configuration option given by
189 option. Option may have any of the values accepted by the listbox
190 itemconfigure command.
191 $listbox->itemconfigure(index, ?option, value, option, value, ...?)
193 Query or modify the configuration options of an item in the list‐
194 box. If no option is specified, returns a list describing all of
195 the available options for the item (see Tk_ConfigureInfo for infor‐
196 mation on the format of this list). If option is specified with no
197 value, then the command returns a list describing the one named
198 option (this list will be identical to the corresponding sublist of
199 the value returned if no option is specified). If one or more
200 option-value pairs are specified, then the command modifies the
201 given widget option(s) to have the given value(s); in this case the
202 command returns an empty string. The following options are cur‐
203 rently supported for items:
204 -background => color
206 Color specifies the background color to use when displaying the
207 item. It may have any of the forms accepted by Tk_GetColor.
208 -foreground => color
210 Color specifies the foreground color to use when displaying the
211 item. It may have any of the forms accepted by Tk_GetColor.
212 -selectbackground => color
214 Color specifies the background color to use when displaying the
215 item while it is selected. It may have any of the forms
216 accepted by Tk_GetColor.
217 -selectforeground => color
219 Color specifies the foreground color to use when displaying the
220 item while it is selected. It may have any of the forms
221 accepted by Tk_GetColor.
222 $listbox->nearest(y)
224 Given a y-coordinate within the listbox window, this command
225 returns the index of the (visible) listbox element nearest to that
226 y-coordinate.
227 $listbox->scan(option, args)
229 This command is used to implement scanning on listboxes. It has
230 two forms, depending on option:
231 $listbox->scanMark(x, y)
233 Records x and y and the current view in the listbox window;
234 used in conjunction with later scan dragto commands. Typi‐
235 cally this command is associated with a mouse button press
236 in the widget. It returns an empty string.
237 $listbox->scanDragto(x, y.)
239 This command computes the difference between its x and y
240 arguments and the x and y arguments to the last scan mark
241 command for the widget. It then adjusts the view by 10
242 times the difference in coordinates. This command is typi‐
243 cally associated with mouse motion events in the widget, to
244 produce the effect of dragging the list at high speed
245 through the window. The return value is an empty string.
246 $listbox->see(index)
248 Adjust the view in the listbox so that the element given by index
249 is visible. If the element is already visible then the command has
250 no effect; if the element is near one edge of the window then the
251 listbox scrolls to bring the element into view at the edge; other‐
252 wise the listbox scrolls to center the element.
253 $listbox->selection(option, arg)
255 This command is used to adjust the selection within a listbox. It
256 has several forms, depending on option:
257 $listbox->selectionAnchor(index)
259 Sets the selection anchor to the element given by index.
260 If index refers to a non-existent element, then the closest
261 element is used. The selection anchor is the end of the
262 selection that is fixed while dragging out a selection with
263 the mouse. The index anchor may be used to refer to the
264 anchor element.
265 $listbox->selectionClear(first, ?last?)
267 If any of the elements between first and last (inclusive)
268 are selected, they are deselected. The selection state is
269 not changed for elements outside this range.
270 $listbox->selectionIncludes(index)
272 Returns 1 if the element indicated by index is currently
273 selected, 0 if it isn't.
274 $listbox->selectionSet(first, ?last?)
276 Selects all of the elements in the range between first and
277 last, inclusive, without affecting the selection state of
278 elements outside that range.
279 $listbox->size
281 Returns a decimal string indicating the total number of elements in
282 the listbox.
283 $listbox->xview(args)
285 This command is used to query and change the horizontal position of
286 the information in the widget's window. It can take any of the
287 following forms:
288 $listbox->xview
290 Returns a list containing two elements. Each element is a
291 real fraction between 0 and 1; together they describe the
292 horizontal span that is visible in the window. For exam‐
293 ple, if the first element is .2 and the second element is
294 .6, 20% of the listbox's text is off-screen to the left,
295 the middle 40% is visible in the window, and 40% of the
296 text is off-screen to the right. These are the same values
297 passed to scrollbars via the -xscrollcommand option.
298 $listbox->xview(index)
300 Adjusts the view in the window so that the character posi‐
301 tion given by index is displayed at the left edge of the
302 window. Character positions are defined by the width of
303 the character 0.
304 $listbox->xviewMoveto( fraction );
306 Adjusts the view in the window so that fraction of the
307 total width of the listbox text is off-screen to the left.
308 fraction must be a fraction between 0 and 1.
309 $listbox->xviewScroll( number, what );
311 This command shifts the view in the window left or right
312 according to number and what. Number must be an integer.
313 What must be either units or pages or an abbreviation of
314 one of these. If what is units, the view adjusts left or
315 right by number character units (the width of the 0 charac‐
316 ter) on the display; if it is pages then the view adjusts
317 by number screenfuls. If number is negative then charac‐
318 ters farther to the left become visible; if it is positive
319 then characters farther to the right become visible.
320 $listbox->yview(?args?)
322 This command is used to query and change the vertical position of
323 the text in the widget's window. It can take any of the following
324 forms:
325 $listbox->yview
327 Returns a list containing two elements, both of which are
328 real fractions between 0 and 1. The first element gives
329 the position of the listbox element at the top of the win‐
330 dow, relative to the listbox as a whole (0.5 means it is
331 halfway through the listbox, for example). The second ele‐
332 ment gives the position of the listbox element just after
333 the last one in the window, relative to the listbox as a
334 whole. These are the same values passed to scrollbars via
335 the -yscrollcommand option.
336 $listbox->yview(index)
338 Adjusts the view in the window so that the element given by
339 index is displayed at the top of the window.
340 $listbox->yviewMoveto( fraction );
342 Adjusts the view in the window so that the element given by
343 fraction appears at the top of the window. Fraction is a
344 fraction between 0 and 1; 0 indicates the first element in
345 the listbox, 0.33 indicates the element one-third the way
346 through the listbox, and so on.
347 $listbox->yviewScroll( number, what );
349 This command adjusts the view in the window up or down
350 according to number and what. Number must be an integer.
351 What must be either units or pages. If what is units, the
352 view adjusts up or down by number lines; if it is pages
353 then the view adjusts by number screenfuls. If number is
354 negative then earlier elements become visible; if it is
355 positive then later elements become visible.
356
358 Tk automatically creates class bindings for listboxes that give them
359 Motif-like behavior. Much of the behavior of a listbox is determined
360 by its selectMode option, which selects one of four ways of dealing
361 with the selection.
362 If the selection mode is single or browse, at most one element can be
364 selected in the listbox at once. In both modes, clicking button 1 on
365 an element selects it and deselects any other selected item. In browse
366 mode it is also possible to drag the selection with button 1.
367 If the selection mode is multiple or extended, any number of elements
369 may be selected at once, including discontiguous ranges. In multiple
370 mode, clicking button 1 on an element toggles its selection state with‐
371 out affecting any other elements. In extended mode, pressing button 1
372 on an element selects it, deselects everything else, and sets the
373 anchor to the element under the mouse; dragging the mouse with button
374 1 down extends the selection to include all the elements between the
375 anchor and the element under the mouse, inclusive.
376 Most people will probably want to use browse mode for single selections
378 and extended mode for multiple selections; the other modes appear to be
379 useful only in special situations.
380 Any time the selection changes in the listbox, the virtual event
382 <<ListboxSelect>> will be generated. It is easiest to bind to this
383 event to be made aware of any changes to listbox selection.
384 In addition to the above behavior, the following additional behavior is
386 defined by the default bindings:
387 [1] In extended mode, the selected range can be adjusted by pressing
389 button 1 with the Shift key down: this modifies the selection to
390 consist of the elements between the anchor and the element under
391 the mouse, inclusive. The un-anchored end of this new selection
392 can also be dragged with the button down.
393 [2] In extended mode, pressing button 1 with the Control key down
395 starts a toggle operation: the anchor is set to the element under
396 the mouse, and its selection state is reversed. The selection
397 state of other elements isn't changed. If the mouse is dragged
398 with button 1 down, then the selection state of all elements
399 between the anchor and the element under the mouse is set to match
400 that of the anchor element; the selection state of all other ele‐
401 ments remains what it was before the toggle operation began.
402 [3] If the mouse leaves the listbox window with button 1 down, the win‐
404 dow scrolls away from the mouse, making information visible that
405 used to be off-screen on the side of the mouse. The scrolling con‐
406 tinues until the mouse re-enters the window, the button is
407 released, or the end of the listbox is reached.
408 [4] Mouse button 2 may be used for scanning. If it is pressed and
410 dragged over the listbox, the contents of the listbox drag at high
411 speed in the direction the mouse moves.
412 [5] If the Up or Down key is pressed, the location cursor (active ele‐
414 ment) moves up or down one element. If the selection mode is
415 browse or extended then the new active element is also selected and
416 all other elements are deselected. In extended mode the new active
417 element becomes the selection anchor.
418 [6] In extended mode, Shift-Up and Shift-Down move the location cursor
420 (active element) up or down one element and also extend the selec‐
421 tion to that element in a fashion similar to dragging with mouse
422 button 1.
423 [7] The Left and Right keys scroll the listbox view left and right by
425 the width of the character 0. Control-Left and Control-Right
426 scroll the listbox view left and right by the width of the window.
427 Control-Prior and Control-Next also scroll left and right by the
428 width of the window.
429 [8] The Prior and Next keys scroll the listbox view up and down by one
431 page (the height of the window).
432 [9] The Home and End keys scroll the listbox horizontally to the left
434 and right edges, respectively.
435 [10]
437 Control-Home sets the location cursor to the the first element in
438 the listbox, selects that element, and deselects everything else in
439 the listbox.
440 [11]
442 Control-End sets the location cursor to the the last element in the
443 listbox, selects that element, and deselects everything else in the
444 listbox.
445 [12]
447 In extended mode, Control-Shift-Home extends the selection to the
448 first element in the listbox and Control-Shift-End extends the
449 selection to the last element.
450 [13]
452 In multiple mode, Control-Shift-Home moves the location cursor to
453 the first element in the listbox and Control-Shift-End moves the
454 location cursor to the last element.
455 [14]
457 The space and Select keys make a selection at the location cursor
458 (active element) just as if mouse button 1 had been pressed over
459 this element.
460 [15]
462 In extended mode, Control-Shift-space and Shift-Select extend the
463 selection to the active element just as if button 1 had been
464 pressed with the Shift key down.
465 [16]
467 In extended mode, the Escape key cancels the most recent selection
468 and restores all the elements in the selected range to their previ‐
469 ous selection state.
470 [17]
472 Control-slash selects everything in the widget, except in single
473 and browse modes, in which case it selects the active element and
474 deselects everything else.
475 [18]
477 Control-backslash deselects everything in the widget, except in
478 browse mode where it has no effect.
479 [19]
481 The F16 key (labelled Copy on many Sun workstations) or Meta-w
482 copies the selection in the widget to the clipboard, if there is a
483 selection.
484 The behavior of listboxes can be changed by defining new bindings
486 for individual widgets or by redefining the class bindings.
487
489 The Tk::Listbox widget can also be tied to a scalar or array variable,
490 with different behaviour depending on the variable type, with the fol‐
491 lowing tie commands:
492 use Tk;
494 my ( @array, $scalar, $other );
496 my %options = ( ReturnType => "index" );
497 my $MW = MainWindow->new();
499 my $lbox = $MW->Listbox()->pack();
500 my @list = ( "a", "b", "c", "d", "e", "f" );
502 $lbox->insert('end', @list );
503 tie @array, "Tk::Listbox", $lbox
505 tie $scalar, "Tk::Listbox", $lbox;
506 tie $other, "Tk::Listbox", $lbox, %options;
507 currently only one modifier is implemented, a 3 way flag for tied
509 scalars "ReturnType" which can have values "element", "index" or
510 "both". The default is "element".
511 Tied Arrays
513 If you tie an array to the Listbox you can manipulate the items
514 currently contained by the box in the same manner as a normal
515 array, e.g.
516 print @array;
518 push(@array, @list);
519 my $popped = pop(@array);
520 my $shifted = shift(@array);
521 unshift(@array, @list);
522 delete $array[$index];
523 print $string if exists $array[$i];
524 @array = ();
525 splice @array, $offset, $length, @list
526 The delete function is implemented slightly differently from the
528 standard array implementation. Instead of setting the element at
529 that index to undef it instead physically removes it from the List‐
530 box. This has the effect of changing the array indices, so for
531 instance if you had a list on non-continuous indices you wish to
532 remove from the Listbox you should reverse sort the list and then
533 apply the delete function, e.g.
534 my @list = ( 1, 2, 4, 12, 20 );
536 my @remove = reverse sort { $a <=> $b } @list;
537 delete @array[@remove];
538 would safely remove indices 20, 12, 4, 2 and 1 from the Listbox
540 without problems. It should also be noted that a similar warning
541 applies to the splice function (which would normally be used in
542 this context to perform the same job).
543 Tied Scalars
545 Unlike tied arrays, if you tie a scalar to the Listbox you can
546 retrieve the currently selected elements in the box as an array
547 referenced by the scalar, for instance
548 my @list = ( "a", "b", "c", "d", "e", "f" );
550 $lbox->insert('end', sort @list );
551 $lbox->selectionSet(1);
552 inserts @list as elements in an already existing listbox and
554 selects the element at index 1, which is "b". If we then
555 print @$selected;
557 this will return the currently selected elements, in this case "b".
559 However, if the "ReturnType" arguement is passed when tying the
561 Listbox to the scalar with value "index" then the indices of the
562 selected elements will be returned instead of the elements them‐
563 selves, ie in this case "1". This can be useful when manipulating
564 both contents and selected elements in the Listbox at the same
565 time.
566 Importantly, if a value "both" is given the scalar will not be tied
568 to an array, but instead to a hash, with keys being the indices and
569 values being the elements at those indices
570 You can also manipulate the selected items using the scalar. Equat‐
572 ing the scalar to an array reference will select any elements that
573 match elements in the Listbox, non-matching array items are
574 ignored, e.g.
575 my @list = ( "a", "b", "c", "d", "e", "f" );
577 $lbox->insert('end', sort @list );
578 $lbox->selectionSet(1);
579 would insert the array @list into an already existing Listbox and
581 select element at index 1, i.e. "b"
582 @array = ( "a", "b", "f" );
584 $selected = \@array;
585 would select elements "a", "b" and "f" in the Listbox.
587 Again, if the "index" we indicate we want to use indices in the
589 options hash then the indices are use instead of elements, e.g.
590 @array = ( 0, 1, 5 );
592 $selected = \@array;
593 would have the same effect, selecting elements "a", "b" and "f" if
595 the $selected variable was tied with %options = ( ReturnType =>
596 "index" ).
597 If we are returning "both", i.e. the tied scalar points to a hash,
599 both key and value must match, e.g.
600 %hash = ( 0 => "a", 1 => "b", 5 => "f" );
602 $selected = \%hash;
603 would have the same effect as the previous examples.
605 It should be noted that, despite being a reference to an array (or
607 possibly a has), you still can not copy the tied variable without
608 it being untied, instead you must pass a reference to the tied
609 scalar between subroutines.
610
612 listbox, widget, tied
613
615 Tk::HList, Tk::TextList.
616perl v5.8.8 2008-02-05 Listbox(3)