SearchPane.SuggestionsRequested | suggestionsrequested event

Applies to Windows only

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

Syntax

Public Event SuggestionsRequested As TypedEventHandler(Of SearchPane, SearchPaneSuggestionsRequestedEventArgs)

Event information

Delegate TypedEventHandler<SearchPane, SearchPaneSuggestionsRequestedEventArgs>

Remarks

Note  An app can't use both the search box (Windows.UI.Xaml.Controls.SearchBox for Windows Store apps using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows Store apps using JavaScript) and the SearchPane. Using both the search box and the search pane in the same app causes the app to throw an exception with this message: "Cannot create instance of type 'Windows.UI.Xaml.Controls.SearchBox.'"

Suggestions can come from three sources: search history, local files, or from a source specified by the app. Suggestions are grouped by their source and display in the following order in the search pane: search history, local files, and then app-specified sources.

If your app participates in the Search contract and you want your app to display suggestions from sources that you specify, you must register a handler to respond when this event fires. In your SuggestionsRequested event handler, respond by obtaining suggestions and populating the SearchSuggestionCollection based on the user's SearchPaneSuggestionsRequestedEventArgs.QueryText.

Note  If you want to respond to this event asynchronously, you must use SearchPaneSuggestionsRequestedEventArgs.Request.GetDeferral.

Suggestions can't be provided for an empty search box, so this event isn't fired when the user updates the search box to be empty.

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.

Obtaining suggestions

Here are a few examples of sources your app can use to obtain suggestions:

Displaying app-provided suggestions in the search pane

After you obtain suggestions, you display them in the search pane by adding them to the Request.SearchSuggestionCollection.

At most, the search pane can display 5 suggestions. 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.

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

Examples

The Search contract sample demonstrates how to access the searchPane to respond to a suggestionsrequested event.

For Javascript:  To ensure that your app can respond to user queries at any time, make sure your searchPane event handlers are registered in your app's global scope.

No code example is currently available or this language may not be supported.

Additionally, for C#/C++/VB: This example demonstrates how to register handlers for SearchPane events (like SuggestionsRequested) so that your app can respond to user queries at any time. Override OnWindowCreated in App.xaml.cs/App.xaml.cpp/App.xaml.vb to access the SearchPane object and register your SearchPane event handlers.


protected override void OnWindowCreated(WindowCreatedEventArgs args)
{
    // At window creation time, access the SearchPane object and register SearchPane events
    // (like QuerySubmitted, SuggestionsRequested, and ResultSuggestionChosen) so that the app
    // can respond to the user's search queries at any time.

    // Get search pane
    Windows.ApplicationModel.Search.SearchPane searchPane = SearchSearchPane.GetForCurrentView();
    
    // Register event handlers for SearchPane events

    // Register QuerySubmitted event handler
    searchPane.QuerySubmitted += new TypedEventHandler<SearchPane, SearchPaneQuerySubmittedEventArgs>(OnQuerySubmitted);
    
    // Register a SuggestionsRequested if your app displays its own suggestions in the search pane (like from a web service)
    searchPane.SuggestionsRequested += new TypedEventHandler<SearchPane, SearchPaneSuggestionsRequestedEventArgs>(OnSuggestionsRequested);

    // Register a ResultSuggestionChosen if your app displays result suggestions in the search pane
}

Requirements

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

None supported

Namespace

Windows.ApplicationModel.Search
Windows::ApplicationModel::Search [C++]

Metadata

Windows.winmd

See also

Guidelines and checklist for search
Search contract sample
Reference
SearchPane class
SearchPane.ResultSuggestionChosen event
SearchSuggestionCollection class
SearchPaneSuggestionsRequestedEventArgs class
SearchPaneSuggestionsRequest.SearchSuggestionCollection property

 

 

Show:
© 2014 Microsoft