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

Class Overview

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

{@example com.google.gwt.examples.ListBoxExample}

Built-in Bidi Text Support

This widget is capable of automatically adjusting its direction according to its content. This feature is controlled by setDirectionEstimator(boolean), and is off by default.

Use in UiBinder Templates

The items of a ListBox element are laid out in <g:item> elements. Each item contains text that will be added to the list of available items that will be shown, either in the drop down or list. (Note that the tags of the item elements are not capitalized. This is meant to signal that the item is not a runtime object, and so cannot have a ui:field attribute.) It is also possible to explicitly specify item's value using value attribute as shown below.

For example:

 <g:ListBox>
  <g:item>
    first
  </g:item>
  <g:item value='2'>
    second
  </g:item>
 </g:ListBox>
 

Summary

[Expand]
Inherited Constants
From class com.google.gwt.user.client.ui.UIObject
Fields
public static final DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR
Public Constructors
ListBox()
Creates an empty list box in single selection mode.
ListBox(boolean isMultipleSelect)
Creates an empty list box.
Protected Constructors
ListBox(Element element)
This constructor may be used by subclasses to explicitly use an existing element.
Public Methods
HandlerRegistration addChangeHandler(ChangeHandler handler)
Adds a ChangeEvent handler.
void addChangeListener(ChangeListener listener)
This method is deprecated. Use addChangeHandler(ChangeHandler) instead
void addItem(String item)
Adds an item to the list box.
void addItem(String item, HasDirection.Direction dir)
Adds an item to the list box, specifying its direction.
void addItem(String item, HasDirection.Direction dir, String value)
Adds an item to the list box, specifying its direction and an initial value for the item.
void addItem(String item, 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.
DirectionEstimator getDirectionEstimator()
Returns the DirectionEstimator object.
int getItemCount()
Gets the number of items present in the list box.
String getItemText(int index)
Gets the text associated with the item at the specified index.
String getName()
Gets the widget's name.
int getSelectedIndex()
Gets the currently-selected item.
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(String item, HasDirection.Direction dir, String value, int index)
Inserts an item into the list box, specifying its direction and an initial value for the item.
void insertItem(String item, int index)
Inserts an item into the list box.
void insertItem(String item, HasDirection.Direction dir, int index)
Inserts an item into the list box, specifying its direction.
void insertItem(String item, 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 removeChangeListener(ChangeListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by addChangeHandler(ChangeHandler) instead
void removeItem(int index)
Removes the item at the specified index.
void setDirectionEstimator(DirectionEstimator directionEstimator)
Sets the DirectionEstimator object. Note: this does not affect the direction of already-existing content.
void setDirectionEstimator(boolean enabled)
Toggles on / off direction estimation. See note at setDirectionEstimator(com.google.gwt.i18n.shared.DirectionEstimator)
void setItemSelected(int index, boolean selected)
Sets whether an individual list item is selected.
void setItemText(int index, String text)
Sets the text associated with the item at a given index.
void setItemText(int index, String text, HasDirection.Direction dir)
Sets the text associated with the item at a given index.
void setMultipleSelect(boolean multiple)
This method is deprecated. use ListBox(boolean) instead
void setName(String name)
Sets the widget's name.
void setSelectedIndex(int index)
Sets the currently selected index.
void setValue(int index, 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.
static ListBox wrap(Element element)
Creates a ListBox widget that wraps an existing <select> element.
Protected Methods
void onEnsureDebugId(String baseID)
Affected Elements:
  • -item# = the option at the specified index.
[Expand]
Inherited Methods
From class com.google.gwt.user.client.ui.FocusWidget
From class com.google.gwt.user.client.ui.Widget
From class com.google.gwt.user.client.ui.UIObject
From class java.lang.Object
From interface com.google.gwt.event.dom.client.HasBlurHandlers
From interface com.google.gwt.event.dom.client.HasChangeHandlers
From interface com.google.gwt.event.dom.client.HasClickHandlers
From interface com.google.gwt.event.dom.client.HasDoubleClickHandlers
From interface com.google.gwt.event.dom.client.HasFocusHandlers
From interface com.google.gwt.event.dom.client.HasGestureChangeHandlers
From interface com.google.gwt.event.dom.client.HasGestureEndHandlers
From interface com.google.gwt.event.dom.client.HasGestureStartHandlers
From interface com.google.gwt.event.dom.client.HasKeyDownHandlers
From interface com.google.gwt.event.dom.client.HasKeyPressHandlers
From interface com.google.gwt.event.dom.client.HasKeyUpHandlers
From interface com.google.gwt.event.dom.client.HasMouseDownHandlers
From interface com.google.gwt.event.dom.client.HasMouseMoveHandlers
From interface com.google.gwt.event.dom.client.HasMouseOutHandlers
From interface com.google.gwt.event.dom.client.HasMouseOverHandlers
From interface com.google.gwt.event.dom.client.HasMouseUpHandlers
From interface com.google.gwt.event.dom.client.HasMouseWheelHandlers
From interface com.google.gwt.event.dom.client.HasTouchCancelHandlers
From interface com.google.gwt.event.dom.client.HasTouchEndHandlers
From interface com.google.gwt.event.dom.client.HasTouchMoveHandlers
From interface com.google.gwt.event.dom.client.HasTouchStartHandlers
From interface com.google.gwt.event.logical.shared.HasAttachHandlers
From interface com.google.gwt.event.shared.HasHandlers
From interface com.google.gwt.i18n.shared.HasDirectionEstimator
From interface com.google.gwt.user.client.EventListener
From interface com.google.gwt.user.client.ui.Focusable
From interface com.google.gwt.user.client.ui.HasEnabled
From interface com.google.gwt.user.client.ui.HasName
From interface com.google.gwt.user.client.ui.IsWidget
From interface com.google.gwt.user.client.ui.SourcesChangeEvents
From interface com.google.gwt.user.client.ui.SourcesClickEvents
From interface com.google.gwt.user.client.ui.SourcesFocusEvents
From interface com.google.gwt.user.client.ui.SourcesKeyboardEvents
From interface com.google.gwt.user.client.ui.SourcesMouseEvents

Fields

public static final DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR

Public Constructors

public ListBox ()

Creates an empty list box in single selection mode.

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

Protected Constructors

protected ListBox (Element element)

This constructor may be used by subclasses to explicitly use an existing element. This element must be a <select> element.

Parameters
element the element to be used

Public Methods

public HandlerRegistration addChangeHandler (ChangeHandler handler)

Adds a ChangeEvent handler.

Parameters
handler the change handler
Returns

public void addChangeListener (ChangeListener listener)

This method is deprecated.
Use addChangeHandler(ChangeHandler) instead

Adds a listener interface to receive change events.

Parameters
listener the listener interface to add

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

public void addItem (String item, HasDirection.Direction dir)

Adds an item to the list box, specifying its direction. This method has the same effect as

 addItem(item, dir, item)
 

Parameters
item the text of the item to be added
dir the item's direction

public void addItem (String item, HasDirection.Direction dir, String value)

Adds an item to the list box, specifying its direction and an initial value for the item.

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

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

public void clear ()

Removes all items from the list box.

public DirectionEstimator getDirectionEstimator ()

Returns the DirectionEstimator object.

public int getItemCount ()

Gets the number of items present in the list box.

Returns
  • the number of items

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
Returns
  • the text associated with the item
Throws
IndexOutOfBoundsException if the index is out of range

public String getName ()

Gets the widget's name.

Returns
  • the widget's name

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

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
Returns
  • the item's associated value
Throws
IndexOutOfBoundsException if the index is out of range

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

public void insertItem (String item, HasDirection.Direction dir, String value, int index)

Inserts an item into the list box, specifying its direction and 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
dir the item's direction. If null, the item is displayed in the widget's overall direction, or, if a direction estimator has been set, in the item's estimated direction.
value the item's value, to be submitted if it is part of a FormPanel.
index the index at which to insert it

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

public void insertItem (String item, HasDirection.Direction dir, int index)

Inserts an item into the list box, specifying its direction. Has the same effect as

 insertItem(item, dir, item, index)
 

Parameters
item the text of the item to be inserted
dir the item's direction
index the index at which to insert it

public void insertItem (String item, String value, int index)

Inserts an item into the list box, specifying an initial value for the item. Has the same effect as

 insertItem(item, null, value, index)
 

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

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
IndexOutOfBoundsException if the index is out of range

public boolean isMultipleSelect ()

Gets whether this list allows multiple selection.

Returns
  • true if multiple selection is allowed

public void removeChangeListener (ChangeListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by addChangeHandler(ChangeHandler) instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void removeItem (int index)

Removes the item at the specified index.

Parameters
index the index of the item to be removed
Throws
IndexOutOfBoundsException if the index is out of range

public void setDirectionEstimator (DirectionEstimator directionEstimator)

Sets the DirectionEstimator object. Note: this does not affect the direction of already-existing content.

Parameters
directionEstimator The {code DirectionEstimator} to be set. null means turning off direction estimation.

public void setDirectionEstimator (boolean enabled)

Toggles on / off direction estimation. See note at setDirectionEstimator(com.google.gwt.i18n.shared.DirectionEstimator)

Parameters
enabled Whether to enable direction estimation. If true, sets the DirectionEstimator object to a default DirectionEstimator.

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 onChange(ChangeEvent) event to be fired.

Parameters
index the index of the item to be selected or unselected
selected true to select the item
Throws
IndexOutOfBoundsException if the index is out of range

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
Throws
IndexOutOfBoundsException if the index is out of range

public void setItemText (int index, String text, HasDirection.Direction dir)

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
dir the item's direction.
Throws
IndexOutOfBoundsException if the index is out of range

public void setMultipleSelect (boolean multiple)

This method is deprecated.
use ListBox(boolean) instead

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

public void setName (String name)

Sets the widget's name.

Parameters
name the widget's new name

public void setSelectedIndex (int index)

Sets the currently selected index. After calling this method, only the specified item in the list will remain selected. For a ListBox with multiple selection enabled, see setItemSelected(int, boolean) to select multiple items at a time.

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

Parameters
index the index of the item to be selected

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
Throws
IndexOutOfBoundsException if the index is out of range

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

public static ListBox wrap (Element element)

Creates a ListBox widget that wraps an existing <select> element. This element must already be attached to the document. If the element is removed from the document, you must call detachNow(Widget).

Parameters
element the element to be wrapped
Returns
  • list box

Protected Methods

protected void onEnsureDebugId (String baseID)

Affected Elements:

  • -item# = the option at the specified index.

Parameters
baseID the base ID used by the main element