Book HomeJava and XSLTSearch this book

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.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.