Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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:
  EventListener, FiresSuggestionEvents, HasFocus, HasText, SourcesChangeEvents, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents

    public final class SuggestBox

extends Composite
implements HasText, HasFocus, SourcesClickEvents, SourcesFocusEvents, SourcesChangeEvents, SourcesKeyboardEvents, FiresSuggestionEvents

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 `addEventHandler(SuggestionHandler)` 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 }

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

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)` Adds a listener to recieve change events on the SuggestBox's text box.
`void` | `addClickListener(ClickListener listener)` Adds a listener to recieve click events on the SuggestBox's text box.
`void` | `addEventHandler(SuggestionHandler handler)` Adds a handler interface to receive suggestion events.
`void` | `addFocusListener(FocusListener listener)` Adds a listener to recieve focus events on the SuggestBox's text box.
`void` | `addKeyboardListener(KeyboardListener listener)` Adds a listener to recieve keyboard events on the SuggestBox's text box.
`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.
`void` | `removeChangeListener(ChangeListener listener)` Removes a previously added listener interface.
`void` | `removeClickListener(ClickListener listener)` Removes a previously added listener interface.
`void` | `removeEventHandler(SuggestionHandler handler)` Removes a previously added handler interface.
`void` | `removeFocusListener(FocusListener listener)` Removes a previously added listener interface.
`void` | `removeKeyboardListener(KeyboardListener listener)` Removes a previously added listener interface.
`void` | `setAccessKey(char key)` Sets the widget's 'access key'.
`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.

Methods inherited from class com.google.gwt.user.client.ui.Composite
`getElement, getWidget, initWidget, isAttached, onAttach, onDetach, setWidget`

Methods inherited from class com.google.gwt.user.client.ui.Widget
`doAttachChildren, doDetachChildren, getParent, onBrowserEvent, onLoad, onUnload, removeFromParent, setElement`

Methods inherited from class com.google.gwt.user.client.ui.UIObject
`addStyleDependentName, addStyleName, getAbsoluteLeft, getAbsoluteTop, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, setHeight, setPixelSize, setSize, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkEvents, toString, unsinkEvents`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

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

### addChangeListener

    public final void addChangeListener(ChangeListener listener)

  Adds a listener to recieve 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

    public final void addClickListener(ClickListener listener)

  Adds a listener to recieve 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

    public final void addEventHandler(SuggestionHandler handler)

  Description copied from interface: `FiresSuggestionEvents`
  Adds a handler interface to receive suggestion events.

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

### addFocusListener

    public final void addFocusListener(FocusListener listener)

  Adds a listener to recieve 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

    public final void addKeyboardListener(KeyboardListener listener)

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

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

### getLimit

    public final 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 final SuggestOracle getSuggestOracle()

  Gets the suggest box's `SuggestOracle`.

  Returns:
    the `SuggestOracle`

### getTabIndex

    public final int getTabIndex()

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

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

### getText

    public final 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

### removeChangeListener

    public final void removeChangeListener(ChangeListener listener)

  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

    public final void removeClickListener(ClickListener listener)

  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

    public final void removeEventHandler(SuggestionHandler handler)

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

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

### removeFocusListener

    public final void removeFocusListener(FocusListener listener)

  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

    public final void removeKeyboardListener(KeyboardListener listener)

  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 final void setAccessKey(char key)

  Description copied from interface: `HasFocus`
  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 `HasFocus`
  Parameters:
    `key` - the widget's access key

### setFocus

    public final void setFocus(boolean focused)

  Description copied from interface: `HasFocus`
  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 `HasFocus`
  Parameters:
    `focused` - whether this widget should take focus or release it

### setLimit

    public final 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 final 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 final void setTabIndex(int index)

  Description copied from interface: `HasFocus`
  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 `HasFocus`
  Parameters:
    `index` - the widget's tab index

### setText

    public final 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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD