21.10. The Listbox Widget
Create a listbox with the
Listbox method. You can then insert items into the
listbox using the insert method.
$parentwidget->Listbox (options)
The standard configuration options that apply to
Listbox are: -background,
-bg, -borderwidth,
-bd, -cursor,
-exportselection, -font,
-foreground, -fg,
-height, -highlightbackground,
-highlightcolor,
-highlightthickness, -relief,
-select-background,
-selectborderwidth,
-selectforeground, -takefocus,
-width,
-xscroll-command, and
-yscrollcommand.
Other options are:
- -selectmode => mode
-
Determines the number of items
that can be selected at once, as well as key/mouse bindings.
mode can be any of:
- single
-
Only one item can be selected at a time.
- browse
-
Only one item can be selected at a time (default).
- multiple
-
Multiple items can be selected at a time.
- extended
-
Multiple items can be selected at a time.
- -setgrid => boolean
-
Turns on gridding for the listbox. If
the widget is resized, only complete lines and characters are
displayed. Default is 0 (off).
21.10.1. Listbox Indexes
In a Listbox widget, several indexes are defined to identify
positions in the listbox. These are used by the methods that retrieve
and manipulate listbox entries.
- n
-
An integer representing a position in
the list, with 0 as the first item.
- active
-
The item with the keyboard focus.
- anchor
-
The anchored position.
- end
-
The last element in the listbox.
- @x,y
-
The listbox item containing the specified x,y coordinate.
21.10.2. Listbox Methods
In addition to configure and
cget, the following methods are supported by
Listbox:
- insert
-
Adds items to a listbox at the
specified index. For example, to insert items at the end of a list:
$listbox->insert('end', "Puerto Rico", "Virgin Islands", "Guam");
- delete
-
Deletes items from a listbox. To delete
all items:
$listbox->delete(0,'end');
- get
-
Returns a list of elements within the
specified range of indexes. For a list of all elements:
@items = $listbox->get(0,'end');
- curselection
-
Returns a list of all currently
selected elements in the listbox.
- activate
-
Sets the specified item to be the
active element.
- bbox
-
Returns the location and dimensions of
the bounding box surrounding the specified listbox element. The
returned list contains four numbers representing (respectively) the x
coordinate of the upper-left corner, the y coordinate of the
upper-left corner, the width of the text in pixels, and the height of
the text in pixels.
- index
-
Converts a named index into a numeric
one.
- nearest
-
Gets the index of the listbox item
nearest a given y coordinate.
- see
-
Pages the listbox up or down to display
the specified item.
- selection
-
Manipulates the selected block of list
items. The first argument can be any of:
- anchor
-
Sets the anchor index to the specified index.
- clear
-
Clears any selected list items in the specified range. For example,
to clear all selections:
$listbox->selection('clear', 0, 'end');
- includes
-
Returns 0 or 1 depending on
whether the specified item is already selected:
$listbox->selection('includes', 'end');
- set
-
Selects a range of items in the listbox:
$listbox->selection('set', 0, 'end');
- size
-
Returns the total number of items in
the listbox.
- xview
-
Manipulates the text in view. With no
arguments, returns a list of two numbers between 0 and 1, defining
the portion of the list text that is currently hidden on the left and
right sides, respectively. With arguments, the function of
xview changes:
- index
-
If the first argument is an index, that position becomes the leftmost
position in view.
- moveto
-
Moves the specified fraction of the listbox to the left of the
visible portion.
- scroll
-
Scrolls the text left or right by the specified number of units
(characters, in this context) or pages. Used primarily as a callback
to a scrollbar; pressing on an arrow would move by units
(characters), and pressing on the trough would move by pages. The
number is either 1 or -1, to
move forwards or backwards, respectively.
- yview
-
Manipulates the text in view. With no
arguments, returns a list of two numbers between 0 and 1, defining
the portion of the list text that is currently hidden on the top and
bottom, respectively. With arguments, the function of
yview changes:
- index
-
If the first argument is an index, that position becomes the topmost
position in view.
- moveto
-
Moves the specified fraction of the listbox to the top of the visible
portion.
- scroll
-
Scrolls the text up or down by the specified number of units (lines,
in this context) or pages. Used primarily as a callback to a
scrollbar; pressing on an arrow would move by units (lines), and
pressing on the trough would move by pages. The number is either
1 or -1, to move forwards or
backwards, respectively.
 |  |  |
| 21.9. The Scrollbar Widget |  | 21.11. The Text Widget |
Copyright © 2002 O'Reilly & Associates. All rights reserved.