com.google.gwt.user.client.ui
Interface SuggestOracle.Suggestion

All Known Implementing Classes:

MultiWordSuggestOracle.MultiWordSuggestion

Enclosing class:

SuggestOracle

public static interface SuggestOracle.Suggestion

Suggestion supplied by the SuggestOracle. Each suggestion has a display string and a replacement string. The display string is what is shown in the SuggestBox's list of suggestions. The interpretation of the display string depends upon the value of its oracle's SuggestOracle.isDisplayStringHTML(). The replacement string is the string that is entered into the SuggestBox's text box when the suggestion is selected from the list.

Replacement strings are useful when the display form of a suggestion differs from the input format for the data. For example, suppose that a company has a webpage with a form which requires the user to enter the e-mail address of an employee. Since users are likely to know the name of the employee, a SuggestBox is used to provide name suggestions as the user types. When the user types the letter f, a suggestion with the display string foo bar appears. When the user chooses this suggestion, the replacement string, foobar@company.com, is entered into the SuggestBox's text box.

This is an example where the input data format for the suggestion is not as user-friendly as the display format. In the event that the display of a suggestion exactly matches the input data format, the Suggestion interface would be implemented in such a way that the display string and replacement string would be identical.

Associating Data Transfer Objects (DTOs) with Suggestion Objects

Some applications retrieve suggesstions from a server, and may want to send back a DTO with each suggestion. In the previous example, a DTO returned with the suggestion may provide additional contact information about the selected employee, and this information could be used to fill out other fields on the form. To send back a DTO with each suggestion, extend the Suggestion interface and define a getter method that has a return value of the DTO's type. Define a class that implements this subinterface and use it to encapsulate each suggestion.

To access a suggestion's DTO when the suggestion is selected, add a SuggestionHandler to the SuggestBox (see SuggestBox's documentation for more information). In the SuggestionHandler.onSuggestionSelected(SuggestionEvent event) method, obtain the selected Suggestion object from the SuggestionEvent object, and downcast the Suggestion object to the subinterface. Then, acces the DTO using the DTO getter method that was defined on the subinterface.

Method Summary

java.lang.String	getDisplayString() Gets the display string associated with this suggestion.
java.lang.String	getReplacementString() Gets the replacement string associated with this suggestion.

Method Detail

getDisplayString

java.lang.String getDisplayString()

Gets the display string associated with this suggestion. The interpretation of the display string depends upon the value of its oracle's SuggestOracle.isDisplayStringHTML().

Returns:

the display string for this suggestion

getReplacementString

java.lang.String getReplacementString()

Gets the replacement string associated with this suggestion. When this suggestion is selected, the replacement string will be entered into the SuggestBox's text box.

Returns:

the string to be entered into the SuggestBox's text box when this suggestion is selected