## com.google.gwt.user.client.ui
Class ListBox

    java.lang.Object
      com.google.gwt.user.client.ui.UIObject
          com.google.gwt.user.client.ui.Widget
              com.google.gwt.user.client.ui.FocusWidget
                  com.google.gwt.user.client.ui.ListBox

All Implemented Interfaces:
  EventListener, HasFocus, HasName, SourcesChangeEvents, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents

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);
>       }
>     }

Constructor Summary
`ListBox()` Creates an empty list box in single selection mode.
`ListBox(boolean isMultipleSelect)` Creates an empty list box.

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

Methods inherited from class com.google.gwt.user.client.ui.FocusWidget
`addClickListener, addFocusListener, addKeyboardListener, getFocusImpl, getTabIndex, isEnabled, removeClickListener, removeFocusListener, removeKeyboardListener, setAccessKey, setElement, setEnabled, setFocus, setTabIndex`

Methods inherited from class com.google.gwt.user.client.ui.Widget
`getParent, isAttached, onAttach, onDetach, onLoad, onUnload, removeFromParent`

Methods inherited from class com.google.gwt.user.client.ui.UIObject
`addStyleName, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getTitle, isVisible, isVisible, removeStyleName, resetStyleName, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setTitle, setVisible, setVisible, setWidth, sinkEvents, toString, unsinkEvents`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

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)

  Description copied from interface: `SourcesChangeEvents`
  Adds a listener interface to receive change events.

  Specified by:
    `addChangeListener` in interface `SourcesChangeEvents`
  Parameters:
    `listener` - the listener interface to add

### addItem

    public void addItem(java.lang.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(java.lang.String item,
                        java.lang.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.

  Returns:
    the number of items

### getItemText

    public java.lang.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
  Returns:
    the text associated with the item

### getName

    public java.lang.String getName()

  Description copied from interface: `HasName`
  Gets the widget's name.

  Specified by:
    `getName` in interface `HasName`
  Returns:
    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).

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

### getValue

    public java.lang.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
  Returns:
    the item's associated value
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is out of range

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

  Returns:
    the visible item count

### insertItem

    public void insertItem(java.lang.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(java.lang.String item,
                           java.lang.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
  Returns:
    `true` if the item is selected

### isMultipleSelect

    public boolean isMultipleSelect()

  Gets whether this list allows multiple selection.

  Returns:
    `true` if multiple selection is allowed

### onBrowserEvent

    public void onBrowserEvent(Event event)

  Description copied from interface: `EventListener`
  Fired whenever a browser event is received.

  Specified by:
    `onBrowserEvent` in interface `EventListener`
  Overrides:
    `onBrowserEvent` in class `FocusWidget`

### removeChangeListener

    public void removeChangeListener(ChangeListener listener)

  Description copied from interface: `SourcesChangeEvents`
  Removes a previously added listener interface.

  Specified by:
    `removeChangeListener` in interface `SourcesChangeEvents`
  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,
                            java.lang.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
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is out of range

### 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(java.lang.String name)

  Description copied from interface: `HasName`
  Sets the widget's name.

  Specified by:
    `setName` in interface `HasName`
  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,
                         java.lang.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`
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is out of range

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