com.google.gwt.user.client.ui

## Class MultiWordSuggestOracle

- java.lang.Object
- - com.google.gwt.user.client.ui.SuggestOracle
  - - com.google.gwt.user.client.ui.MultiWordSuggestOracle

-     public class MultiWordSuggestOracle
      extends SuggestOracle

  The default `SuggestOracle`. The default oracle returns potential suggestions based on breaking the query into separate words and looking for matches. It also modifies the returned text to show which prefix matched the query term. The matching is case insensitive. All suggestions are sorted before being passed into a response.

  Example Table

  All Suggestions | Query string | Matching Suggestions
  John Smith, Joe Brown, Jane Doe, Jane Smith, Bob Jones | Jo | John Smith, Joe Brown, Bob Jones
  John Smith, Joe Brown, Jane Doe, Jane Smith, Bob Jones | Smith | John Smith, Jane Smith
  Georgia, New York, California | g | Georgia

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `MultiWordSuggestOracle.MultiWordSuggestion` Suggestion class for `MultiWordSuggestOracle`.

    - ### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.SuggestOracle

      `SuggestOracle.Callback, SuggestOracle.Request, SuggestOracle.Response, SuggestOracle.Suggestion`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultiWordSuggestOracle()` Constructor for `MultiWordSuggestOracle`.
    `MultiWordSuggestOracle(java.lang.String whitespaceChars)` Constructor for `MultiWordSuggestOracle` which takes in a set of whitespace chars that filter its input.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(java.lang.String suggestion)` Adds a suggestion to the oracle.
    `void` | `addAll(java.util.Collection<java.lang.String> collection)` Adds all suggestions specified.
    `void` | `clear()` Removes all of the suggestions from the oracle.
    `protected MultiWordSuggestOracle.MultiWordSuggestion` | `createSuggestion(java.lang.String replacementString, java.lang.String displayString)` Creates the suggestion based on the given replacement and display strings.
    `boolean` | `isDisplayStringHTML()` Should `SuggestOracle.Suggestion` display strings be treated as HTML? If true, this all suggestions' display strings will be interpreted as HTML, otherwise as text.
    `void` | `requestDefaultSuggestions(SuggestOracle.Request request, SuggestOracle.Callback callback)` Generate a `SuggestOracle.Response` based on a default request.
    `void` | `requestSuggestions(SuggestOracle.Request request, SuggestOracle.Callback callback)` Generate a `SuggestOracle.Response` based on a specific `SuggestOracle.Request`.
    `void` | `setComparator(java.util.Comparator<java.lang.String> comparator)` Sets the comparator used for sorting candidates from search.
    `void` | `setDefaultSuggestions(java.util.Collection<SuggestOracle.Suggestion> suggestionList)` Sets the default suggestion collection.
    `void` | `setDefaultSuggestionsFromText(java.util.Collection<java.lang.String> suggestionList)` A convenience method to set default suggestions using plain text strings.
    `void` | `setSuggestAllMatchingWords(boolean suggestAllMatchingWords)` Sets the flag on whether to suggest all matching words.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### MultiWordSuggestOracle

          public MultiWordSuggestOracle()

      Constructor for `MultiWordSuggestOracle`. This uses a space as the whitespace character.
      See Also:
        `MultiWordSuggestOracle(String)`

    - #### MultiWordSuggestOracle

          public MultiWordSuggestOracle(java.lang.String whitespaceChars)

      Constructor for `MultiWordSuggestOracle` which takes in a set of whitespace chars that filter its input.

      Example: If `".,"` is passed in as whitespace, then the string "foo.bar" would match the queries "foo", "bar", "foo.bar", "foo...bar", and "foo, bar". If the empty string is used, then all characters are used in matching. For example, the query "bar" would match "bar", but not "foo bar".

      Parameters:
        `whitespaceChars` - the characters to treat as word separators

  - ### Method Detail

    - #### add

          public void add(java.lang.String suggestion)

      Adds a suggestion to the oracle. Each suggestion must be plain text.
      Parameters:
        `suggestion` - the suggestion

    - #### addAll

          public final void addAll(java.util.Collection<java.lang.String> collection)

      Adds all suggestions specified. Each suggestion must be plain text.
      Parameters:
        `collection` - the collection

    - #### clear

          public void clear()

      Removes all of the suggestions from the oracle.

    - #### isDisplayStringHTML

          public boolean isDisplayStringHTML()

      Description copied from class: `SuggestOracle`
      Should `SuggestOracle.Suggestion` display strings be treated as HTML? If true, this all suggestions' display strings will be interpreted as HTML, otherwise as text.
      Overrides:
        `isDisplayStringHTML` in class `SuggestOracle`
      Returns:
        by default, returns false

    - #### requestDefaultSuggestions

          public void requestDefaultSuggestions(SuggestOracle.Request request,
                                                SuggestOracle.Callback callback)

      Description copied from class: `SuggestOracle`
      Generate a `SuggestOracle.Response` based on a default request. The request query must be null as it represents the results the oracle should return based on no query string.

      After the `SuggestOracle.Response` is created, it is passed into `SuggestOracle.Callback.onSuggestionsReady(com.google.gwt.user.client.ui.SuggestOracle.Request, com.google.gwt.user.client.ui.SuggestOracle.Response)` .

      Overrides:
        `requestDefaultSuggestions` in class `SuggestOracle`
      Parameters:
        `request` - the request
        `callback` - the callback to use for the response

    - #### requestSuggestions

          public void requestSuggestions(SuggestOracle.Request request,
                                         SuggestOracle.Callback callback)

      Description copied from class: `SuggestOracle`
      Generate a `SuggestOracle.Response` based on a specific `SuggestOracle.Request`. After the `SuggestOracle.Response` is created, it is passed into `SuggestOracle.Callback.onSuggestionsReady(com.google.gwt.user.client.ui.SuggestOracle.Request, com.google.gwt.user.client.ui.SuggestOracle.Response)`.
      Specified by:
        `requestSuggestions` in class `SuggestOracle`
      Parameters:
        `request` - the request
        `callback` - the callback to use for the response

    - #### setComparator

          public void setComparator(java.util.Comparator<java.lang.String> comparator)

      Sets the comparator used for sorting candidates from search.
      Parameters:
        `comparator` - the comparator to use.

    - #### setDefaultSuggestions

          public void setDefaultSuggestions(java.util.Collection<SuggestOracle.Suggestion> suggestionList)

      Sets the default suggestion collection.
      Parameters:
        `suggestionList` - the default list of suggestions

    - #### setDefaultSuggestionsFromText

          public final void setDefaultSuggestionsFromText(java.util.Collection<java.lang.String> suggestionList)

      A convenience method to set default suggestions using plain text strings. Note to use this method each default suggestion must be plain text.
      Parameters:
        `suggestionList` - the default list of suggestions

    - #### setSuggestAllMatchingWords

          public final void setSuggestAllMatchingWords(boolean suggestAllMatchingWords)

      Sets the flag on whether to suggest all matching words. With words 'Mobile', 'MOBILE', 'mobile', 'MoBILE', typing 'm' will only build one suggestion for 'MoBILE' if `suggestAllMatchingWords` is `false`. However, it will build suggestions for all four words if `suggestAllMatchingWords` is `true`.
      Parameters:
        `suggestAllMatchingWords` - true to return all formatted suggestions per normalized candidate, false to return the last formatted suggestions per normalized candidate.

    - #### createSuggestion

          protected MultiWordSuggestOracle.MultiWordSuggestion createSuggestion(java.lang.String replacementString,
                                                                                java.lang.String displayString)

      Creates the suggestion based on the given replacement and display strings.
      Parameters:
        `replacementString` - the string to enter into the SuggestBox's text box if the suggestion is chosen
        `displayString` - the display string
      Returns:
        the suggestion created