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
14 -highlightthickness -offset -relief -selectbackground
15 -selectborderwidth -selectforeground -setgrid -state -takefocus -tile
16 -width -xscrollcommand -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
27 (underline 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
98 support scanning, as described below.
99
101 Many of the methods for listboxes take one or more indices as
102 arguments. An index specifies a particular element of the listbox, in
103 any 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
112 keyboard 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
141 element is activated. The active element is drawn with an
142 underline when the widget has the input focus, and its index may be
143 retrieved 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
153 element, then the result is an empty string; if the element is
154 partially 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
159 elements in the listbox that are currently selected. If there are
160 no elements selected in the listbox then an empty string is
161 returned.
162 $listbox->delete(first, ?last?)
164 Deletes one or more elements of the listbox. First and last are
165 indices specifying the first and last elements in the range to
166 delete. If last isn't specified it defaults to first, i.e. a
167 single element is deleted.
168 $listbox->get(first, ?last?)
170 If last is omitted, returns the contents of the listbox element
171 indicated by first, or an empty string if first refers to a non-
172 existent element. If last is specified, the command returns a list
173 whose elements are all of the listbox elements between first and
174 last, inclusive. Both first and last may have any of the standard
175 forms for indices.
176 $listbox->index(index)
178 Returns the integer index value that corresponds to index. If
179 index is end the return value is a count of the number of elements
180 in the listbox (not the index of the last element).
181 $listbox->insert(index, ?element, element, ...?)
183 Inserts zero or more new elements in the list just before the
184 element given by index. If index is specified as end then the new
185 elements are added to the end of the list. Returns an empty
186 string.
187 $listbox->itemcget(index, option)
189 Returns the current value of the item configuration option given by
190 option. Option may have any of the values accepted by the listbox
191 itemconfigure command.
192 $listbox->itemconfigure(index, ?option, value, option, value, ...?)
194 Query or modify the configuration options of an item in the
195 listbox. If no option is specified, returns a list describing all
196 of the available options for the item (see Tk_ConfigureInfo for
197 information on the format of this list). If option is specified
198 with no value, then the command returns a list describing the one
199 named option (this list will be identical to the corresponding
200 sublist of the value returned if no option is specified). If one or
201 more option-value pairs are specified, then the command modifies
202 the given widget option(s) to have the given value(s); in this case
203 the command returns an empty string. The following options are
204 currently supported for items:
205 -background => color
207 Color specifies the background color to use when displaying the
208 item. It may have any of the forms accepted by Tk_GetColor.
209 -foreground => color
211 Color specifies the foreground color to use when displaying the
212 item. It may have any of the forms accepted by Tk_GetColor.
213 -selectbackground => color
215 Color specifies the background color to use when displaying the
216 item while it is selected. It may have any of the forms
217 accepted by Tk_GetColor.
218 -selectforeground => color
220 Color specifies the foreground color to use when displaying the
221 item while it is selected. It may have any of the forms
222 accepted by Tk_GetColor.
223 $listbox->nearest(y)
225 Given a y-coordinate within the listbox window, this command
226 returns the index of the (visible) listbox element nearest to that
227 y-coordinate.
228 $listbox->scan(option, args)
230 This command is used to implement scanning on listboxes. It has
231 two forms, depending on option:
232 $listbox->scanMark(x, y)
234 Records x and y and the current view in the listbox window;
235 used in conjunction with later scan dragto commands.
236 Typically this command is associated with a mouse button
237 press in the widget. It returns an empty string.
238 $listbox->scanDragto(x, y.)
240 This command computes the difference between its x and y
241 arguments and the x and y arguments to the last scan mark
242 command for the widget. It then adjusts the view by 10
243 times the difference in coordinates. This command is
244 typically associated with mouse motion events in the
245 widget, to produce the effect of dragging the list at high
246 speed through the window. The return value is an empty
247 string.
248 $listbox->see(index)
250 Adjust the view in the listbox so that the element given by index
251 is visible. If the element is already visible then the command has
252 no effect; if the element is near one edge of the window then the
253 listbox scrolls to bring the element into view at the edge;
254 otherwise the listbox scrolls to center the element.
255 $listbox->selection(option, arg)
257 This command is used to adjust the selection within a listbox. It
258 has several forms, depending on option:
259 $listbox->selectionAnchor(index)
261 Sets the selection anchor to the element given by index.
262 If index refers to a non-existent element, then the closest
263 element is used. The selection anchor is the end of the
264 selection that is fixed while dragging out a selection with
265 the mouse. The index anchor may be used to refer to the
266 anchor element.
267 $listbox->selectionClear(first, ?last?)
269 If any of the elements between first and last (inclusive)
270 are selected, they are deselected. The selection state is
271 not changed for elements outside this range.
272 $listbox->selectionIncludes(index)
274 Returns 1 if the element indicated by index is currently
275 selected, 0 if it isn't.
276 $listbox->selectionSet(first, ?last?)
278 Selects all of the elements in the range between first and
279 last, inclusive, without affecting the selection state of
280 elements outside that range.
281 $listbox->size
283 Returns a decimal string indicating the total number of elements in
284 the listbox.
285 $listbox->xview(args)
287 This command is used to query and change the horizontal position of
288 the information in the widget's window. It can take any of the
289 following forms:
290 $listbox->xview
292 Returns a list containing two elements. Each element is a
293 real fraction between 0 and 1; together they describe the
294 horizontal span that is visible in the window. For
295 example, if the first element is .2 and the second element
296 is .6, 20% of the listbox's text is off-screen to the left,
297 the middle 40% is visible in the window, and 40% of the
298 text is off-screen to the right. These are the same values
299 passed to scrollbars via the -xscrollcommand option.
300 $listbox->xview(index)
302 Adjusts the view in the window so that the character
303 position given by index is displayed at the left edge of
304 the window. Character positions are defined by the width
305 of the character 0.
306 $listbox->xviewMoveto( fraction );
308 Adjusts the view in the window so that fraction of the
309 total width of the listbox text is off-screen to the left.
310 fraction must be a fraction between 0 and 1.
311 $listbox->xviewScroll( number, what );
313 This command shifts the view in the window left or right
314 according to number and what. Number must be an integer.
315 What must be either units or pages or an abbreviation of
316 one of these. If what is units, the view adjusts left or
317 right by number character units (the width of the 0
318 character) on the display; if it is pages then the view
319 adjusts by number screenfuls. If number is negative then
320 characters farther to the left become visible; if it is
321 positive then characters farther to the right become
322 visible.
323 $listbox->yview(?args?)
325 This command is used to query and change the vertical position of
326 the text in the widget's window. It can take any of the following
327 forms:
328 $listbox->yview
330 Returns a list containing two elements, both of which are
331 real fractions between 0 and 1. The first element gives
332 the position of the listbox element at the top of the
333 window, relative to the listbox as a whole (0.5 means it is
334 halfway through the listbox, for example). The second
335 element gives the position of the listbox element just
336 after the last one in the window, relative to the listbox
337 as a whole. These are the same values passed to scrollbars
338 via the -yscrollcommand option.
339 $listbox->yview(index)
341 Adjusts the view in the window so that the element given by
342 index is displayed at the top of the window.
343 $listbox->yviewMoveto( fraction );
345 Adjusts the view in the window so that the element given by
346 fraction appears at the top of the window. Fraction is a
347 fraction between 0 and 1; 0 indicates the first element in
348 the listbox, 0.33 indicates the element one-third the way
349 through the listbox, and so on.
350 $listbox->yviewScroll( number, what );
352 This command adjusts the view in the window up or down
353 according to number and what. Number must be an integer.
354 What must be either units or pages. If what is units, the
355 view adjusts up or down by number lines; if it is pages
356 then the view adjusts by number screenfuls. If number is
357 negative then earlier elements become visible; if it is
358 positive then later elements become visible.
359
361 Tk automatically creates class bindings for listboxes that give them
362 Motif-like behavior. Much of the behavior of a listbox is determined
363 by its selectMode option, which selects one of four ways of dealing
364 with the selection.
365 If the selection mode is single or browse, at most one element can be
367 selected in the listbox at once. In both modes, clicking button 1 on
368 an element selects it and deselects any other selected item. In browse
369 mode it is also possible to drag the selection with button 1.
370 If the selection mode is multiple or extended, any number of elements
372 may be selected at once, including discontiguous ranges. In multiple
373 mode, clicking button 1 on an element toggles its selection state
374 without affecting any other elements. In extended mode, pressing
375 button 1 on an element selects it, deselects everything else, and sets
376 the anchor to the element under the mouse; dragging the mouse with
377 button 1 down extends the selection to include all the elements between
378 the anchor and the element under the mouse, inclusive.
379 Most people will probably want to use browse mode for single selections
381 and extended mode for multiple selections; the other modes appear to be
382 useful only in special situations.
383 Any time the selection changes in the listbox, the virtual event
385 <<ListboxSelect>> will be generated. It is easiest to bind to this
386 event to be made aware of any changes to listbox selection.
387 In addition to the above behavior, the following additional behavior is
389 defined by the default bindings:
390 [1] In extended mode, the selected range can be adjusted by pressing
392 button 1 with the Shift key down: this modifies the selection to
393 consist of the elements between the anchor and the element under
394 the mouse, inclusive. The un-anchored end of this new selection
395 can also be dragged with the button down.
396 [2] In extended mode, pressing button 1 with the Control key down
398 starts a toggle operation: the anchor is set to the element under
399 the mouse, and its selection state is reversed. The selection
400 state of other elements isn't changed. If the mouse is dragged
401 with button 1 down, then the selection state of all elements
402 between the anchor and the element under the mouse is set to match
403 that of the anchor element; the selection state of all other
404 elements remains what it was before the toggle operation began.
405 [3] If the mouse leaves the listbox window with button 1 down, the
407 window scrolls away from the mouse, making information visible that
408 used to be off-screen on the side of the mouse. The scrolling
409 continues until the mouse re-enters the window, the button is
410 released, or the end of the listbox is reached.
411 [4] Mouse button 2 may be used for scanning. If it is pressed and
413 dragged over the listbox, the contents of the listbox drag at high
414 speed in the direction the mouse moves.
415 [5] If the Up or Down key is pressed, the location cursor (active
417 element) moves up or down one element. If the selection mode is
418 browse or extended then the new active element is also selected and
419 all other elements are deselected. In extended mode the new active
420 element becomes the selection anchor.
421 [6] In extended mode, Shift-Up and Shift-Down move the location cursor
423 (active element) up or down one element and also extend the
424 selection to that element in a fashion similar to dragging with
425 mouse button 1.
426 [7] The Left and Right keys scroll the listbox view left and right by
428 the width of the character 0. Control-Left and Control-Right
429 scroll the listbox view left and right by the width of the window.
430 Control-Prior and Control-Next also scroll left and right by the
431 width of the window.
432 [8] The Prior and Next keys scroll the listbox view up and down by one
434 page (the height of the window).
435 [9] The Home and End keys scroll the listbox horizontally to the left
437 and right edges, respectively.
438 [10]
440 Control-Home sets the location cursor to the the first element in
441 the listbox, selects that element, and deselects everything else in
442 the listbox.
443 [11]
445 Control-End sets the location cursor to the the last element in the
446 listbox, selects that element, and deselects everything else in the
447 listbox.
448 [12]
450 In extended mode, Control-Shift-Home extends the selection to the
451 first element in the listbox and Control-Shift-End extends the
452 selection to the last element.
453 [13]
455 In multiple mode, Control-Shift-Home moves the location cursor to
456 the first element in the listbox and Control-Shift-End moves the
457 location cursor to the last element.
458 [14]
460 The space and Select keys make a selection at the location cursor
461 (active element) just as if mouse button 1 had been pressed over
462 this element.
463 [15]
465 In extended mode, Control-Shift-space and Shift-Select extend the
466 selection to the active element just as if button 1 had been
467 pressed with the Shift key down.
468 [16]
470 In extended mode, the Escape key cancels the most recent selection
471 and restores all the elements in the selected range to their
472 previous selection state.
473 [17]
475 Control-slash selects everything in the widget, except in single
476 and browse modes, in which case it selects the active element and
477 deselects everything else.
478 [18]
480 Control-backslash deselects everything in the widget, except in
481 browse mode where it has no effect.
482 [19]
484 The F16 key (labelled Copy on many Sun workstations) or Meta-w
485 copies the selection in the widget to the clipboard, if there is a
486 selection.
487 The behavior of listboxes can be changed by defining new bindings
489 for individual widgets or by redefining the class bindings.
490
492 The Tk::Listbox widget can also be tied to a scalar or array variable,
493 with different behaviour depending on the variable type, with the
494 following tie commands:
495 use Tk;
497 my ( @array, $scalar, $other );
499 my %options = ( ReturnType => "index" );
500 my $MW = MainWindow->new();
502 my $lbox = $MW->Listbox()->pack();
503 my @list = ( "a", "b", "c", "d", "e", "f" );
505 $lbox->insert('end', @list );
506 tie @array, "Tk::Listbox", $lbox
508 tie $scalar, "Tk::Listbox", $lbox;
509 tie $other, "Tk::Listbox", $lbox, %options;
510 currently only one modifier is implemented, a 3 way flag for tied
512 scalars "ReturnType" which can have values "element", "index" or
513 "both". The default is "element".
514 Tied Arrays
516 If you tie an array to the Listbox you can manipulate the items
517 currently contained by the box in the same manner as a normal
518 array, e.g.
519 print @array;
521 push(@array, @list);
522 my $popped = pop(@array);
523 my $shifted = shift(@array);
524 unshift(@array, @list);
525 delete $array[$index];
526 print $string if exists $array[$i];
527 @array = ();
528 splice @array, $offset, $length, @list
529 The delete function is implemented slightly differently from the
531 standard array implementation. Instead of setting the element at
532 that index to undef it instead physically removes it from the
533 Listbox. This has the effect of changing the array indices, so for
534 instance if you had a list on non-continuous indices you wish to
535 remove from the Listbox you should reverse sort the list and then
536 apply the delete function, e.g.
537 my @list = ( 1, 2, 4, 12, 20 );
539 my @remove = reverse sort { $a <=> $b } @list;
540 delete @array[@remove];
541 would safely remove indices 20, 12, 4, 2 and 1 from the Listbox
543 without problems. It should also be noted that a similar warning
544 applies to the splice function (which would normally be used in
545 this context to perform the same job).
546 Tied Scalars
548 Unlike tied arrays, if you tie a scalar to the Listbox you can
549 retrieve the currently selected elements in the box as an array
550 referenced by the scalar, for instance
551 my @list = ( "a", "b", "c", "d", "e", "f" );
553 $lbox->insert('end', sort @list );
554 $lbox->selectionSet(1);
555 inserts @list as elements in an already existing listbox and
557 selects the element at index 1, which is "b". If we then
558 print @$selected;
560 this will return the currently selected elements, in this case "b".
562 However, if the "ReturnType" arguement is passed when tying the
564 Listbox to the scalar with value "index" then the indices of the
565 selected elements will be returned instead of the elements
566 themselves, ie in this case "1". This can be useful when
567 manipulating both contents and selected elements in the Listbox at
568 the same time.
569 Importantly, if a value "both" is given the scalar will not be tied
571 to an array, but instead to a hash, with keys being the indices and
572 values being the elements at those indices
573 You can also manipulate the selected items using the scalar.
575 Equating the scalar to an array reference will select any elements
576 that match elements in the Listbox, non-matching array items are
577 ignored, e.g.
578 my @list = ( "a", "b", "c", "d", "e", "f" );
580 $lbox->insert('end', sort @list );
581 $lbox->selectionSet(1);
582 would insert the array @list into an already existing Listbox and
584 select element at index 1, i.e. "b"
585 @array = ( "a", "b", "f" );
587 $selected = \@array;
588 would select elements "a", "b" and "f" in the Listbox.
590 Again, if the "index" we indicate we want to use indices in the
592 options hash then the indices are use instead of elements, e.g.
593 @array = ( 0, 1, 5 );
595 $selected = \@array;
596 would have the same effect, selecting elements "a", "b" and "f" if
598 the $selected variable was tied with %options = ( ReturnType =>
599 "index" ).
600 If we are returning "both", i.e. the tied scalar points to a hash,
602 both key and value must match, e.g.
603 %hash = ( 0 => "a", 1 => "b", 5 => "f" );
605 $selected = \%hash;
606 would have the same effect as the previous examples.
608 It should be noted that, despite being a reference to an array (or
610 possibly a has), you still can not copy the tied variable without
611 it being untied, instead you must pass a reference to the tied
612 scalar between subroutines.
613
615 listbox, widget, tied
616
618 Tk::HList, Tk::TextList.
619perl v5.36.0 2022-07-22 Listbox(3)