public class SuggestBox extends Composite implements HasText, HasFocus, HasAnimation, HasEnabled, SourcesClickEvents, SourcesChangeEvents, SourcesKeyboardEvents, FiresSuggestionEvents, HasAllKeyHandlers, HasValue<java.lang.String>, HasSelectionHandlers<SuggestOracle.Suggestion>, IsEditor<LeafValueEditor<java.lang.String>>
SuggestBox is a text box or text area which displays a
pre-configured set of selections that match the user's input.
Each SuggestBox is associated with a single SuggestOracle.
The SuggestOracle is used to provide a set of selections given a
specific query string.
By default, the SuggestBox uses a MultiWordSuggestOracle as
its oracle. Below we show how a MultiWordSuggestOracle can be
configured:
MultiWordSuggestOracle oracle = new MultiWordSuggestOracle();
oracle.add("Cat");
oracle.add("Dog");
oracle.add("Horse");
oracle.add("Canary");
SuggestBox box = new SuggestBox(oracle);
Using the example above, if the user types "C" into the text widget, the
oracle will configure the suggestions with the "Cat" and "Canary"
suggestions. Specifically, whenever the user types a key into the text
widget, the value is submitted to the MultiWordSuggestOracle.
Note that there is no method to retrieve the "currently selected suggestion"
in a SuggestBox, because there are points in time where the currently
selected suggestion is not defined. For example, if the user types in some
text that does not match any of the SuggestBox's suggestions, then the
SuggestBox will not have a currently selected suggestion. It is more useful
to know when a suggestion has been chosen from the SuggestBox's list of
suggestions. A SuggestBox fires SelectionEvents
whenever a suggestion is chosen, and handlers for these events can be added
using the addSelectionHandler(SelectionHandler) method.
SuggestOracle,
MultiWordSuggestOracle,
ValueBoxBase| Modifier and Type | Class and Description |
|---|---|
static class |
SuggestBox.DefaultSuggestionDisplay
The default implementation of
SuggestBox.SuggestionDisplay displays
suggestions in a PopupPanel beneath the SuggestBox. |
static interface |
SuggestBox.SuggestionCallback
The callback used when a user selects a
SuggestOracle.Suggestion. |
static class |
SuggestBox.SuggestionDisplay
Used to display suggestions to the user.
|
UIObject.DebugIdImpl, UIObject.DebugIdImplEnabledeventsToSinkDEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR| Constructor and Description |
|---|
SuggestBox()
Constructor for
SuggestBox. |
SuggestBox(SuggestOracle oracle)
Constructor for
SuggestBox. |
SuggestBox(SuggestOracle oracle,
ValueBoxBase<java.lang.String> box)
Constructor for
SuggestBox. |
SuggestBox(SuggestOracle oracle,
ValueBoxBase<java.lang.String> box,
SuggestBox.SuggestionDisplay suggestDisplay)
Constructor for
SuggestBox. |
| Modifier and Type | Method and Description |
|---|---|
void |
addChangeListener(ChangeListener listener)
Deprecated.
use
getTextBox()().addChangeHandler instead |
void |
addClickListener(ClickListener listener)
Deprecated.
use
getTextBox()().addClickHandler instead |
void |
addEventHandler(SuggestionHandler handler)
|
void |
addFocusListener(FocusListener listener)
Deprecated.
use
getTextBox()().addFocusHandler/addBlurHandler()
instead |
void |
addKeyboardListener(KeyboardListener listener)
|
HandlerRegistration |
addKeyDownHandler(KeyDownHandler handler)
Adds a
KeyDownEvent handler. |
HandlerRegistration |
addKeyPressHandler(KeyPressHandler handler)
Adds a
KeyPressEvent handler. |
HandlerRegistration |
addKeyUpHandler(KeyUpHandler handler)
Adds a
KeyUpEvent handler. |
HandlerRegistration |
addSelectionHandler(SelectionHandler<SuggestOracle.Suggestion> handler)
Adds a
SelectionEvent handler. |
HandlerRegistration |
addValueChangeHandler(ValueChangeHandler<java.lang.String> handler)
Adds a
ValueChangeEvent handler. |
LeafValueEditor<java.lang.String> |
asEditor()
Returns a
TakesValueEditor backed by the SuggestBox. |
int |
getLimit()
Gets the limit for the number of suggestions that should be displayed for
this box.
|
SuggestBox.SuggestionDisplay |
getSuggestionDisplay()
Get the
SuggestBox.SuggestionDisplay used to display suggestions. |
SuggestOracle |
getSuggestOracle()
Gets the suggest box's
SuggestOracle. |
int |
getTabIndex()
Gets the widget's position in the tab index.
|
java.lang.String |
getText()
Gets this object's text.
|
TextBoxBase |
getTextBox()
Deprecated.
in favour of getValueBox
|
java.lang.String |
getValue()
Gets this object's value.
|
ValueBoxBase<java.lang.String> |
getValueBox()
Get the ValueBoxBase associated with this suggest box.
|
void |
hideSuggestionList()
Deprecated.
|
boolean |
isAnimationEnabled()
Deprecated.
|
boolean |
isAutoSelectEnabled()
Returns whether or not the first suggestion will be automatically selected.
|
boolean |
isEnabled()
Gets whether this widget is enabled.
|
boolean |
isSuggestionListShowing()
Check if the
SuggestBox.SuggestionDisplay is showing. |
protected void |
onEnsureDebugId(java.lang.String baseID)
Called when the user sets the id using the
UIObject.ensureDebugId(String)
method. |
void |
refreshSuggestionList()
Refreshes the current list of suggestions.
|
void |
removeChangeListener(ChangeListener listener)
Deprecated.
Use the
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addChangeHandler
instead |
void |
removeClickListener(ClickListener listener)
Deprecated.
Use the
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addClickHandler
instead |
void |
removeEventHandler(SuggestionHandler handler)
Deprecated.
Use the
HandlerRegistration.removeHandler() method no the
object returned by addSelectionHandler(com.google.gwt.event.logical.shared.SelectionHandler<com.google.gwt.user.client.ui.SuggestOracle.Suggestion>) instead |
void |
removeFocusListener(FocusListener listener)
Deprecated.
Use the
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addFocusListener
instead |
void |
removeKeyboardListener(KeyboardListener listener)
Deprecated.
Use the
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().add*Handler instead |
void |
setAccessKey(char key)
Sets the widget's 'access key'.
|
void |
setAnimationEnabled(boolean enable)
Deprecated.
|
void |
setAutoSelectEnabled(boolean selectsFirstItem)
Turns on or off the behavior that automatically selects the first suggested
item.
|
void |
setEnabled(boolean enabled)
Sets whether this widget is enabled.
|
void |
setFocus(boolean focused)
Explicitly focus/unfocus this widget.
|
void |
setLimit(int limit)
Sets the limit to the number of suggestions the oracle should provide.
|
void |
setPopupStyleName(java.lang.String style)
Deprecated.
|
void |
setTabIndex(int index)
Sets the widget's position in the tab index.
|
void |
setText(java.lang.String text)
Sets this object's text.
|
void |
setValue(java.lang.String newValue)
Sets this object's value without firing any events.
|
void |
setValue(java.lang.String value,
boolean fireEvents)
Sets this object's value.
|
void |
showSuggestionList()
Show the current list of suggestions.
|
(package private) void |
showSuggestions(java.lang.String query) |
static SuggestBox |
wrap(SuggestOracle oracle,
Element element)
Creates a
SuggestBox widget that wraps an existing <input
type='text'> element. |
claimElement, getWidget, initializeClaimedElement, initWidget, isAttached, onAttach, onBrowserEvent, onDetach, render, render, resolvePotentialElement, setWidgetaddAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isOrWasAttached, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents, unsinkEventsaddStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toStringclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitfireEventpublic SuggestBox()
SuggestBox. Creates a
MultiWordSuggestOracle and TextBox to use with this
SuggestBox.public SuggestBox(SuggestOracle oracle)
oracle - the oracle for this SuggestBoxpublic SuggestBox(SuggestOracle oracle, ValueBoxBase<java.lang.String> box)
SuggestBox. The text box will be removed from it's
current location and wrapped by the SuggestBox.oracle - supplies suggestions based upon the current contents of the
text widgetbox - the text widgetpublic SuggestBox(SuggestOracle oracle, ValueBoxBase<java.lang.String> box, SuggestBox.SuggestionDisplay suggestDisplay)
SuggestBox. The text box will be removed from it's
current location and wrapped by the SuggestBox.oracle - supplies suggestions based upon the current contents of the
text widgetbox - the text widgetsuggestDisplay - the class used to display suggestionspublic static SuggestBox wrap(SuggestOracle oracle, Element element)
SuggestBox widget that wraps an existing <input
type='text'> element.
This element must already be attached to the document. If the element is
removed from the document, you must call
RootPanel.detachNow(Widget).oracle - the suggest box oracle to useelement - the element to be wrapped@Deprecated public void addChangeListener(ChangeListener listener)
getTextBox()().addChangeHandler insteadaddChangeListener in interface SourcesChangeEventslistener - the listener interface to add@Deprecated public void addClickListener(ClickListener listener)
getTextBox()().addClickHandler insteadaddClickListener in interface SourcesClickEventslistener - the listener interface to add@Deprecated public void addEventHandler(SuggestionHandler handler)
addSelectionHandler(com.google.gwt.event.logical.shared.SelectionHandler<com.google.gwt.user.client.ui.SuggestOracle.Suggestion>) instead.addEventHandler in interface FiresSuggestionEventshandler - the handler to add@Deprecated public void addFocusListener(FocusListener listener)
getTextBox()().addFocusHandler/addBlurHandler()
insteadaddFocusListener in interface SourcesFocusEventslistener - the listener interface to add@Deprecated public void addKeyboardListener(KeyboardListener listener)
addKeyDownHandler(com.google.gwt.event.dom.client.KeyDownHandler), addKeyUpHandler(com.google.gwt.event.dom.client.KeyUpHandler) and
addKeyPressHandler(com.google.gwt.event.dom.client.KeyPressHandler) insteadSourcesKeyboardEventsaddKeyboardListener in interface SourcesKeyboardEventslistener - the listener interface to addpublic HandlerRegistration addKeyDownHandler(KeyDownHandler handler)
HasKeyDownHandlersKeyDownEvent handler.addKeyDownHandler in interface HasKeyDownHandlershandler - the key down handlerHandlerRegistration used to remove this handlerpublic HandlerRegistration addKeyPressHandler(KeyPressHandler handler)
HasKeyPressHandlersKeyPressEvent handler.addKeyPressHandler in interface HasKeyPressHandlershandler - the key press handlerHandlerRegistration used to remove this handlerpublic HandlerRegistration addKeyUpHandler(KeyUpHandler handler)
HasKeyUpHandlersKeyUpEvent handler.addKeyUpHandler in interface HasKeyUpHandlershandler - the key up handlerHandlerRegistration used to remove this handlerpublic HandlerRegistration addSelectionHandler(SelectionHandler<SuggestOracle.Suggestion> handler)
HasSelectionHandlersSelectionEvent handler.addSelectionHandler in interface HasSelectionHandlers<SuggestOracle.Suggestion>handler - the handlerpublic HandlerRegistration addValueChangeHandler(ValueChangeHandler<java.lang.String> handler)
HasValueChangeHandlersValueChangeEvent handler.addValueChangeHandler in interface HasValueChangeHandlers<java.lang.String>handler - the handlerpublic LeafValueEditor<java.lang.String> asEditor()
TakesValueEditor backed by the SuggestBox.asEditor in interface IsEditor<LeafValueEditor<java.lang.String>>Editor of type Epublic int getLimit()
SuggestOracle to enforce this
limit.public SuggestBox.SuggestionDisplay getSuggestionDisplay()
SuggestBox.SuggestionDisplay used to display suggestions.SuggestBox.SuggestionDisplaypublic SuggestOracle getSuggestOracle()
SuggestOracle.SuggestOraclepublic int getTabIndex()
FocusablegetTabIndex in interface Focusablepublic java.lang.String getText()
HasText@Deprecated public TextBoxBase getTextBox()
java.lang.ClassCastException - if this suggest box's value box is not an
instance of TextBoxBasepublic java.lang.String getValue()
HasValuegetValue in interface TakesValue<java.lang.String>getValue in interface HasValue<java.lang.String>TakesValue.setValue(V)public ValueBoxBase<java.lang.String> getValueBox()
@Deprecated public void hideSuggestionList()
SuggestBox.DefaultSuggestionDisplay.hideSuggestions() insteadSuggestBox.DefaultSuggestionDisplay. Note that
this method is a no-op unless the SuggestBox.DefaultSuggestionDisplay is used.@Deprecated public boolean isAnimationEnabled()
SuggestBox.DefaultSuggestionDisplay.isAnimationEnabled()
insteadSuggestBox.DefaultSuggestionDisplay has animations
enabled. Note that this method only has a meaningful return value when the
SuggestBox.DefaultSuggestionDisplay is used.isAnimationEnabled in interface HasAnimationpublic boolean isAutoSelectEnabled()
public boolean isEnabled()
isEnabled in interface HasEnabledtrue if the widget is enabledpublic boolean isSuggestionListShowing()
SuggestBox.SuggestionDisplay is showing.public void refreshSuggestionList()
@Deprecated public void removeChangeListener(ChangeListener listener)
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addChangeHandler
insteadSourcesChangeEventsremoveChangeListener in interface SourcesChangeEventslistener - the listener interface to remove@Deprecated public void removeClickListener(ClickListener listener)
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addClickHandler
insteadSourcesClickEventsremoveClickListener in interface SourcesClickEventslistener - the listener interface to remove@Deprecated public void removeEventHandler(SuggestionHandler handler)
HandlerRegistration.removeHandler() method no the
object returned by addSelectionHandler(com.google.gwt.event.logical.shared.SelectionHandler<com.google.gwt.user.client.ui.SuggestOracle.Suggestion>) insteadFiresSuggestionEventsremoveEventHandler in interface FiresSuggestionEventshandler - the handler to remove@Deprecated public void removeFocusListener(FocusListener listener)
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addFocusListener
insteadSourcesFocusEventsremoveFocusListener in interface SourcesFocusEventslistener - the listener interface to remove@Deprecated public void removeKeyboardListener(KeyboardListener listener)
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().add*Handler insteadSourcesKeyboardEventsremoveKeyboardListener in interface SourcesKeyboardEventslistener - the listener interface to removepublic void setAccessKey(char key)
FocusablesetAccessKey in interface Focusablekey - the widget's access key@Deprecated public void setAnimationEnabled(boolean enable)
SuggestBox.DefaultSuggestionDisplay.setAnimationEnabled(boolean)
insteadSuggestBox.DefaultSuggestionDisplay. Note
that this method is a no-op unless the SuggestBox.DefaultSuggestionDisplay is
used.setAnimationEnabled in interface HasAnimationenable - true to enable, false to disablepublic void setAutoSelectEnabled(boolean selectsFirstItem)
selectsFirstItem - Whether or not to automatically select the first
suggestionpublic void setEnabled(boolean enabled)
setEnabled in interface HasEnabledenabled - true to enable the widget, false
to disable itpublic void setFocus(boolean focused)
FocusableGWTTestCase#delayTestFinish for more information on how to do this.public void setLimit(int limit)
limit - the limit to the number of suggestions provided@Deprecated public void setPopupStyleName(java.lang.String style)
SuggestBox.DefaultSuggestionDisplay.setPopupStyleName(String)
insteadSuggestBox.DefaultSuggestionDisplay. Note that this method is a no-op unless
the SuggestBox.DefaultSuggestionDisplay is used.style - the new primary style nameUIObject.setStyleName(String)public void setTabIndex(int index)
Focusable-1 will cause this widget to
be removed from the tab order.setTabIndex in interface Focusableindex - the widget's tab indexpublic void setText(java.lang.String text)
HasTextpublic void setValue(java.lang.String newValue)
HasValueIt is acceptable to fail assertions or throw (documented) unchecked exceptions in response to bad values.
Widgets must accept null as a valid value. By convention, setting a widget to
null clears value, calling getValue() on a cleared widget returns null. Widgets
that can not be cleared (e.g. CheckBox) must find another valid meaning
for null input.
setValue in interface TakesValue<java.lang.String>setValue in interface HasValue<java.lang.String>newValue - the object's new valueTakesValue.getValue()public void setValue(java.lang.String value,
boolean fireEvents)
HasValueValueChangeEvent when
fireEvents is true and the new value does not equal the existing value.
It is acceptable to fail assertions or throw (documented) unchecked exceptions in response to bad values.
public void showSuggestionList()
protected void onEnsureDebugId(java.lang.String baseID)
UIObjectUIObject.ensureDebugId(String)
method. Subclasses of UIObject can override this method to add IDs
to their sub elements. If a subclass does override this method, it should
list the IDs (relative to the base ID), that will be applied to each sub
Element with a short description. For example:
<inherits name="com.google.gwt.user.Debug"/>
onEnsureDebugId in class UIObjectbaseID - the base ID used by the main elementvoid showSuggestions(java.lang.String query)