Listbox Bindings and Events

A listbox has an active element and it may have one or more selected elements. The active element is highlighted according to the -activestyle options (by default, with an underline), and the selected elements are highlighted with a different color. There are a large number of key bindings for listboxes. You must set the input focus to the listbox for the key bindings to work. Chapter 39 describes focus. There are four selection modes for a listbox, and the bindings vary depending what mode the listbox is in. Table 35-4 lists the four possible selectMode settings:

Table 35-4. The values for the selectMode of a listbox

single	A single element can be selected.
browse	A single element can be selected, and the selection can be dragged with the mouse. This is the default.
multiple	More than one element can be selected by toggling the selection state of items, but you only select or deselect one line at a time.
extended	More than one element can be selected by dragging out a selection with the shift or control keys.

Browse Select Mode

In browse selection mode, <Button-1> selects the item under the mouse and dragging with the mouse moves the selection, too. Table 35-5 gives the bindings for browse mode.

Table 35-5. Bindings for browse selection mode

<Button-1>	Selects the item under the mouse. This becomes the active element, too.
<B1-Motion>	Same as <Button-1>, the selection moves with the mouse.
<Shift-Button-1>	Activates the item under the mouse. The selection is not changed.
<Key-Up> <Key-Down>	Moves the active item up (down) one line, and selects it.
<Control-Home>	Activates and select the first element of the listbox.
<Control-End>	Activates and select the last element of the listbox.
<space> <Select> <Control-slash>	Selects the active element.

Single Select Mode

In single selection mode, <Button-1> selects the item under the mouse, but dragging the mouse does not change the selection. When you release the mouse, the item under that point is activated. Table 35-6 specifies the bindings for single mode:

Table 35-6. Bindings for single selection mode

<ButtonPress-1>	Selects the item under the mouse.
<ButtonRelease-1>	Activates the item under the mouse.
<Shift-Button-1>	Activates the item under the mouse. The selection is not changed.
<Key-Up> <Key-Down>	Moves the active item up (down) one line. The selection is not changed.
<Control-Home>	Activates and selects the first element of the listbox.
<Control-End>	Activates and selects the last element of the listbox.
<space> <Select> <Control-slash>	Selects the active element.
<Control-backslash>	Clears the selection.

Extended Select Mode

In extended selection mode, multiple items are selected by dragging out a selection with the first mouse button. Hold down the Shift key to adjust the ends of the selection. Use the Control key to make a disjoint selection. The Control key works in a toggle fashion, changing the selection state of the item under the mouse. If this starts a new part of the selection, then dragging the mouse extends the new part of the selection. If the toggle action cleared the selected item, then dragging the mouse continues to clear the selection. The extended mode is quite intuitive once you try it. Table 35-7 specifies the complete set of bindings for extended mode:

Table 35-7. Bindings for extended selection mode

<Button-1>	Selects the item under the mouse. This becomes the anchor point for adjusting the selection.
<B1-Motion>	Sweeps out a selection from the anchor point.
<ButtonRelease-1>	Activates the item under the mouse.
<Shift-Button-1>	Adjusts the selection from the anchor item to the item under the mouse.
<Shift-B1-Motion>	Continues to adjust the selection from the anchor.
<Control-Button-1>	Toggles the selection state of the item under the mouse, and makes this the anchor point.
<Control-B1-Motion>	Sets the selection state of the items from the anchor point to the item under the mouse to be the same as the selection state of the anchor point.
<Key-Up> <Key-Down>	Moves the active item up (down) one line, and starts a new selection with this item as the anchor point.
<Shift-Up> <Shift-Down>	Moves the active element up (down) and extends the selection to include this element.
<Control-Home>	Activates and selects the first element of the listbox.
<Control-Shift-Home>	Extends the selection to the first element.
<Control-End>	Activates and selects the last element of the listbox.
<Control-Shift-End>	Extends the selection to the last element.
<space> <Select>	Selects the active element.
<Escape>	Cancels the previous selection action.
<Control-slash>	Selects everything in the listbox.
<Control-backslash>	Clears the selection.

Multiple Select Mode

In multiple selection mode you can select more than one item, but you can add or remove only one item at a time. Dragging the mouse does not sweep out a selection. If you click on a selected item it is deselected. Table 35-8 specifies the complete set of bindings for multiple selection mode.

Table 35-8. Bindings for multiple selection mode

<Button-1>	Selects the item under the mouse.
<ButtonRelease-1>	Activates the item under the mouse.
<Key-Up> <Key-Down>	Moves the active item up (down) one line, and starts a new selection with this item as the anchor point.
<Shift-Up> <Shift-Down>	Moves the active element up (down).
<Control-Home>	Activates and selects the first element of the listbox.
<Control-Shift-Home>	Activates the first element of the listbox.
<Control-End>	Activates and selects the last element of the listbox.
<Control-Shift-End>	Activates the last element of the listbox.
<space> <Select>	Selects the active element.
<Control-slash>	Selects everything in the listbox.
<Control-backslash>	Clears the selection.

Scroll Bindings

There are several bindings that scroll the display of the listbox. In addition to the standard middle-drag scrolling, there are some additional key bindings for scrolling. Table 35-9 summarizes the scroll-related bindings:

Table 35-9. Listbox scroll bindings

<Button-2>	Marks the start of a scroll operation.
<B2-Motion>	Scrolls vertically and horizontally.
<MouseWheel>	Scrolls vertically.
<Button-4>	Mousewheel support on Unix only; scrolls up. (Tk 8.3)
<Button-5>	Mousewheel support on Unix only; scrolls down. (Tk 8.3)
<Left> <Right>	Scrolls horizontally by one character.
<Control-Left> <Control-Right> <Control-Prior> <Control-Next>	Scrolls horizontally by one screen width.
<Prior> <Next>	Scrolls vertically by one screen height.
<Home> <End>	Scrolls to left and right edges of the screen, respectively.

Listbox Virtual Events

As of Tk 8.1, the listbox widget generates a <<ListboxSelect>> virtual event whenever the listbox selection changes. The event fires after the selection has changed, so the binding action can access the new selection. The easiest way to be aware of changes to the listbox selection is to bind to this virtual event, as shown in Example 35-3:

Example 35-3 Using the <<ListboxSelect>> virtual event

proc ListboxChanged {w} {
    puts -nonewline "Listbox $w selection is now: "
    foreach index [$w curselection] {
        puts -nonewline "[$w get $index] "
    }
    puts ""
}
bind .lbox <<ListboxSelect>> {ListboxChanged %W}