Google Web Toolkit (Beta)
Search this site:

# Class ListBox

public class ListBox
extends FocusWidget
implements SourcesChangeEvents, HasName
A widget that presents a list of choices to the user, either as a list box or as a drop-down list.

### CSS Style Rules

- .gwt-ListBox { }

### Example

    public class ListBoxExample implements EntryPoint {

      public void onModuleLoad() {
        // Make a new list box, adding a few items to it.
        ListBox lb = new ListBox();
        lb.addItem("foo");
        lb.addItem("bar");
        lb.addItem("baz");
        lb.addItem("toto");
        lb.addItem("tintin");

        // Make enough room for all five items (setting this value to 1 turns it
        // into a drop-down list).
        lb.setVisibleItemCount(5);

        // Add it to the root panel.
        RootPanel.get().add(lb);
      }
    }

## Constructors

ListBox() | Creates an empty list box in single selection mode.
ListBox(boolean) | Creates an empty list box.

## Methods

addChangeListener(ChangeListener) | Adds a listener interface to receive change events.
addItem(String) | Adds an item to the list box.
addItem(String, String) | Adds an item to the list box, specifying an initial value for the item.
clear() | Removes all items from the list box.
getItemCount() | Gets the number of items present in the list box.
getItemText(int) | Gets the text associated with the item at the specified index.
getName() | Gets the widget's name.
getSelectedIndex() | Gets the currently-selected item.
getValue(int) | Gets the value associated with the item at a given index.
getVisibleItemCount() | Gets the number of items that are visible.
insertItem(String, int) | Inserts an item into the list box.
insertItem(String, String, int) | Inserts an item into the list box, specifying an initial value for the item.
isItemSelected(int) | Determines whether an individual list item is selected.
isMultipleSelect() | Gets whether this list allows multiple selection.
onBrowserEvent(Event) |
removeChangeListener(ChangeListener) | Removes a previously added listener interface.
removeItem(int) | Removes the item at the specified index.
setItemSelected(int, boolean) | Sets whether an individual list item is selected.
setItemText(int, String) | Sets the text associated with the item at a given index.
setMultipleSelect(boolean) | Sets whether this list allows multiple selections.
setName(String) | Sets the widget's name.
setSelectedIndex(int) | Sets the currently selected index.
setValue(int, String) | Sets the value associated with the item at a given index.
setVisibleItemCount(int) | Sets the number of items that are visible.

## Constructor Detail

### ListBox

public ListBox()
Creates an empty list box in single selection mode.

### ListBox

public ListBox(boolean isMultipleSelect)
Creates an empty list box. The preferred way to enable multiple selections is to use this constructor rather than setMultipleSelect(boolean).

#### Parameters

isMultipleSelect
  specifies if multiple selection is enabled

## Method Detail

### addChangeListener

public void addChangeListener(ChangeListener listener)
Adds a listener interface to receive change events.

#### Parameters

listener
  the listener interface to add

### addItem

public void addItem(String item)
Adds an item to the list box. This method has the same effect as

     addItem(item, item)

#### Parameters

item
  the text of the item to be added

### addItem

public void addItem(String item, String value)
Adds an item to the list box, specifying an initial value for the item.

#### Parameters

item
  the text of the item to be added
value
  the item's value, to be submitted if it is part of a FormPanel; cannot be `null`

### clear

public void clear()
Removes all items from the list box.

### getItemCount

public int getItemCount()
Gets the number of items present in the list box.

#### Return Value

the number of items

### getItemText

public String getItemText(int index)
Gets the text associated with the item at the specified index.

#### Parameters

index
  the index of the item whose text is to be retrieved

#### Return Value

the text associated with the item

### getName

public String getName()
Gets the widget's name.

#### Return Value

the widget's name

### getSelectedIndex

public int getSelectedIndex()
Gets the currently-selected item. If multiple items are selected, this method will return the first selected item (isItemSelected(int) can be used to query individual items).

#### Return Value

the selected index, or `-1` if none is selected

### getValue

public String getValue(int index)
Gets the value associated with the item at a given index.

#### Parameters

index
  the index of the item to be retrieved

#### Return Value

the item's associated value

### getVisibleItemCount

public int getVisibleItemCount()
Gets the number of items that are visible. If only one item is visible, then the box will be displayed as a drop-down list.

#### Return Value

the visible item count

### insertItem

public void insertItem(String item, int index)
Inserts an item into the list box. Has the same effect as

     insertItem(item, item, index)

#### Parameters

item
  the text of the item to be inserted
index
  the index at which to insert it

### insertItem

public void insertItem(String item, String value, int index)
Inserts an item into the list box, specifying an initial value for the item.

#### Parameters

item
  the text of the item to be inserted
value
  the item's value, to be submitted if it is part of a FormPanel.
index
  the index at which to insert it

### isItemSelected

public boolean isItemSelected(int index)
Determines whether an individual list item is selected.

#### Parameters

index
  the index of the item to be tested

#### Return Value

`true` if the item is selected

### isMultipleSelect

public boolean isMultipleSelect()
Gets whether this list allows multiple selection.

#### Return Value

`true` if multiple selection is allowed

### onBrowserEvent

public void onBrowserEvent(Event event)

#### Parameters

event

### removeChangeListener

public void removeChangeListener(ChangeListener listener)
Removes a previously added listener interface.

#### Parameters

listener
  the listener interface to remove

### removeItem

public void removeItem(int index)
Removes the item at the specified index.

#### Parameters

index
  the index of the item to be removed

### setItemSelected

public void setItemSelected(int index, boolean selected)
Sets whether an individual list item is selected.

Note that setting the selection programmatically does not cause the ChangeListener.onChange(Widget) event to be fired.

#### Parameters

index
  the index of the item to be selected or unselected
selected
  `true` to select the item

### setItemText

public void setItemText(int index, String text)
Sets the text associated with the item at a given index.

#### Parameters

index
  the index of the item to be set
text
  the item's new text

### setMultipleSelect

public void setMultipleSelect(boolean multiple)
Sets whether this list allows multiple selections. NOTE: The preferred way of enabling multiple selections in a list box is by using the ListBox(boolean) constructor. Using this method can spuriously fail on Internet Explorer 6.0.

#### Parameters

multiple
  `true` to allow multiple selections

### setName

public void setName(String name)
Sets the widget's name.

#### Parameters

name
  the widget's new name

### setSelectedIndex

public void setSelectedIndex(int index)
Sets the currently selected index.

Note that setting the selected index programmatically does not cause the ChangeListener.onChange(Widget) event to be fired.

#### Parameters

index
  the index of the item to be selected

### setValue

public void setValue(int index, String value)
Sets the value associated with the item at a given index. This value can be used for any purpose, but is also what is passed to the server when the list box is submitted as part of a FormPanel.

#### Parameters

index
  the index of the item to be set
value
  the item's new value; cannot be `null`

### setVisibleItemCount

public void setVisibleItemCount(int visibleItems)
Sets the number of items that are visible. If only one item is visible, then the box will be displayed as a drop-down list.

#### Parameters

visibleItems
  the visible item count