SearchSuggestionCollection SearchSuggestionCollection SearchSuggestionCollection SearchSuggestionCollection Class

Represents a collection of search suggestions to be displayed in the search pane in response to a SuggestionsRequested event.

Syntax

Declaration

public sealed class SearchSuggestionCollectionpublic sealed class SearchSuggestionCollectionPublic NotInheritable Class SearchSuggestionCollection

Remarks

The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

An app retrieves this object through the SearchSuggestionCollection property while handling a SuggestionsRequested event.

Examples

The Search contract sample demonstrates how to respond to a SuggestionsRequested event, including how to use the SearchSuggestionCollection.

private void OnSearchPaneSuggestionsRequested(SearchPane sender, SearchPaneSuggestionsRequestedEventArgs e)
{
    var queryText = e.QueryText;
    if (string.IsNullOrEmpty(queryText))
    {
        MainPage.Current.NotifyUser("Use the search pane to submit a query", NotifyType.StatusMessage);
    }
    else
    {
        var request = e.Request;
        var linguisticDetails = e.LinguisticDetails;
        foreach (string alternative in linguisticDetails.QueryTextAlternatives)
        {
            foreach (string suggestion in suggestionList)
            {
                if (suggestion.StartsWith(alternative, StringComparison.CurrentCultureIgnoreCase))
                {
                    // Add suggestion to Search Pane
                    request.SearchSuggestionCollection.AppendQuerySuggestion(suggestion);

                    // Break since the Search Pane can show at most 5 suggestions
                    if (request.SearchSuggestionCollection.Size >= MainPage.SearchPaneMaxSuggestions)
                    {
                        break;
                    }
                }
            }

            // Break since the Search Pane can show at most 5 suggestions
            if (request.SearchSuggestionCollection.Size >= MainPage.SearchPaneMaxSuggestions)
            {
                break;
            }
        }

        if (request.SearchSuggestionCollection.Size > 0)
        {
            MainPage.Current.NotifyUser("Suggestions provided for query: " + queryText, NotifyType.StatusMessage);
        }
        else
        {
            MainPage.Current.NotifyUser("No suggestions provided for query: " + queryText, NotifyType.StatusMessage);
        }
    }
}
// Register the onsuggestionsrequested event in your apps global scope, for example default.js, so that it is registered as soon as your app is launched.
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onsuggestionsrequested = function (eventObject) {
    var queryText = eventObject.queryText, suggestionRequest = eventObject.request, linguisticDetails = eventObject.linguisticDetails;

    var queryAlternatives = linguisticDetails.queryTextAlternatives;
    var maxNumberOfSuggestions = 5;
    for (var i = 0, len = queryAlternatives.length, done = false; i < len && !done; i++) {
        // toLowerCase not necessary for East Asian languages. Preserves compatibility when non East Asian suggestions are mixed in with East Asian suggestions.
        var alternative = queryAlternatives[i].toLowerCase();
        for (var j = 0, suggestionLength = suggestionList.length; j < suggestionLength; j++) {
            if (suggestionList[j].substr(0, alternative.length).toLowerCase() === alternative) {
                suggestionRequest.searchSuggestionCollection.appendQuerySuggestion(suggestionList[j]);
                if (suggestionRequest.searchSuggestionCollection.size === maxNumberOfSuggestions) {
                    done = true;
                    break;
                }
            }
        }
    }

    // Construct list of alternatives so we can output them.
    var alternatives = "";
    for (var k = 0, alternativeCount = queryAlternatives.length; k < alternativeCount; k++) {
        alternatives += queryAlternatives[k];
    }
    if (suggestionRequest.searchSuggestionCollection.size > 0) {
        WinJS.log && WinJS.log("Suggestions provided for query: " + queryText + "\nUsing alternatives: " + alternatives, "sample", "status");
    } else {
        WinJS.log && WinJS.log("No suggestions provided for query: " + queryText + "\nUsing alternatives: " + alternatives, "sample", "status");
    }
};

Properties summary

The number of suggestions in the collection.

Methods summary

Appends a query suggestion to the list of search suggestions for the search pane.

Appends a list of query suggestions to the list of search suggestions for the search pane.

Appends a suggested search result to the list of suggestions to display in the search pane.

Appends a text label that is used to separate groups of suggestions in the search pane.

Properties

  • Size
    Size
    Size
    Size

    The number of suggestions in the collection.

    public uint Size { get; }public uint Size { get; }Public ReadOnly Property Size As uint

    Property Value

    • uint
      uint
      uint
      uint

      The number of suggestions.

    Remarks

    The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

Methods

  • AppendQuerySuggestion(System.String)
    AppendQuerySuggestion(System.String)
    AppendQuerySuggestion(System.String)
    AppendQuerySuggestion(System.String)

    Appends a query suggestion to the list of search suggestions for the search pane.

    public void AppendQuerySuggestion(System.String)public void AppendQuerySuggestion(System.String)Public Function AppendQuerySuggestion(System.String) As void

    Parameters

    • text
      System.String
      System.String
      System.String
      System.String

      The text of the query suggestion.

    Remarks

    A query suggestion is a suggestion that the user can select as his or her query.

    The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

  • AppendQuerySuggestions(Windows.Foundation.Collections.IIterable{System.String})
    AppendQuerySuggestions(Windows.Foundation.Collections.IIterable{System.String})
    AppendQuerySuggestions(Windows.Foundation.Collections.IIterable{System.String})
    AppendQuerySuggestions(Windows.Foundation.Collections.IIterable{System.String})

    Appends a list of query suggestions to the list of search suggestions for the search pane.

    public void AppendQuerySuggestions(Windows.Foundation.Collections.IIterable{System.String})public void AppendQuerySuggestions(Windows.Foundation.Collections.IIterable{System.String})Public Function AppendQuerySuggestions(Windows.Foundation.Collections.IIterable{System.String}) As void

    Parameters

    • suggestions

      The list of query suggestions.

    Remarks

    A query suggestion is a suggestion that the user can select as his or her query.

    The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

  • AppendResultSuggestion(System.String,System.String,System.String,Windows.Storage.Streams.IRandomAccessStreamReference,System.String)
    AppendResultSuggestion(System.String,System.String,System.String,Windows.Storage.Streams.IRandomAccessStreamReference,System.String)
    AppendResultSuggestion(System.String,System.String,System.String,Windows.Storage.Streams.IRandomAccessStreamReference,System.String)
    AppendResultSuggestion(System.String,System.String,System.String,Windows.Storage.Streams.IRandomAccessStreamReference,System.String)

    Appends a suggested search result to the list of suggestions to display in the search pane.

    public void AppendResultSuggestion(System.String,System.String,System.String,Windows.Storage.Streams.IRandomAccessStreamReference,System.String)public void AppendResultSuggestion(System.String,System.String,System.String,Windows.Storage.Streams.IRandomAccessStreamReference,System.String)Public Function AppendResultSuggestion(System.String,System.String,System.String,Windows.Storage.Streams.IRandomAccessStreamReference,System.String) As void

    Parameters

    • text
      System.String
      System.String
      System.String
      System.String

      The text of the suggested result.

    • detailText
      System.String
      System.String
      System.String
      System.String

      The detail text for the suggested result.

    • tag
      System.String
      System.String
      System.String
      System.String

      The unique tag that identifies this suggested result.

      If this suggested result is selected by the user, a ResultSuggestionChosen event is fired. When the app handles this event, it can get the tag of the chosen result suggestion from the Tag property.

    • image

      The image to accompany the results suggestion. The image should be 40 x 40. Windows will scale or crop smaller or larger images.

    • imageAlternateText
      System.String
      System.String
      System.String
      System.String

      The alternate text for the image.

    Remarks

    You should use result suggestions instead of query suggestions only to display high-confidence results that take the user directly to the item instead of to a view that shows search results.

    Suggested results include an image and optional detail text to display with the suggestion in the search pane. The image signals to the user that they are seeing results and not query suggestions. If an image for the result doesn't exist, you can use a generic image or icon that represents the result or result type.

    You must listen for and handle the ResultSuggestionChosen event if you want to provide result suggestions.

    The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and lowers the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

  • AppendSearchSeparator(System.String)
    AppendSearchSeparator(System.String)
    AppendSearchSeparator(System.String)
    AppendSearchSeparator(System.String)

    Appends a text label that is used to separate groups of suggestions in the search pane.

    public void AppendSearchSeparator(System.String)public void AppendSearchSeparator(System.String)Public Function AppendSearchSeparator(System.String) As void

    Parameters

    • label
      System.String
      System.String
      System.String
      System.String

      The text to use as a separator. This text should be descriptive of any suggestions that are appended after it.

    Remarks

    The search pane can display 5 suggestions, at most. Additionally, each separator you use takes the place of a suggestion and decreases the number of suggestions that you can display. Learn more about displaying suggestions in Guidelines and checklist for search.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MuseAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.ApplicationModel.Search.dll