JavaScript EditorFree JavaScript Editor     Perl Manuals 

Main Page

Chapter 7. The Listbox Widget


Creating and Filling a Listbox
Listbox Options
Selection Modes
Listbox Style
Configuring a Listbox
Inserting Items
Deleting Items
Retrieving Elements
Selection Methods
Moving to a Specific Index
Translating Indexes
Counting Items
Active Versus Selected
Bounding Box
Finding an Index by y Coordinate
Scrolling Methods
Listbox Virtual Events
Listbox Example

A Listbox widget is designed to list strings of text, one text string per line. You can then select a line or multiple lines from the Listbox on which to perform other operations. Some examples of things to place inside a Listbox include:

Figure 7-1 shows an example of a Listbox.

Figure 7-1

Figure 7-1. Listbox widget

A Listbox is ideal for replacing Radiobuttons or Checkbuttons that have become too numerous to display on the screen. Usually 3 or 4 Checkbuttons or Radiobuttons aren't a big deal, but if you try to display 10 at a time, the window could get a little crowded. A group of Radiobuttons can be replaced by a Listbox that limits the number of selections to one and has a default selection. A bunch of Checkbuttons can be replaced by a Listbox that allows multiple selections.

There are times when you'd like several Listboxes arranged side-by-side that scroll in parallel. While the standard Perl/Tk distribution doesn't have such a widget, Chapter 23, "Plethora of pTk Potpourri" highlights some user-contributed "multi-Listbox" widgets.

An alternative to the plain Listbox are the HList and TextList widgets, which allow single lines to be configured individually.

7.1. Creating and Filling a Listbox

To create a Listbox widget, use the Listbox method on the parent of the Listbox:

$lb = $parent->Listbox( [ options ...] )->pack;

The Listbox method returns a reference to the Listbox that you've created. You can now use this reference to configure the Listbox, insert items into the Listbox, and so on. After creating a Listbox, use the insert method to insert items into it:

$lb->insert('end', @listbox_items);
# or...
$lb->insert('end', $item1, $item2, $item3);

The insert method takes an index value as the first argument; the rest of the arguments will be considered items to put into the Listbox. Listbox indexes are similar to the Entry widget indexes except they refer to lines instead of individual characters.

We could use a Listbox instead of Radiobuttons to select our window background color (see Chapter 4, " Button, Checkbutton, and Radiobutton Widgets" for the Radiobutton example). The Listbox code looks like this:

$lb = $mw->Listbox(-selectmode => "single")->pack( );
$lb->insert('end', qw/red yellow green blue grey/);
          sub { $lb->configure(-background => 
                             $lb->get($lb->curselection( )) );

The -selectmode option limits the number of selections to one. We insert some colors from which to choose. There is no -command option for a Listbox, so we use bind (see Chapter 15, "Anatomy of the MainLoop") to make something happen when the user clicks on an item with the left mouse button. Using the Listbox methods get and curselection, we determine which item the user clicked on and then set the background of the Listbox to that color. There are only five colors in our example here; you can use more colors and add a Scrollbar to make it more useful. You can add a Scrollbar by changing the line with Listbox in it:

$lb = $mw->Scrolled("Listbox", -scrollbars => "e",
                    -selectmode => "single")->pack( );

All the other lines in the program remain unchanged. For more information about adding and utilizing Scrollbars, see Chapter 6, "The Scrollbar Widget". Now that we've looked at an example, let's go over the options and methods that let us use the Listbox the way we want to.

JavaScript EditorJavaScript Formatter     Perl Manuals