java.lang.Object
   ↳ com.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

Class Overview

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 SuggestionEvents whenever a suggestion is chosen, and handlers for these events can be added using the addValueChangeHandler(ValueChangeHandler) method.

CSS Style Rules

.gwt-SuggestBox
the suggest box itself
TODO(pdr): Add SafeHtml support to this and implementing classes.

See Also

Summary

Nested Classes
class SuggestBox.DefaultSuggestionDisplay

The default implementation of SuggestBox.SuggestionDisplay displays suggestions in a PopupPanel beneath the SuggestBox. 
interface SuggestBox.SuggestionCallback The callback used when a user selects a SuggestOracle.Suggestion. 
class SuggestBox.SuggestionDisplay Used to display suggestions to the user. 
[Expand]
Inherited Constants
From class com.google.gwt.user.client.ui.UIObject
Public Constructors
SuggestBox()
Constructor for SuggestBox.
SuggestBox(SuggestOracle oracle)
Constructor for SuggestBox.
SuggestBox(SuggestOracle oracle, TextBoxBase box)
Constructor for SuggestBox.
SuggestBox(SuggestOracle oracle, TextBoxBase box, SuggestBox.SuggestionDisplay suggestDisplay)
Constructor for SuggestBox.
Public Methods
void addChangeListener(ChangeListener listener)
This method is deprecated. use getTextBox()().addChangeHandler instead
void addClickListener(ClickListener listener)
This method is deprecated. use getTextBox()().addClickHandler instead
void addEventHandler(SuggestionHandler handler)
This method is deprecated. use addSelectionHandler(SelectionHandler) instead.
void addFocusListener(FocusListener listener)
This method is deprecated. use getTextBox()().addFocusHandler/addBlurHandler() 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.
void addKeyboardListener(KeyboardListener listener)
This method is deprecated. Use addKeyDownHandler(KeyDownHandler), addKeyUpHandler(KeyUpHandler) and addKeyPressHandler(KeyPressHandler) instead
HandlerRegistration addSelectionHandler(SelectionHandler<SuggestOracle.Suggestion> handler)
HandlerRegistration addValueChangeHandler(ValueChangeHandler<String> handler)
LeafValueEditor<String> asEditor()
Returns a TakesValueEditor backed by the DateBox.
int getLimit()
Gets the limit for the number of suggestions that should be displayed for this box.
SuggestOracle getSuggestOracle()
Gets the suggest box's SuggestOracle.
SuggestBox.SuggestionDisplay getSuggestionDisplay()
Get the SuggestBox.SuggestionDisplay used to display suggestions.
int getTabIndex()
Gets the widget's position in the tab index.
String getText()
Gets this object's text.
TextBoxBase getTextBox()
Get the text box associated with this suggest box.
String getValue()
Gets this object's value.
void hideSuggestionList()
This method is deprecated. use hideSuggestions() instead
boolean isAnimationEnabled()
This method is deprecated. use isAnimationEnabled() instead
boolean isAutoSelectEnabled()
Returns whether or not the first suggestion will be automatically selected.
boolean isSuggestionListShowing()
This method is deprecated. use isSuggestionListShowing()
void removeChangeListener(ChangeListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by getTextBox()().addChangeHandler instead
void removeClickListener(ClickListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by getTextBox()().addClickHandler instead
void removeEventHandler(SuggestionHandler handler)
This method is deprecated. Use the removeHandler() method no the object returned by addSelectionHandler(SelectionHandler) instead
void removeFocusListener(FocusListener listener)
This method is deprecated. Use the removeHandler() method on the object returned by getTextBox()().addFocusListener instead
void removeKeyboardListener(KeyboardListener listener)
This method is deprecated. Use the 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)
This method is deprecated. use setAnimationEnabled(boolean) instead
void setAutoSelectEnabled(boolean selectsFirstItem)
Turns on or off the behavior that automatically selects the first suggested item.
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(String style)
This method is deprecated. use setPopupStyleName(String) instead
void setTabIndex(int index)
Sets the widget's position in the tab index.
void setText(String text)
Sets this object's text.
void setValue(String value, boolean fireEvents)
void setValue(String newValue)
void showSuggestionList()
Show the current list of suggestions.
static SuggestBox wrap(SuggestOracle oracle, Element element)
Creates a SuggestBox widget that wraps an existing <input type='text'> element.
Protected Methods
void onEnsureDebugId(String baseID)
Called when the user sets the id using the ensureDebugId(String) method.
[Expand]
Inherited Methods
From class com.google.gwt.user.client.ui.Composite
From class com.google.gwt.user.client.ui.Widget
From class com.google.gwt.user.client.ui.UIObject
From class java.lang.Object
From interface com.google.gwt.editor.client.IsEditor
From interface com.google.gwt.event.dom.client.HasKeyDownHandlers
From interface com.google.gwt.event.dom.client.HasKeyPressHandlers
From interface com.google.gwt.event.dom.client.HasKeyUpHandlers
From interface com.google.gwt.event.logical.shared.HasAttachHandlers
From interface com.google.gwt.event.logical.shared.HasSelectionHandlers
From interface com.google.gwt.event.logical.shared.HasValueChangeHandlers
From interface com.google.gwt.event.shared.HasHandlers
From interface com.google.gwt.user.client.EventListener
From interface com.google.gwt.user.client.TakesValue
From interface com.google.gwt.user.client.ui.FiresSuggestionEvents
From interface com.google.gwt.user.client.ui.Focusable
From interface com.google.gwt.user.client.ui.HasAnimation
From interface com.google.gwt.user.client.ui.HasText
From interface com.google.gwt.user.client.ui.HasValue
From interface com.google.gwt.user.client.ui.IsWidget
From interface com.google.gwt.user.client.ui.SourcesChangeEvents
From interface com.google.gwt.user.client.ui.SourcesClickEvents
From interface com.google.gwt.user.client.ui.SourcesFocusEvents
From interface com.google.gwt.user.client.ui.SourcesKeyboardEvents

Public Constructors

public SuggestBox ()

Constructor for SuggestBox. Creates a MultiWordSuggestOracle and TextBox to use with this SuggestBox.

public SuggestBox (SuggestOracle oracle)

Constructor for SuggestBox. Creates a TextBox to use with this SuggestBox.

Parameters
oracle the oracle for this SuggestBox

public SuggestBox (SuggestOracle oracle, TextBoxBase box)

Constructor for SuggestBox. The text box will be removed from it's current location and wrapped by the SuggestBox.

Parameters
oracle supplies suggestions based upon the current contents of the text widget
box the text widget

public SuggestBox (SuggestOracle oracle, TextBoxBase box, SuggestBox.SuggestionDisplay suggestDisplay)

Constructor for SuggestBox. The text box will be removed from it's current location and wrapped by the SuggestBox.

Parameters
oracle supplies suggestions based upon the current contents of the text widget
box the text widget
suggestDisplay the class used to display suggestions

Public Methods

public void addChangeListener (ChangeListener listener)

This method is deprecated.
use getTextBox()().addChangeHandler instead

Adds a listener to receive change events on the SuggestBox's text box. The source Widget for these events will be the SuggestBox.

Parameters
listener the listener interface to add

public void addClickListener (ClickListener listener)

This method is deprecated.
use getTextBox()().addClickHandler instead

Adds a listener to receive click events on the SuggestBox's text box. The source Widget for these events will be the SuggestBox.

Parameters
listener the listener interface to add

public void addEventHandler (SuggestionHandler handler)

This method is deprecated.
use addSelectionHandler(SelectionHandler) instead.

Adds an event to this handler.

Parameters
handler the handler to add

public void addFocusListener (FocusListener listener)

This method is deprecated.
use getTextBox()().addFocusHandler/addBlurHandler() instead

Adds a listener to receive focus events on the SuggestBox's text box. The source Widget for these events will be the SuggestBox.

Parameters
listener the listener interface to add

public HandlerRegistration addKeyDownHandler (KeyDownHandler handler)

Adds a KeyDownEvent handler.

Parameters
handler the key down handler
Returns

public HandlerRegistration addKeyPressHandler (KeyPressHandler handler)

Adds a KeyPressEvent handler.

Parameters
handler the key press handler
Returns

public HandlerRegistration addKeyUpHandler (KeyUpHandler handler)

Adds a KeyUpEvent handler.

Parameters
handler the key up handler
Returns

public void addKeyboardListener (KeyboardListener listener)

This method is deprecated.
Use addKeyDownHandler(KeyDownHandler), addKeyUpHandler(KeyUpHandler) and addKeyPressHandler(KeyPressHandler) instead

Adds a listener interface to receive keyboard events.

Parameters
listener the listener interface to add

public HandlerRegistration addSelectionHandler (SelectionHandler<SuggestOracle.Suggestion> handler)

public HandlerRegistration addValueChangeHandler (ValueChangeHandler<String> handler)

public LeafValueEditor<String> asEditor ()

Returns a TakesValueEditor backed by the DateBox.

Returns

public int getLimit ()

Gets the limit for the number of suggestions that should be displayed for this box. It is up to the current SuggestOracle to enforce this limit.

Returns
  • the limit for the number of suggestions

public SuggestOracle getSuggestOracle ()

Gets the suggest box's SuggestOracle.

Returns

public SuggestBox.SuggestionDisplay getSuggestionDisplay ()

Get the SuggestBox.SuggestionDisplay used to display suggestions.

Returns

public int getTabIndex ()

Gets the widget's position in the tab index.

Returns
  • the widget's tab index

public String getText ()

Gets this object's text.

Returns
  • the object's text

public TextBoxBase getTextBox ()

Get the text box associated with this suggest box.

Returns
  • this suggest box's text box

public String getValue ()

Gets this object's value.

Returns
  • the object's value

public void hideSuggestionList ()

This method is deprecated.
use hideSuggestions() instead

Hide current suggestions in the SuggestBox.DefaultSuggestionDisplay. Note that this method is a no-op unless the SuggestBox.DefaultSuggestionDisplay is used.

public boolean isAnimationEnabled ()

This method is deprecated.
use isAnimationEnabled() instead

Check whether or not the SuggestBox.DefaultSuggestionDisplay has animations enabled. Note that this method only has a meaningful return value when the SuggestBox.DefaultSuggestionDisplay is used.

public boolean isAutoSelectEnabled ()

Returns whether or not the first suggestion will be automatically selected. This behavior is on by default.

Returns
  • true if the first suggestion will be automatically selected

public boolean isSuggestionListShowing ()

This method is deprecated.
use isSuggestionListShowing()

Check if the SuggestBox.DefaultSuggestionDisplay is showing. Note that this method only has a meaningful return value when the SuggestBox.DefaultSuggestionDisplay is used.

Returns
  • true if the list of suggestions is currently showing, false if not

public void removeChangeListener (ChangeListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by getTextBox()().addChangeHandler instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void removeClickListener (ClickListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by getTextBox()().addClickHandler instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void removeEventHandler (SuggestionHandler handler)

This method is deprecated.
Use the removeHandler() method no the object returned by addSelectionHandler(SelectionHandler) instead

Removes a previously added handler interface.

Parameters
handler the handler to remove

public void removeFocusListener (FocusListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by getTextBox()().addFocusListener instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void removeKeyboardListener (KeyboardListener listener)

This method is deprecated.
Use the removeHandler() method on the object returned by getTextBox()().add*Handler instead

Removes a previously added listener interface.

Parameters
listener the listener interface to remove

public void setAccessKey (char key)

Sets the widget's 'access key'. This key is used (in conjunction with a browser-specific modifier key) to automatically focus the widget.

Parameters
key the widget's access key

public void setAnimationEnabled (boolean enable)

This method is deprecated.
use setAnimationEnabled(boolean) instead

Enable or disable animations in the SuggestBox.DefaultSuggestionDisplay. Note that this method is a no-op unless the SuggestBox.DefaultSuggestionDisplay is used.

Parameters
enable true to enable, false to disable

public void setAutoSelectEnabled (boolean selectsFirstItem)

Turns on or off the behavior that automatically selects the first suggested item. This behavior is on by default.

Parameters
selectsFirstItem Whether or not to automatically select the first suggestion

public void setFocus (boolean focused)

Explicitly focus/unfocus this widget. Only one widget can have focus at a time, and the widget that does will receive all keyboard events.

Parameters
focused whether this widget should take focus or release it

public void setLimit (int limit)

Sets the limit to the number of suggestions the oracle should provide. It is up to the oracle to enforce this limit.

Parameters
limit the limit to the number of suggestions provided

public void setPopupStyleName (String style)

This method is deprecated.
use setPopupStyleName(String) instead

Sets the style name of the suggestion popup in the SuggestBox.DefaultSuggestionDisplay. Note that this method is a no-op unless the SuggestBox.DefaultSuggestionDisplay is used.

Parameters
style the new primary style name
See Also

public void setTabIndex (int index)

Sets the widget's position in the tab index. If more than one widget has the same tab index, each such widget will receive focus in an arbitrary order. Setting the tab index to -1 will cause this widget to be removed from the tab order.

Parameters
index the widget's tab index

public void setText (String text)

Sets this object's text.

Parameters
text the object's new text

public void setValue (String value, boolean fireEvents)

public void setValue (String newValue)

public void showSuggestionList ()

Show the current list of suggestions.

public static SuggestBox wrap (SuggestOracle oracle, Element element)

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

Parameters
oracle the suggest box oracle to use
element the element to be wrapped

Protected Methods

protected void onEnsureDebugId (String baseID)

Called when the user sets the id using the 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:

  • -mysubelement = Applies to my sub element.
Subclasses should make a super call to this method to ensure that the ID of the main element is set. This method will not be called unless you inherit the DebugID module in your gwt.xml file by adding the following line: 
 <inherits name="com.google.gwt.user.Debug"/>

Parameters
baseID the base ID used by the main element