## com.google.gwt.user.client.ui
Class SuggestBox

    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

All Implemented Interfaces:
  HasAllKeyHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasSelectionHandlers<SuggestOracle.Suggestion>, HasValueChangeHandlers<java.lang.String>, HasHandlers, EventListener, FiresSuggestionEvents, Focusable, HasAnimation, HasFocus, HasText, HasValue<java.lang.String>, SourcesChangeEvents, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents

    public class SuggestBox

extends Composite
implements HasText, HasFocus, HasAnimation, SourcesClickEvents, SourcesFocusEvents, SourcesChangeEvents, SourcesKeyboardEvents, FiresSuggestionEvents, HasAllKeyHandlers, HasValue<java.lang.String>, HasSelectionHandlers<SuggestOracle.Suggestion>

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
.gwt-SuggestBoxPopup
  the suggestion popup
.gwt-SuggestBoxPopup .item
  an unselected suggestion
.gwt-SuggestBoxPopup .item-selected
  a selected suggestion
.gwt-SuggestBoxPopup .suggestPopupTopLeft
  the top left cell
.gwt-SuggestBoxPopup .suggestPopupTopLeftInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupTopCenter
  the top center cell
.gwt-SuggestBoxPopup .suggestPopupTopCenterInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupTopRight
  the top right cell
.gwt-SuggestBoxPopup .suggestPopupTopRightInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupMiddleLeft
  the middle left cell
.gwt-SuggestBoxPopup .suggestPopupMiddleLeftInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupMiddleCenter
  the middle center cell
.gwt-SuggestBoxPopup .suggestPopupMiddleCenterInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupMiddleRight
  the middle right cell
.gwt-SuggestBoxPopup .suggestPopupMiddleRightInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupBottomLeft
  the bottom left cell
.gwt-SuggestBoxPopup .suggestPopupBottomLeftInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupBottomCenter
  the bottom center cell
.gwt-SuggestBoxPopup .suggestPopupBottomCenterInner
  the inner element of the cell
.gwt-SuggestBoxPopup .suggestPopupBottomRight
  the bottom right cell
.gwt-SuggestBoxPopup .suggestPopupBottomRightInner
  the inner element of the cell

See Also:
  `SuggestOracle`, `MultiWordSuggestOracle`, `TextBoxBase`

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.UIObject
`DEBUG_ID_PREFIX`

Constructor Summary
`SuggestBox()` Constructor for `SuggestBox`.
`SuggestBox(SuggestOracle oracle)` Constructor for `SuggestBox`.
`SuggestBox(SuggestOracle oracle, TextBoxBase box)` 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<com.google.gwt.user.client.ui.SuggestOracle.Suggestion>)` 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.
`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`.
`int` | `getTabIndex()` Gets the widget's position in the tab index.
`java.lang.String` | `getText()` Gets this object's text.
`TextBoxBase` | `getTextBox()` Get the text box associated with this suggest box.
`java.lang.String` | `getValue()` Gets this object's value.
`void` | `hideSuggestionList()` Hide current suggestions.
`boolean` | `isAnimationEnabled()`
`boolean` | `isAutoSelectEnabled()` Returns whether or not the first suggestion will be automatically selected.
`boolean` | `isSuggestionListShowing()`
`protected void` | `onEnsureDebugId(java.lang.String baseID)` Affected Elements: -popup = The popup that appears with suggestions. -items-item# = The suggested item at the specified index.
`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)` Enable or disable animations.
`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(java.lang.String style)` Sets the style name of the suggestion popup.
`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.
`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
`getWidget, initWidget, isAttached, onAttach, onBrowserEvent, onDetach, setWidget`

Methods inherited from class com.google.gwt.user.client.ui.Widget
`addDomHandler, addHandler, delegateEvent, doAttachChildren, doDetachChildren, fireEvent, getHandlerCount, getParent, isOrWasAttached, onLoad, onUnload, removeFromParent, 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, setElement, setElement, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, 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`

Methods inherited from interface com.google.gwt.event.shared.HasHandlers
`fireEvent`

Methods inherited from interface com.google.gwt.event.shared.HasHandlers
`fireEvent`

Methods inherited from interface com.google.gwt.event.shared.HasHandlers
`fireEvent`

Constructor Detail

### SuggestBox

    public SuggestBox()

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

### SuggestBox

    public SuggestBox(SuggestOracle oracle)

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

  Parameters:
    `oracle` - the oracle for this `SuggestBox`

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

Method Detail

### wrap

    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 `RootPanel.detachNow(Widget)`.

  Parameters:
    `oracle` - the suggest box oracle to use
    `element` - the element to be wrapped

### addChangeListener

    @Deprecated
    public void addChangeListener(ChangeListener listener)

  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.

  Specified by:
    `addChangeListener` in interface `SourcesChangeEvents`
  Parameters:
    `listener` - the listener interface to add

### addClickListener

    @Deprecated
    public void addClickListener(ClickListener listener)

  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.

  Specified by:
    `addClickListener` in interface `SourcesClickEvents`
  Parameters:
    `listener` - the listener interface to add

### addEventHandler

    @Deprecated
    public void addEventHandler(SuggestionHandler handler)

  Deprecated. use `addSelectionHandler(com.google.gwt.event.logical.shared.SelectionHandler<com.google.gwt.user.client.ui.SuggestOracle.Suggestion>)` instead.

  Adds an event to this handler.

  Specified by:
    `addEventHandler` in interface `FiresSuggestionEvents`
  Parameters:
    `handler` - the handler to add

### addFocusListener

    @Deprecated
    public void addFocusListener(FocusListener listener)

  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.

  Specified by:
    `addFocusListener` in interface `SourcesFocusEvents`
  Parameters:
    `listener` - the listener interface to add

### addKeyboardListener

    @Deprecated
    public 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

  Description copied from interface: `SourcesKeyboardEvents`
  Adds a listener interface to receive keyboard events.

  Specified by:
    `addKeyboardListener` in interface `SourcesKeyboardEvents`
  Parameters:
    `listener` - the listener interface to add

### addKeyDownHandler

    public HandlerRegistration addKeyDownHandler(KeyDownHandler handler)

  Description copied from interface: `HasKeyDownHandlers`
  Adds a `KeyDownEvent` handler.

  Specified by:
    `addKeyDownHandler` in interface `HasKeyDownHandlers`
  Parameters:
    `handler` - the key down handler
  Returns:
    `HandlerRegistration` used to remove this handler

### addKeyPressHandler

    public HandlerRegistration addKeyPressHandler(KeyPressHandler handler)

  Description copied from interface: `HasKeyPressHandlers`
  Adds a `KeyPressEvent` handler.

  Specified by:
    `addKeyPressHandler` in interface `HasKeyPressHandlers`
  Parameters:
    `handler` - the key press handler
  Returns:
    `HandlerRegistration` used to remove this handler

### addKeyUpHandler

    public HandlerRegistration addKeyUpHandler(KeyUpHandler handler)

  Description copied from interface: `HasKeyUpHandlers`
  Adds a `KeyUpEvent` handler.

  Specified by:
    `addKeyUpHandler` in interface `HasKeyUpHandlers`
  Parameters:
    `handler` - the key up handler
  Returns:
    `HandlerRegistration` used to remove this handler

### addSelectionHandler

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

  Description copied from interface: `HasSelectionHandlers`
  Adds a `SelectionEvent` handler.

  Specified by:
    `addSelectionHandler` in interface `HasSelectionHandlers<SuggestOracle.Suggestion>`
  Parameters:
    `handler` - the handler
  Returns:
    the registration for the event

### addValueChangeHandler

    public HandlerRegistration addValueChangeHandler(ValueChangeHandler<java.lang.String> handler)

  Description copied from interface: `HasValueChangeHandlers`
  Adds a `ValueChangeEvent` handler.

  Specified by:
    `addValueChangeHandler` in interface `HasValueChangeHandlers<java.lang.String>`
  Parameters:
    `handler` - the handler
  Returns:
    the registration for the event

### getLimit

    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

### getSuggestOracle

    public SuggestOracle getSuggestOracle()

  Gets the suggest box's `SuggestOracle`.

  Returns:
    the `SuggestOracle`

### getTabIndex

    public int getTabIndex()

  Description copied from interface: `Focusable`
  Gets the widget's position in the tab index.

  Specified by:
    `getTabIndex` in interface `Focusable`
  Returns:
    the widget's tab index

### getText

    public java.lang.String getText()

  Description copied from interface: `HasText`
  Gets this object's text.

  Specified by:
    `getText` in interface `HasText`
  Returns:
    the object's text

### getTextBox

    public TextBoxBase getTextBox()

  Get the text box associated with this suggest box.

  Returns:
    this suggest box's text box

### getValue

    public java.lang.String getValue()

  Description copied from interface: `HasValue`
  Gets this object's value.

  Specified by:
    `getValue` in interface `HasValue<java.lang.String>`
  Returns:
    the object's value

### hideSuggestionList

    public void hideSuggestionList()

  Hide current suggestions.

### isAnimationEnabled

    public boolean isAnimationEnabled()

  Specified by:
    `isAnimationEnabled` in interface `HasAnimation`
  Returns:
    true if animations are enabled, false if not

### isAutoSelectEnabled

    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

### isSuggestionListShowing

    public boolean isSuggestionListShowing()

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

### removeChangeListener

    @Deprecated
    public void removeChangeListener(ChangeListener listener)

  Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by `getTextBox()`().addChangeHandler 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

### removeClickListener

    @Deprecated
    public void removeClickListener(ClickListener listener)

  Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by `getTextBox()`().addClickHandler instead

  Description copied from interface: `SourcesClickEvents`
  Removes a previously added listener interface.

  Specified by:
    `removeClickListener` in interface `SourcesClickEvents`
  Parameters:
    `listener` - the listener interface to remove

### removeEventHandler

    @Deprecated
    public 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

  Description copied from interface: `FiresSuggestionEvents`
  Removes a previously added handler interface.

  Specified by:
    `removeEventHandler` in interface `FiresSuggestionEvents`
  Parameters:
    `handler` - the handler to remove

### removeFocusListener

    @Deprecated
    public void removeFocusListener(FocusListener listener)

  Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by `getTextBox()`().addFocusListener instead

  Description copied from interface: `SourcesFocusEvents`
  Removes a previously added listener interface.

  Specified by:
    `removeFocusListener` in interface `SourcesFocusEvents`
  Parameters:
    `listener` - the listener interface to remove

### removeKeyboardListener

    @Deprecated
    public void removeKeyboardListener(KeyboardListener listener)

  Deprecated. Use the `HandlerRegistration.removeHandler()` method on the object returned by `getTextBox()`().add*Handler instead

  Description copied from interface: `SourcesKeyboardEvents`
  Removes a previously added listener interface.

  Specified by:
    `removeKeyboardListener` in interface `SourcesKeyboardEvents`
  Parameters:
    `listener` - the listener interface to remove

### setAccessKey

    public void setAccessKey(char key)

  Description copied from interface: `Focusable`
  Sets the widget's 'access key'. This key is used (in conjunction with a browser-specific modifier key) to automatically focus the widget.

  Specified by:
    `setAccessKey` in interface `Focusable`
  Parameters:
    `key` - the widget's access key

### setAnimationEnabled

    public void setAnimationEnabled(boolean enable)

  Description copied from interface: `HasAnimation`
  Enable or disable animations.

  Specified by:
    `setAnimationEnabled` in interface `HasAnimation`
  Parameters:
    `enable` - true to enable, false to disable

### setAutoSelectEnabled

    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

### setFocus

    public void setFocus(boolean focused)

  Description copied from interface: `Focusable`
  Explicitly focus/unfocus this widget. Only one widget can have focus at a time, and the widget that does will receive all keyboard events.

  Specified by:
    `setFocus` in interface `Focusable`
  Parameters:
    `focused` - whether this widget should take focus or release it

### setLimit

    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

### setPopupStyleName

    public void setPopupStyleName(java.lang.String style)

  Sets the style name of the suggestion popup.

  Parameters:
    `style` - the new primary style name
  See Also:
    `UIObject.setStyleName(String)`

### setTabIndex

    public void setTabIndex(int index)

  Description copied from interface: `Focusable`
  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.

  Specified by:
    `setTabIndex` in interface `Focusable`
  Parameters:
    `index` - the widget's tab index

### setText

    public void setText(java.lang.String text)

  Description copied from interface: `HasText`
  Sets this object's text.

  Specified by:
    `setText` in interface `HasText`
  Parameters:
    `text` - the object's new text

### setValue

    public void setValue(java.lang.String newValue)

  Description copied from interface: `HasValue`
  Sets this object's value without firing any events. This should be identical to calling setValue(value, false).

  It is acceptable to fail assertions or throw (documented) unchecked exceptions in response to bad values.

  By convention, GWT widgets that can be cleared accept null for `value`, but it is acceptable for widgets that cannot be cleared to throw an exception for null values.

  Specified by:
    `setValue` in interface `HasValue<java.lang.String>`
  Parameters:
    `newValue` - the object's new value

### setValue

    public void setValue(java.lang.String value,
                         boolean fireEvents)

  Description copied from interface: `HasValue`
  Sets this object's value. Fires `ValueChangeEvent` 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.

  Specified by:
    `setValue` in interface `HasValue<java.lang.String>`
  Parameters:
    `value` - the object's new value
    `fireEvents` - fire events if true and value is new

### showSuggestionList

    public void showSuggestionList()

  Show the current list of suggestions.

### onEnsureDebugId

    protected void onEnsureDebugId(java.lang.String baseID)

  Affected Elements:
  - -popup = The popup that appears with suggestions.
  - -items-item# = The suggested item at the specified index.

  Overrides:
    `onEnsureDebugId` in class `UIObject`
  Parameters:
    `baseID` - the base ID used by the main element
  See Also:
    `UIObject.onEnsureDebugId(String)`