The Listbox Widget

The listbox operations use indices to reference lines in the listbox. The lines are numbered starting at zero. Keyword indices are also used for some special lines. The listbox keeps track of an active element, which is displayed with underlined text. There is also a selection anchor that is used when adjusting selections. Table 35-1 summarizes the keywords used for indices.

Table 35-1. Listbox indices

0	Index of the first line.
active	The index of the activated line.
anchor	The index of the anchor point of the selection.
end	Index of the last line.
number	Index a line, counting from zero.
@x,y	The line closest to the specified X and Y coordinates.

Table 35-2 presents the operations for programming a listbox. In the table, $w is a listbox widget. Most of the operations have to do with the selection, and these operations are already programmed by the default bindings for the Listbox widget class:

Table 35-2. Listbox operations

$w activate index	Activates the specified line.
$w bbox index	Returns the bounding box of the text in the specified line in the form: xoff yoff width height.
$w cget option	Returns the value of the configuration option.
$w configure ...	Queries or modifies the widget configuration.
$w curselection	Returns a list of indices of the selected lines.
$w delete first ?last?	Deletes the lines from first to last, including the line at last. The line at first is deleted if last is not given.
$w get first ?last?	Returns the lines from first to last as a list.
$w index index	Returns the numerical index corresponding to index.
$w insert index ?string string string ...?	Inserts the string items before the line at index. If index is end, then append the items.
$w itemcget index option	Returns the current value of the item's configuration option. (Tk 8.3)
$w itemconfigure index ?option? ?value? ?...?	Queries or modifies the item's configuration options. (Tk 8.3)
$w nearest y	Returns the index of the line closest to the widget-relative Y coordinate.
$w scan mark x y	Starts a scroll operation. x and y are widget-relative screen coordinates.
$w scan dragto x y	Scrolls from previous mark position.
$w see index	Adjusts the display so the line at index is visible.
$w selection anchor index	Anchors the selection at the specified line.
$w selection clear start ?end?	Clears the selection.
$w selection includes index	Returns 1 if the line at index is in the selection.
$w selection set start ?end?	Selects the lines from start to end.
$w size	Returns the number of items in the listbox.
$w xview	Returns the offset and span of visible contents. These are both real numbers between 0 and 1.
$w xview index	Shifts the display so the character at index is at the left edge of the display.
$w xview moveto fraction	Shifts the display so that fraction of the contents are off the left edge of the display.
$w xview scroll num what	Scrolls the contents horizontally by the specified number of what, which can be units or pages.
$w yview	Returns the offset and span of visible contents. These are both real numbers between 0 and 1.
$w yview index	Shifts the display so the line at index is at the top edge of the display.
$w yview moveto fraction	Shifts the display so that fraction of the contents are off the top of the display.
$w yview scroll num what	Scrolls the contents vertically by the specified number of what, which can be units or pages.

As of Tk 8.3, the itemcget and itemconfigure operations allow you to control the appearance of individual items in the listbox, overriding the listbox's defaults. Table 35-3 lists the configuration options supported for individual items. Note that there is no direct support for setting these values through the option resource database; you can set them only through the listbox's itemconfigure operation.

Table 35-3. Listbox item configuration options

-background color	Background color for the item.
-foreground color	Foreground color for the item.
-selectbackground color	Background color for the item when it's selected.
-selectforeground color	Foreground color for the item when it's selected.