SearchPaneSuggestionsRequest SearchPaneSuggestionsRequest SearchPaneSuggestionsRequest SearchPaneSuggestionsRequest Class

Stores suggestions and information about the request for suggestions.

Syntax

Declaration

public sealed class SearchPaneSuggestionsRequestpublic sealed class SearchPaneSuggestionsRequestPublic NotInheritable Class SearchPaneSuggestionsRequestpublic sealed class SearchPaneSuggestionsRequest

Remarks

If your app provides its own suggestions to display in the search pane, use the SearchSuggestionCollection property to add your app's suggestions to the collection of suggestions to display.

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.

Examples

The Search contract sample demonstrates how to respond to a SuggestionsRequested event, including how to access the SearchPaneSuggestionsRequest.

private async 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 if (string.IsNullOrEmpty(UrlTextBox.Text))
    {
        MainPage.Current.NotifyUser("Please enter the web service URL", NotifyType.StatusMessage);
    }
    else
    {
        // The deferral object is used to supply suggestions asynchronously for example when fetching suggestions from a web service.
        var request = e.Request;
        var deferral = request.GetDeferral();

        try
        {
            // Use the web service Url entered in the UrlTextBox that supports XML Search Suggestions in order to see suggestions come from the web service.
            // See http://msdn.microsoft.com/en-us/library/cc848863(v=vs.85).aspx for details on XML Search Suggestions format.
            // Replace "{searchTerms}" of the Url with the query string.
            Task task = GetSuggestionsAsync(Regex.Replace(UrlTextBox.Text, "{searchTerms}", Uri.EscapeDataString(queryText)), request.SearchSuggestionCollection);
            await task;
            if (task.Status == TaskStatus.RanToCompletion)
            {
                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);
                }
            }
        }
        catch (TaskCanceledException)
        {
            // Previous suggestion request was canceled.
        }
        catch (FormatException)
        {
            MainPage.Current.NotifyUser("Suggestions could not be retrieved, please verify that the URL points to a valid service (for example http://contoso.com?q={searchTerms})", NotifyType.ErrorMessage);
        }
        catch (Exception)
        {
            MainPage.Current.NotifyUser("Suggestions could not be displayed, please verify that the service provides valid XML Search Suggestions.", NotifyType.ErrorMessage);
        }
        finally
        {
            deferral.Complete();
        }
    }
}
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onsuggestionsrequested = function (eventObject) {
    var queryText = eventObject.queryText, language = eventObject.language, suggestionRequest = eventObject.request;

    // The deferral object is used to supply suggestions asynchronously for example when fetching suggestions from a web service.
    // Indicate that we'll do this asynchronously:
    var deferral = suggestionRequest.getDeferral();

    // Use the web service Uri entered in the urlInput that supports this standard in order to see suggestions come from the web service.
    // See http://msdn.microsoft.com/en-us/library/cc848863(v=vs.85).aspx for details on XML Search Suggestions format.
    // And replace "{searchTerms}" with the query string, which should be encoded into the URI.
    var suggestionUri = document.getElementById("urlInput").innerText.replace("{searchTerms}", encodeURIComponent(queryText));

    // Cancel the previous suggestion request if it is not finished.
    if (xhrRequest && xhrRequest.cancel) {
        xhrRequest.cancel();
    }

    // Create request to obtain suggestions from service and supply them to the Search Pane.
    xhrRequest = WinJS.xhr({ url: suggestionUri });
    xhrRequest.done(
        function (request) {
            if (request.responseXML) {
                generateSuggestions(request.responseXML, suggestionRequest.searchSuggestionCollection, queryText);
            }

            deferral.complete(); // Indicate we're done supplying suggestions.
        },
        function (error) {
            WinJS.log && WinJS.log("Error retrieving suggestions for query: " + queryText, "sample", "status");

            // Call complete on the deferral when there is an error.
            deferral.complete();
        });
};

Properties summary

Indicates whether the request for suggestions to display is canceled.

The suggestions to display in the search pane for the current query. Apps provide suggestions to display by appending them to this SearchSuggestionCollection object.

Methods summary

Retrieves an object that lets an app respond to a request for suggestions asynchronously.

Properties

  • IsCanceled
    IsCanceled
    IsCanceled
    IsCanceled

    Indicates whether the request for suggestions to display is canceled.

    public bool IsCanceled { get; }public bool IsCanceled { get; }Public ReadOnly Property IsCanceled As boolpublic bool IsCanceled { get; }

    Property Value

    • bool
      bool
      bool
      bool

      True if the request was canceled, otherwise false. The default value is false.

    Remarks

    A request for search pane suggestions is valid if it is still tied to the most recent SuggestionsRequested event; that is, if the user has not changed the search query.

  • SearchSuggestionCollection
    SearchSuggestionCollection
    SearchSuggestionCollection
    SearchSuggestionCollection

    The suggestions to display in the search pane for the current query. Apps provide suggestions to display by appending them to this SearchSuggestionCollection object.

    public SearchSuggestionCollection SearchSuggestionCollection { get; }public SearchSuggestionCollection SearchSuggestionCollection { get; }Public ReadOnly Property SearchSuggestionCollection As SearchSuggestionCollectionpublic SearchSuggestionCollection SearchSuggestionCollection { get; }

    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.

    Use the SearchSuggestionCollection object to append app-provided suggestions and search separators to display in the search pane.

    When the request for suggestions is completed, either by returning from the SuggestionsRequested event handler or by calling Complete(), the search pane displays the suggestions in the SearchSuggestionCollection.

Methods

  • GetDeferral()
    GetDeferral()
    GetDeferral()
    GetDeferral()

    Retrieves an object that lets an app respond to a request for suggestions asynchronously.

    public SearchPaneSuggestionsRequestDeferral GetDeferral()public SearchPaneSuggestionsRequestDeferral GetDeferral()Public Function GetDeferral() As SearchPaneSuggestionsRequestDeferralpublic SearchPaneSuggestionsRequestDeferral GetDeferral()

    Returns

    Remarks

    Your app should respond asynchronously to a request for search suggestions if fulfilling the request will take a significant amount of time, such as fetching suggestions from a web service.

    Use the Complete() method to signal when your app has fulfilled the request.

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.ContractVersionAttribute
Windows.Foundation.Metadata.DeprecatedAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.ApplicationModel.Search.dll