[Chapter 18] 18.10 The Listbox Widget
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T01:58:54Z

#

| Chapter 18 Perl/Tk |

## 18.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`, `-selectbackground`, `-selectborderwidth`, `-selectforeground`, `-takefocus`, `-width`, `-xscrollcommand`, and `-yscrollcommand`.

Other options are:

`-selectmode =>` `mode`

  Determines how many items 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).

### 18.10.1 Listbox Indexes

In a Listbox widget, several indexes are defined to identify positions in the listbox, for use by the methods used for retrieving or manipulating listbox entries. These indexes are:

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

### 18.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 to 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 what portion of the list text 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 what portion of the list text 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.

18.9 The Scrollbar Widget |  | 18.11 The Text Widget