Google Web Toolkit
Search Google Code:

# Class SuggestBox

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 }

## Constructors

SuggestBox() | Constructor for SuggestBox.
SuggestBox(SuggestOracle) | Constructor for SuggestBox.
SuggestBox(SuggestOracle, TextBoxBase) | Constructor for SuggestBox.

## Methods

addChangeListener(ChangeListener) | Adds a listener to recieve change events on the SuggestBox's text box.
addClickListener(ClickListener) | Adds a listener to recieve click events on the SuggestBox's text box.
addEventHandler(SuggestionHandler) | Adds a handler interface to receive suggestion events.
addFocusListener(FocusListener) | Adds a listener to recieve focus events on the SuggestBox's text box.
addKeyboardListener(KeyboardListener) | Adds a listener to recieve keyboard events on the SuggestBox's text box.
getLimit() | Gets the limit for the number of suggestions that should be displayed for this box.
getSuggestOracle() | Gets the suggest box's SuggestOracle.
getTabIndex() | Gets the widget's position in the tab index.
getText() | Gets this object's text.
removeChangeListener(ChangeListener) | Removes a previously added listener interface.
removeClickListener(ClickListener) | Removes a previously added listener interface.
removeEventHandler(SuggestionHandler) | Removes a previously added handler interface.
removeFocusListener(FocusListener) | Removes a previously added listener interface.
removeKeyboardListener(KeyboardListener) | Removes a previously added listener interface.
setAccessKey(char) | Sets the widget's 'access key'.
setFocus(boolean) | Explicitly focus/unfocus this widget.
setLimit(int) | Sets the limit to the number of suggestions the oracle should provide.
setPopupStyleName(String) | Sets the style name of the suggestion popup.
setTabIndex(int) | Sets the widget's position in the tab index.
setText(String) | Sets this object's text.

## See Also

SuggestOracle, MultiWordSuggestOracle, TextBoxBase

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

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

#### Parameters

listener
  the listener interface to add

### addEventHandler

public void addEventHandler(SuggestionHandler handler)
Adds a handler interface to receive suggestion events.

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

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

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

#### Return Value

the limit for the number of suggestions

### getSuggestOracle

public final SuggestOracle getSuggestOracle()
Gets the suggest box's SuggestOracle.

#### Return Value

the SuggestOracle

### getTabIndex

public int getTabIndex()
Gets the widget's position in the tab index.

#### Return Value

the widget's tab index

### getText

public String getText()
Gets this object's text.

#### Return Value

the object's text

### removeChangeListener

public void removeChangeListener(ChangeListener listener)
Removes a previously added listener interface.

#### Parameters

listener
  the listener interface to remove

### removeClickListener

public void removeClickListener(ClickListener listener)
Removes a previously added listener interface.

#### Parameters

listener
  the listener interface to remove

### removeEventHandler

public void removeEventHandler(SuggestionHandler handler)
Removes a previously added handler interface.

#### Parameters

handler
  the handler to remove.

### removeFocusListener

public void removeFocusListener(FocusListener listener)
Removes a previously added listener interface.

#### Parameters

listener
  the listener interface to remove

### removeKeyboardListener

public void removeKeyboardListener(KeyboardListener listener)
Removes a previously added listener interface.

#### Parameters

listener
  the listener interface to remove

### setAccessKey

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

### setFocus

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

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

### setText

public void setText(String text)
Sets this object's text.

#### Parameters

text
  the object's new text