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

doAttachChildren, doDetachChildren, getParent, isAttached, onAttach, onDetach, onLoad, onUnload, removeFromParent

Methods inherited from class com.google.gwt.user.client.ui.UIObject

addStyleDependentName, addStyleName, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, 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

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range

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. If the index is less than zero, or greater than or equal to the length of the list, then the item will be appended to the end of the list.

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

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range

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

Parameters:

event - the event received

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

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range

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

Throws:

java.lang.IndexOutOfBoundsException - if the index is out of range

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