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

java.lang.Object
  extended bycom.google.gwt.user.client.ui.UIObject
      extended bycom.google.gwt.user.client.ui.Widget
          extended bycom.google.gwt.user.client.ui.Composite
              extended bycom.google.gwt.user.client.ui.SuggestBox
All Implemented Interfaces:
EventListener, HasFocus, HasText, SourcesChangeEvents, SourcesClickEvents, SourcesFocusEvents, SourcesKeyboardEvents

public final class SuggestBox
extends Composite
implements HasText, HasFocus, SourcesClickEvents, SourcesFocusEvents, SourcesChangeEvents, SourcesKeyboardEvents

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.

CSS Style Rules

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 interface to receive change events.
 void addClickListener(ClickListener listener)
          Adds a listener interface to receive click events.
 void addFocusListener(FocusListener listener)
          Adds a listener interface to receive mouse events.
 void addKeyboardListener(KeyboardListener listener)
          Adds a listener interface to receive keyboard events.
 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 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 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, onAttach, onDetach, setWidget
 
Methods inherited from class com.google.gwt.user.client.ui.Widget
getParent, isAttached, onBrowserEvent, onLoad, onUnload, removeFromParent, setElement
 
Methods inherited from class com.google.gwt.user.client.ui.UIObject
addStyleName, getAbsoluteLeft, getAbsoluteTop, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getTitle, isVisible, isVisible, removeStyleName, resetStyleName, setHeight, setPixelSize, setSize, setStyleName, setStyleName, 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)
Description copied from interface: SourcesChangeEvents
Adds a listener interface to receive change events.

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

addClickListener

public final void addClickListener(ClickListener listener)
Description copied from interface: SourcesClickEvents
Adds a listener interface to receive click events.

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

addFocusListener

public final void addFocusListener(FocusListener listener)
Description copied from interface: SourcesFocusEvents
Adds a listener interface to receive mouse events.

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

addKeyboardListener

public final void addKeyboardListener(KeyboardListener listener)
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

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

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

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