Package 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 bysetDirectionEstimator(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 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
-
Method Summary
Modifier and TypeMethodDescriptionaddChangeHandler
(ChangeHandler handler) Adds aChangeEvent
handler.void
addChangeListener
(ChangeListener listener) Deprecated.void
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
Adds an item to the list box, specifying an initial value for the item.void
clear()
Removes all items from the list box.Returns theDirectionEstimator
object.int
Gets the number of items present in the list box.getItemText
(int index) Gets the text associated with the item at the specified index.getName()
Gets the widget's name.protected String
getOptionText
(OptionElement option) Retrieves the text of an option element.int
Gets the currently-selected item.Gets the text for currently selected item.Gets the value for currently selected item.getValue
(int index) Gets the value associated with the item at a given index.int
Gets the number of items that are visible.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, 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, 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
Gets whether this list allows multiple selection.protected void
onEnsureDebugId
(String baseID) Affected Elements: -item# = the option at the specified index.void
removeChangeListener
(ChangeListener listener) Deprecated.Use theHandlerRegistration.removeHandler()
method on the object returned byaddChangeHandler(com.google.gwt.event.dom.client.ChangeHandler)
insteadvoid
removeItem
(int index) Removes the item at the specified index.void
setDirectionEstimator
(boolean enabled) Toggles on / off direction estimation.void
setDirectionEstimator
(DirectionEstimator directionEstimator) Sets theDirectionEstimator
object.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) Sets whether this list allows multiple selections.void
Sets the widget's name.protected void
setOptionText
(OptionElement option, String text, HasDirection.Direction dir) Sets the text of an option element.void
setSelectedIndex
(int index) Sets the currently selected index.void
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
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 Details
-
DEFAULT_DIRECTION_ESTIMATOR
-
-
Constructor Details
-
ListBox
public ListBox()Creates an empty list box in single selection mode. -
ListBox
Deprecated.usesetMultipleSelect(boolean)
instead.Creates an empty list box.- Parameters:
isMultipleSelect
- specifies if multiple selection is enabled
-
ListBox
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 Details
-
wrap
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 callWidget.removeFromParent()
.- Parameters:
element
- the element to be wrapped- Returns:
- list box
-
addChangeHandler
Description copied from interface:HasChangeHandlers
Adds aChangeEvent
handler.- Specified by:
addChangeHandler
in interfaceHasChangeHandlers
- Parameters:
handler
- the change handler- Returns:
HandlerRegistration
used to remove this handler
-
addChangeListener
Deprecated.Description copied from interface:SourcesChangeEvents
Adds a listener interface to receive change events.- Specified by:
addChangeListener
in interfaceSourcesChangeEvents
- Parameters:
listener
- the listener interface to add
-
addItem
Adds an item to the list box. This method has the same effect asaddItem(item, item)
- Parameters:
item
- the text of the item to be added
-
addItem
Adds an item to the list box, specifying its direction. This method has the same effect asaddItem(item, dir, item)
- Parameters:
item
- the text of the item to be addeddir
- the item's direction
-
addItem
Adds an item to the list box, specifying an initial value for the item.- Parameters:
item
- the text of the item to be addedvalue
- the item's value, to be submitted if it is part of aFormPanel
; cannot benull
-
addItem
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 addeddir
- the item's directionvalue
- the item's value, to be submitted if it is part of aFormPanel
; cannot benull
-
clear
public void clear()Removes all items from the list box. -
getDirectionEstimator
Description copied from interface:HasDirectionEstimator
Returns theDirectionEstimator
object.- Specified by:
getDirectionEstimator
in interfaceHasDirectionEstimator
-
getItemCount
public int getItemCount()Gets the number of items present in the list box.- Returns:
- the number of items
-
getItemText
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
-
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
Description copied from interface:HasName
Gets 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
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
-
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
Inserts an item into the list box. Has the same effect asinsertItem(item, item, index)
- Parameters:
item
- the text of the item to be insertedindex
- the index at which to insert it
-
insertItem
Inserts an item into the list box, specifying its direction. Has the same effect asinsertItem(item, dir, item, index)
- Parameters:
item
- the text of the item to be inserteddir
- the item's directionindex
- the index at which to insert it
-
insertItem
Inserts an item into the list box, specifying an initial value for the item. Has the same effect asinsertItem(item, null, value, index)
- Parameters:
item
- the text of the item to be insertedvalue
- the item's value, to be submitted if it is part of aFormPanel
.index
- the index at which to insert it
-
insertItem
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 inserteddir
- the item's direction. Ifnull
, 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 aFormPanel
.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:
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.Use theHandlerRegistration.removeHandler()
method on the object returned byaddChangeHandler(com.google.gwt.event.dom.client.ChangeHandler)
insteadDescription copied from interface:SourcesChangeEvents
Removes a previously added listener interface.- Specified by:
removeChangeListener
in interfaceSourcesChangeEvents
- 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:
IndexOutOfBoundsException
- if the index is out of range
-
setDirectionEstimator
public void setDirectionEstimator(boolean enabled) Toggles on / off direction estimation. See note atsetDirectionEstimator(com.google.gwt.i18n.shared.DirectionEstimator)
.- Specified by:
setDirectionEstimator
in interfaceHasDirectionEstimator
- Parameters:
enabled
- Whether to enable direction estimation. Iftrue
, sets theDirectionEstimator
object to a defaultDirectionEstimator
.
-
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 unselectedselected
-true
to select the item- Throws:
IndexOutOfBoundsException
- if the index is out of range
-
setItemText
Sets the text associated with the item at a given index.- Parameters:
index
- the index of the item to be settext
- the item's new text- Throws:
IndexOutOfBoundsException
- if the index is out of range
-
setItemText
Sets the text associated with the item at a given index.- Parameters:
index
- the index of the item to be settext
- the item's new textdir
- the item's direction.- Throws:
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
Description copied from interface:HasName
Sets the widget's 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, seesetItemSelected(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
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 aFormPanel
.- Parameters:
index
- the index of the item to be setvalue
- the item's new value; cannot benull
- Throws:
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
Retrieves the text of an option element. If the text was set bysetOptionText(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
Affected Elements:- -item# = the option at the specified index.
- Overrides:
onEnsureDebugId
in classUIObject
- Parameters:
baseID
- the base ID used by the main element- See Also:
-
setOptionText
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'sBIDI_ATTR_NAME
custom attribute.- Parameters:
option
- an option elementtext
- text to be set to the elementdir
- the text's direction. Ifnull
and direction estimation is turned off, direction is ignored.
-
setMultipleSelect(boolean)
instead.