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)

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

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.

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.