 |  |
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.
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.