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

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

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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `ListBox()` Creates an empty list box in single selection mode.
    `` | `ListBox(boolean isMultipleSelect)` Creates an empty list box.
    `protected` | `ListBox(Element element)` This constructor may be used by subclasses to explicitly use an existing element.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `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)` Deprecated. use `ListBox(boolean)` instead
    `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`

    - ### 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, unsinkEvents`

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

          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

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

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

          @Deprecated
          public void setMultipleSelect(boolean multiple)

      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

    - #### 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:
      - -item# = the option at the specified index.
      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.