SearchBox.SuggestionsRequested Event

Definition

Namespace:

Windows.UI.Xaml.Controls

Occurs when the user's query text changes and the app needs to provide new suggestions to display in the search pane.

// Register
event_token SuggestionsRequested(TypedEventHandler<SearchBox, SearchBoxSuggestionsRequestedEventArgs const&> const& handler) const;

// Revoke with event_token
void SuggestionsRequested(event_token const* cookie) const;

// Revoke with event_revoker
SearchBox::SuggestionsRequested_revoker SuggestionsRequested(auto_revoke_t, TypedEventHandler<SearchBox, SearchBoxSuggestionsRequestedEventArgs const&> const& handler) const;

public event TypedEventHandler<SearchBox,SearchBoxSuggestionsRequestedEventArgs> SuggestionsRequested;

function onSuggestionsRequested(eventArgs) { /* Your code */ }
searchBox.addEventListener("suggestionsrequested", onSuggestionsRequested);
searchBox.removeEventListener("suggestionsrequested", onSuggestionsRequested);
- or -
searchBox.onsuggestionsrequested = onSuggestionsRequested;

Public Custom Event SuggestionsRequested As TypedEventHandler(Of SearchBox, SearchBoxSuggestionsRequestedEventArgs) 

<SearchBox SuggestionsRequested="eventhandler"/>

Event Type

TypedEventHandler<SearchBox,SearchBoxSuggestionsRequestedEventArgs>

Remarks

You can get suggestions from several sources:

• You can define them yourself. For example, you could create a list of car manufacturers.
• You can get them from Windows if your app searches local files.
• You can get them from a web service or server.

For user experience guidelines for displaying suggestions, see Guidelines and checklist for search.

You can use LocalContentSuggestionSettings to add suggestions, based on local files from Windows, in only a few lines of code. Alternatively, you can register for the search box control's SuggestionsRequested event and build your own list of suggestions that is made up of suggestions you retrieved from another source (like a locally-defined list or a web service).

For code examples that show how to add search suggestions, download the SearchBox control sample. The sample demonstrates how to add search suggestions by using all three possible sources, and how to add suggestions for East Asian languages by using alternate forms of the query text generated by an Input Method Editor (IME). (We recommend using query text alternatives if your app will be used by Japanese or Chinese users.)

Types of search suggestions

There are two types of suggestions your app can display: suggestions that help users refine a query (query suggestions), and suggestions that are actual results of a query (result suggestions). You may choose to display either or both types of suggestions.

If you provide query suggestions and the user selects one, your app should respond by displaying results for the selected, refined query in your app's search results page.

If you provide result suggestions, you must also register a ResultSuggestionChosen event handler so that you can respond when the user selects one of your result suggestions and you can display the result to the user.

Displaying app-provided suggestions

After you obtain suggestions, you display them by adding them to the SearchSuggestionsRequest.SearchSuggestionCollection.

If you choose to display both query suggestions and result suggestions, you should group the suggestions by suggestion type (query or result) and separate the groups using AppendSearchSeparator. Each separator takes the place of a suggestion and must be followed by at least one suggestion, decreasing the number of suggestions that you can display.

The maximum length of all of the textual fields in a suggestion (such as text, detail text, and image alt text) is 512 characters.

To learn more about using suggestions to create a good search experience for your users in Guidelines and checklist for search.

Handling the SuggestionsRequested event asynchronously

If you want to respond to the SuggestionsRequested event asynchronously, you must obtain a SearchSuggestionsRequestDeferral object before you edit the suggestion list. Here's an example from Quickstart: Adding search to an app that shows how:

public async static void SearchBox_SuggestionsRequested(
    SearchBox sender, 
    SearchBoxSuggestionsRequestedEventArgs args)
{

    // This object lets us edit the SearchSuggestionCollection asynchronously. 
    var deferral = args.Request.GetDeferral();

    try { 

        // Retrieve the system-supplied suggestions.
        var suggestions = args.Request.SearchSuggestionCollection;

        var groups = await SampleDataSource.GetGroupsAsync();
        foreach (var group in groups)
        {
            var matchingItems = group.Items.Where(
                item => item.Title.StartsWith(
                    args.QueryText, StringComparison.CurrentCultureIgnoreCase));

            foreach (var item in matchingItems)
            {
                suggestions.AppendQuerySuggestion(item.Title);
            }
        }

        foreach (string alternative in args.LinguisticDetails.QueryTextAlternatives)
        {
            if (alternative.StartsWith(
                args.QueryText, StringComparison.CurrentCultureIgnoreCase))
            {
                suggestions.AppendQuerySuggestion(alternative); 
            }
        }
    }
    finally {
        deferral.Complete();
    }

}

See also

• Quickstart: Adding search to an app