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 (off).

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

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 or 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 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 or -1, to move forwards or backwards, respectively.