|
GWT 2.7.0 | |||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||
java.lang.Objectcom.google.gwt.user.client.ui.UIObject
com.google.gwt.user.client.ui.Widget
com.google.gwt.user.client.ui.Composite
com.google.gwt.user.client.ui.SuggestBox
public class SuggestBox
A 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| Nested Class Summary | |
|---|---|
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. |
| 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 | |
|---|---|
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. |
|
| Method Summary | |
|---|---|
void |
addChangeListener(ChangeListener listener)
Deprecated. use getTextBox()().addChangeHandler instead |
void |
addClickListener(ClickListener listener)
Deprecated. use getTextBox()().addClickHandler instead |
void |
addEventHandler(SuggestionHandler handler)
Deprecated. use addSelectionHandler(com.google.gwt.event.logical.shared.SelectionHandler instead. |
void |
addFocusListener(FocusListener listener)
Deprecated. use getTextBox()().addFocusHandler/addBlurHandler()
instead |
void |
addKeyboardListener(KeyboardListener listener)
Deprecated. Use 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) instead |
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. use SuggestBox.DefaultSuggestionDisplay.hideSuggestions() instead |
boolean |
isAnimationEnabled()
Deprecated. use SuggestBox.DefaultSuggestionDisplay.isAnimationEnabled()
instead |
boolean |
isAutoSelectEnabled()
Returns whether or not the first suggestion will be automatically selected. |
boolean |
isEnabled()
Gets whether this widget is enabled. |
boolean |
isSuggestionListShowing()
Deprecated. use SuggestBox.DefaultSuggestionDisplay.isSuggestionListShowing() |
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 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. use SuggestBox.DefaultSuggestionDisplay.setAnimationEnabled(boolean)
instead |
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. use SuggestBox.DefaultSuggestionDisplay.setPopupStyleName(String)
instead |
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. |
| Methods inherited from class com.google.gwt.user.client.ui.Composite |
|---|
claimElement, getWidget, initializeClaimedElement, initWidget, isAttached, onAttach, onBrowserEvent, onDetach, render, render, resolvePotentialElement, setWidget |
| 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, isOrWasAttached, 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, 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 |
| Constructor Detail |
|---|
public SuggestBox()
SuggestBox. Creates a
MultiWordSuggestOracle and TextBox to use with this
SuggestBox.
public SuggestBox(SuggestOracle oracle)
SuggestBox. Creates a TextBox to use with
this SuggestBox.
oracle - the oracle for this SuggestBox
public 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 widget
public 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 suggestions| Method Detail |
|---|
public 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 instead
addChangeListener in interface SourcesChangeEventslistener - the listener interface to add@Deprecated public void addClickListener(ClickListener listener)
getTextBox()().addClickHandler instead
addClickListener in interface SourcesClickEventslistener - the listener interface to add@Deprecated public void addEventHandler(SuggestionHandler handler)
addSelectionHandler(com.google.gwt.event.logical.shared.SelectionHandler) instead.
addEventHandler in interface FiresSuggestionEventshandler - the handler to add@Deprecated public void addFocusListener(FocusListener listener)
getTextBox()().addFocusHandler/addBlurHandler()
instead
addFocusListener 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) instead
SourcesKeyboardEvents
addKeyboardListener in interface SourcesKeyboardEventslistener - the listener interface to addpublic HandlerRegistration addKeyDownHandler(KeyDownHandler handler)
HasKeyDownHandlersKeyDownEvent handler.
addKeyDownHandler in interface HasKeyDownHandlershandler - the key down handler
HandlerRegistration used to remove this handlerpublic HandlerRegistration addKeyPressHandler(KeyPressHandler handler)
HasKeyPressHandlersKeyPressEvent handler.
addKeyPressHandler in interface HasKeyPressHandlershandler - the key press handler
HandlerRegistration used to remove this handlerpublic HandlerRegistration addKeyUpHandler(KeyUpHandler handler)
HasKeyUpHandlersKeyUpEvent handler.
addKeyUpHandler in interface HasKeyUpHandlershandler - the key up handler
HandlerRegistration used to remove this handlerpublic HandlerRegistration addSelectionHandler(SelectionHandler<SuggestOracle.Suggestion> handler)
HasSelectionHandlersSelectionEvent handler.
addSelectionHandler in interface HasSelectionHandlers<SuggestOracle.Suggestion>handler - the handler
public HandlerRegistration addValueChangeHandler(ValueChangeHandler<java.lang.String> handler)
HasValueChangeHandlersValueChangeEvent handler.
addValueChangeHandler in interface HasValueChangeHandlers<java.lang.String>handler - the handler
public 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()
Focusable
getTabIndex in interface Focusablepublic java.lang.String getText()
HasText
getText in interface 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()
HasValue
getValue 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() instead
SuggestBox.DefaultSuggestionDisplay. Note that
this method is a no-op unless the SuggestBox.DefaultSuggestionDisplay is used.
@Deprecated public boolean isAnimationEnabled()
SuggestBox.DefaultSuggestionDisplay.isAnimationEnabled()
instead
SuggestBox.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 enabled@Deprecated public boolean isSuggestionListShowing()
SuggestBox.DefaultSuggestionDisplay.isSuggestionListShowing()
SuggestBox.DefaultSuggestionDisplay is showing. Note that this
method only has a meaningful return value when the
SuggestBox.DefaultSuggestionDisplay is used.
public void refreshSuggestionList()
@Deprecated public void removeChangeListener(ChangeListener listener)
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addChangeHandler
instead
SourcesChangeEvents
removeChangeListener in interface SourcesChangeEventslistener - the listener interface to remove@Deprecated public void removeClickListener(ClickListener listener)
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addClickHandler
instead
SourcesClickEvents
removeClickListener 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) instead
FiresSuggestionEvents
removeEventHandler in interface FiresSuggestionEventshandler - the handler to remove@Deprecated public void removeFocusListener(FocusListener listener)
HandlerRegistration.removeHandler() method on the
object returned by getTextBox()().addFocusListener
instead
SourcesFocusEvents
removeFocusListener 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 instead
SourcesKeyboardEvents
removeKeyboardListener in interface SourcesKeyboardEventslistener - the listener interface to removepublic void setAccessKey(char key)
Focusable
setAccessKey in interface Focusablekey - the widget's access key@Deprecated public void setAnimationEnabled(boolean enable)
SuggestBox.DefaultSuggestionDisplay.setAnimationEnabled(boolean)
instead
SuggestBox.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)
Focusable
setFocus in interface Focusablefocused - whether this widget should take focus or release itpublic 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)
instead
SuggestBox.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)
HasText
setText in interface HasTexttext - the object's new textpublic 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.
setValue in interface HasValue<java.lang.String>value - the object's new valuefireEvents - fire events if true and value is newpublic 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)
|
GWT 2.7.0 | |||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||