SearchPaneSuggestionsRequestedEventArgs SearchPaneSuggestionsRequestedEventArgs SearchPaneSuggestionsRequestedEventArgs SearchPaneSuggestionsRequestedEventArgs Class

Provides data for a SuggestionsRequested event that is associated with a SearchPane object.

Syntax

Declaration

public sealed class SearchPaneSuggestionsRequestedEventArgspublic sealed class SearchPaneSuggestionsRequestedEventArgsPublic NotInheritable Class SearchPaneSuggestionsRequestedEventArgs

Remarks

This object is passed to an app's SuggestionsRequested event handler.

Use your app to provide suggestions

There are a few different ways you can get suggestions for your app to provide:

  • From an app-defined, static, local list
  • From a URL that supports suggestions in OpenSearch format
  • From a URL that supports suggestions in XML format After you obtain suggestions, you must append them to the collection of suggestions to display for the user's query. Access this collection with the SearchSuggestionCollection property.
Note

If you want to provide result suggestions, you must also listen for and handle the ResultSuggestionChosen event.

Examples

The Search contract sample demonstrates how to respond to a SuggestionsRequested event.

Note

You can access information about the event from the SearchPaneSuggestionsRequestedEventArgs object that is passed to your SuggestionsRequested handler.

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");
    }
};
searchPane.SuggestionsRequested += new TypedEventHandler<SearchPane, SearchPaneSuggestionsRequestedEventArgs>(OnSearchPaneSuggestionsRequested);

Properties summary

The Internet Engineering Task Force (IETF) language tag (BCP 47 standard) that identifies the language currently associated with the user's text input device.

An object that provides linguistic information about query text that the user is entering through an Input Method Editor (IME).

The text that the app should provide suggestions for and that was in the search box when the SuggestionsRequested event fired.

An object that stores suggestions and information about the request.

Properties

  • Language
    Language
    Language
    Language

    The Internet Engineering Task Force (IETF) language tag (BCP 47 standard) that identifies the language currently associated with the user's text input device.

    public string Language { get; }public string Language { get; }Public ReadOnly Property Language As string

    Property Value

    • string
      string
      string
      string

      The Internet Engineering Task Force (IETF) BCP 47 standard language tag.

  • LinguisticDetails
    LinguisticDetails
    LinguisticDetails
    LinguisticDetails

    An object that provides linguistic information about query text that the user is entering through an Input Method Editor (IME).

    public SearchPaneQueryLinguisticDetails LinguisticDetails { get; }public SearchPaneQueryLinguisticDetails LinguisticDetails { get; }Public ReadOnly Property LinguisticDetails As SearchPaneQueryLinguisticDetails

    Property Value

  • QueryText
    QueryText
    QueryText
    QueryText

    The text that the app should provide suggestions for and that was in the search box when the SuggestionsRequested event fired.

    public string QueryText { get; }public string QueryText { get; }Public ReadOnly Property QueryText As string

    Property Value

    • string
      string
      string
      string

      The query text that the app should provide suggestions for.

    Remarks

    Generally, this is the current text in the search box, but if the user types quickly or the app processes slowly, it may not be.

  • Request
    Request
    Request
    Request

    An object that stores suggestions and information about the request.

    public SearchPaneSuggestionsRequest Request { get; }public SearchPaneSuggestionsRequest Request { get; }Public ReadOnly Property Request As SearchPaneSuggestionsRequest

    Property Value

    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.

Device family

Windows Desktop Extension SDK (introduced v10.0.10240.0)
Xbox One Extensions for the UWP (introduced v10.0.10586.0)

API contract

Windows.ApplicationModel.Search.SearchContract (introduced v1)

Attributes

Windows.Foundation.Metadata.DeprecatedAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.ApplicationModel.Search.dll