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 `SelectionHandler` to the SuggestBox (see SuggestBox's documentation for more information). In the `SelectionHandler.onSelection(SelectionEvent<Suggestion> event)` method, obtain the selected `Suggestion` object from the `SelectionEvent` object, and downcast the `Suggestion` object to the subinterface. Then, access the DTO using the DTO getter method that was defined on the subinterface.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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