Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

java.lang.Object
  extended by com.google.gwt.user.client.ui.UIObject
      extended by com.google.gwt.user.client.ui.Widget
          extended by com.google.gwt.user.client.ui.FocusWidget
              extended by com.google.gwt.user.client.ui.ListBox
All Implemented Interfaces:
HasAllDragAndDropHandlers, HasAllFocusHandlers, HasAllGestureHandlers, HasAllKeyHandlers, HasAllMouseHandlers, HasAllTouchHandlers, HasBlurHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragEndHandlers, HasDragEnterHandlers, HasDragHandlers, HasDragLeaveHandlers, HasDragOverHandlers, HasDragStartHandlers, HasDropHandlers, HasFocusHandlers, HasGestureChangeHandlers, HasGestureEndHandlers, HasGestureStartHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasTouchCancelHandlers, HasTouchEndHandlers, HasTouchMoveHandlers, HasTouchStartHandlers, HasAttachHandlers, HasHandlers, HasDirectionEstimator, EventListener, Focusable, HasEnabled, HasFocus, HasName, HasVisibility, IsWidget, SourcesChangeEvents, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents, SourcesMouseEvents
public class ListBox
extends FocusWidget
implements SourcesChangeEvents, HasChangeHandlers, HasName, HasDirectionEstimator

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

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

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>

Important usage note

Subclasses should neither read nor write option text directly from the option elements created by this class, since such text may need to be wrapped in Unicode bidi formatting characters. They can use the getOptionText and/or setOptionText methods for this purpose instead.

Nested Class Summary
 
Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject
UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled
 
Field Summary
static DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR
           
 
Fields inherited from class com.google.gwt.user.client.ui.Widget
eventsToSink
 
Fields inherited from class com.google.gwt.user.client.ui.UIObject
DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR
 
Constructor Summary
  ListBox()
          Creates an empty list box in single selection mode.
  ListBox(boolean isMultipleSelect)
          Deprecated. use setMultipleSelect(boolean) instead.
protected ListBox(Element element)
          This constructor may be used by subclasses to explicitly use an existing element.
 
Method Summary
 HandlerRegistration addChangeHandler(ChangeHandler handler)
          Adds a ChangeEvent handler.
 void addChangeListener(ChangeListener listener)
          Deprecated. Use addChangeHandler(com.google.gwt.event.dom.client.ChangeHandler) instead
 void addItem(java.lang.String item)
          Adds an item to the list box.
 void addItem(java.lang.String item, HasDirection.Direction dir)
          Adds an item to the list box, specifying its direction.
 void addItem(java.lang.String item, HasDirection.Direction dir, java.lang.String value)
          Adds an item to the list box, specifying its direction and an initial value for the item.
 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.
 DirectionEstimator getDirectionEstimator()
          Returns the DirectionEstimator object.
 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.
protected  java.lang.String getOptionText(OptionElement option)
          Retrieves the text of an option element.
 int getSelectedIndex()
          Gets the currently-selected item.
 java.lang.String getSelectedItemText()
          Gets the text for currently selected item.
 java.lang.String getSelectedValue()
          Gets the value for 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, HasDirection.Direction dir, int index)
          Inserts an item into the list box, specifying its direction.
 void insertItem(java.lang.String item, HasDirection.Direction dir, java.lang.String value, int index)
          Inserts an item into the list box, specifying its direction and an initial value for the item.
 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.
protected  void onEnsureDebugId(java.lang.String baseID)
          Affected Elements: -item# = the option at the specified index.
 void removeChangeListener(ChangeListener listener)
          Deprecated. Use the HandlerRegistration.removeHandler() method on the object returned by addChangeHandler(com.google.gwt.event.dom.client.ChangeHandler) instead
 void removeItem(int index)
          Removes the item at the specified index.
 void setDirectionEstimator(boolean enabled)
          Toggles on / off direction estimation.
 void setDirectionEstimator(DirectionEstimator directionEstimator)
          Sets the DirectionEstimator object.
 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 setItemText(int index, java.lang.String text, HasDirection.Direction dir)
          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.
protected  void setOptionText(OptionElement option, java.lang.String text, HasDirection.Direction dir)
          Sets the text of an option element.
 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.
static ListBox wrap(Element element)
          Creates a ListBox widget that wraps an existing <select> element.
 
Methods inherited from class com.google.gwt.user.client.ui.FocusWidget
addBlurHandler, addClickHandler, addClickListener, addDoubleClickHandler, addDragEndHandler, addDragEnterHandler, addDragHandler, addDragLeaveHandler, addDragOverHandler, addDragStartHandler, addDropHandler, addFocusHandler, addFocusListener, addGestureChangeHandler, addGestureEndHandler, addGestureStartHandler, addKeyboardListener, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addMouseDownHandler, addMouseListener, addMouseMoveHandler, addMouseOutHandler, addMouseOverHandler, addMouseUpHandler, addMouseWheelHandler, addMouseWheelListener, addTouchCancelHandler, addTouchEndHandler, addTouchMoveHandler, addTouchStartHandler, getFocusImpl, getTabIndex, isEnabled, onAttach, removeClickListener, removeFocusListener, removeKeyboardListener, removeMouseListener, removeMouseWheelListener, setAccessKey, setEnabled, setFocus, setTabIndex
 
Methods inherited from class com.google.gwt.user.client.ui.Widget
addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onBrowserEvent, onDetach, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents, unsinkEvents
 
Methods inherited from class com.google.gwt.user.client.ui.UIObject
addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 

Field Detail

DEFAULT_DIRECTION_ESTIMATOR

public static final DirectionEstimator DEFAULT_DIRECTION_ESTIMATOR
Constructor Detail

ListBox

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

ListBox

@Deprecated
public ListBox(boolean isMultipleSelect)
Deprecated. use setMultipleSelect(boolean) instead.

Creates an empty list box.

Parameters:
isMultipleSelect - specifies if multiple selection is enabled

ListBox

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
Method Detail

wrap

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 RootPanel.detachNow(Widget).

Parameters:
element - the element to be wrapped
Returns:
list box

addChangeHandler

public HandlerRegistration addChangeHandler(ChangeHandler handler)
Description copied from interface: HasChangeHandlers
Adds a ChangeEvent handler.

Specified by:
addChangeHandler in interface HasChangeHandlers
Parameters:
handler - the change handler
Returns:
HandlerRegistration used to remove this handler

addChangeListener

@Deprecated
public void addChangeListener(ChangeListener listener)
Deprecated. Use addChangeHandler(com.google.gwt.event.dom.client.ChangeHandler) instead

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

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

addItem

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

clear

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

getDirectionEstimator

public DirectionEstimator getDirectionEstimator()
Description copied from interface: HasDirectionEstimator
Returns the DirectionEstimator object.

Specified by:
getDirectionEstimator in interface HasDirectionEstimator

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

getSelectedItemText

public java.lang.String getSelectedItemText()
Gets the text for currently selected item. If multiple items are selected, this method will return the text of the first selected item.

Returns:
the text for selected item, or null if none is selected

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

getSelectedValue

public java.lang.String getSelectedValue()
Gets the value for currently selected item. If multiple items are selected, this method will return the value of the first selected item.

Returns:
the value for selected item, or null if none is selected

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

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

insertItem

public void insertItem(java.lang.String item,
                       HasDirection.Direction dir,
                       java.lang.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

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

removeChangeListener

@Deprecated
public void removeChangeListener(ChangeListener listener)
Deprecated. Use the HandlerRegistration.removeHandler() method on the object returned by addChangeHandler(com.google.gwt.event.dom.client.ChangeHandler) instead

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

setDirectionEstimator

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

Specified by:
setDirectionEstimator in interface HasDirectionEstimator
Parameters:
enabled - Whether to enable direction estimation. If true, sets the DirectionEstimator object to a default DirectionEstimator.

setDirectionEstimator

public void setDirectionEstimator(DirectionEstimator directionEstimator)
Sets the DirectionEstimator object. Note: this does not affect the direction of already-existing content.

Specified by:
setDirectionEstimator in interface HasDirectionEstimator
Parameters:
directionEstimator - The DirectionEstimator to be set. null means turning off direction estimation.

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 ChangeHandler.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:
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

setItemText

public void setItemText(int index,
                        java.lang.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:
java.lang.IndexOutOfBoundsException - if the index is out of range

setMultipleSelect

public void setMultipleSelect(boolean multiple)
Sets whether this list allows multiple selections. NOTE: 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. 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 ChangeHandler.onChange(ChangeEvent) 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

getOptionText

protected java.lang.String getOptionText(OptionElement option)
Retrieves the text of an option element. If the text was set by setOptionText(com.google.gwt.dom.client.OptionElement, java.lang.String, com.google.gwt.i18n.client.HasDirection.Direction) and was wrapped with Unicode bidi formatting characters, also removes those additional formatting characters.

Parameters:
option - an option element
Returns:
the element's text

onEnsureDebugId

protected void onEnsureDebugId(java.lang.String baseID)
Affected Elements:

Overrides:
onEnsureDebugId in class UIObject
Parameters:
baseID - the base ID used by the main element
See Also:
UIObject.onEnsureDebugId(String)

setOptionText

protected void setOptionText(OptionElement option,
                             java.lang.String text,
                             HasDirection.Direction dir)
Sets the text of an option element. If the direction of the text is opposite to the page's direction, also wraps it with Unicode bidi formatting characters to prevent garbling, and indicates that this was done by setting the option's BIDI_ATTR_NAME custom attribute.

Parameters:
option - an option element
text - text to be set to the element
dir - the text's direction. If null and direction estimation is turned off, direction is ignored.
Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD