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