Overview  Package   Class  Tree  Deprecated  Index  Help 
GWT 2.0.3
 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
  extended by com.google.gwt.user.client.ui.UIObject
      extended by com.google.gwt.user.client.ui.Widget
          extended by com.google.gwt.user.client.ui.Composite
              extended by 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) 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) 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, getLayoutData, getParent, isOrWasAttached, onLoad, onUnload, removeFromParent, setLayoutData, 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
 

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) 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) 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:

Overrides:
onEnsureDebugId in class UIObject
Parameters:
baseID - the base ID used by the main element
See Also:
UIObject.onEnsureDebugId(String)
Overview  Package   Class  Tree  Deprecated  Index  Help 
GWT 2.0.3
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD