SearchSuggestionManager SearchSuggestionManager SearchSuggestionManager SearchSuggestionManager Class

Definition

Manages access to search suggestions for the in-app SearchBox control.

public : sealed class SearchSuggestionManager : ISearchSuggestionManagerpublic sealed class SearchSuggestionManager : ISearchSuggestionManagerPublic NotInheritable Class SearchSuggestionManager Implements ISearchSuggestionManager// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows Desktop Extension SDK (introduced v10.0.10240.0)
API contract
Windows.ApplicationModel.Search.Core.SearchCoreContract (introduced v1)

Constructors

SearchSuggestionManager() SearchSuggestionManager() SearchSuggestionManager() SearchSuggestionManager()

Initializes a new instance of the SearchSuggestionManager class.

public : SearchSuggestionManager()public SearchSuggestionManager()Public Sub New()// You can use this method in JavaScript.

Properties

SearchHistoryContext SearchHistoryContext SearchHistoryContext SearchHistoryContext

Identifies the context of the search and is used to store the user's search history with the app.

public : PlatForm::String SearchHistoryContext { get; set; }public string SearchHistoryContext { get; set; }Public ReadWrite Property SearchHistoryContext As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The search history context string.

Remarks

The search history context string is used as a secondary key for storing search history. The primary key is the AppId. An app can use the search history context string to store different search histories based on the context of the application.

Changing the value of the SearchHistoryContext property doesn't immediately update the suggestions in the Suggestions property. Call SetQuery to update the Suggestions property.

If you don't set this property, Windows assumes that all searches in your app occur in the same context.

SearchHistoryEnabled SearchHistoryEnabled SearchHistoryEnabled SearchHistoryEnabled

Indicates whether the user's previous searches with the app are automatically tracked and used to provide suggestions.

public : PlatForm::Boolean SearchHistoryEnabled { get; set; }public bool SearchHistoryEnabled { get; set; }Public ReadWrite Property SearchHistoryEnabled As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

True if the user's search history is automatically tracked and used to provide suggestions; otherwise false. The default value is true.

Remarks

Set the SearchHistoryEnabled property to false to opt out of automatic suggestions, so your app can optionally provide its own suggestions instead. If you decide to have your app track its own search history, you should also give the user some control over their history through the Settings charm, like the ability to clear the history.

Changing the value of the SearchHistoryEnabled property doesn't immediately update the suggestions in the Suggestions property. Call SetQuery to update the Suggestions property.

Suggestions Suggestions Suggestions Suggestions

Gets the search suggestions for the current search query.

public : IObservableVector<SearchSuggestion> Suggestions { get; }public IObservableVector<SearchSuggestion> Suggestions { get; }Public ReadOnly Property Suggestions As IObservableVector<SearchSuggestion>// You can use this property in JavaScript.

Methods

AddToHistory(String) AddToHistory(String) AddToHistory(String) AddToHistory(String)

Stores the specified query in the search history.

public : void AddToHistory(PlatForm::String queryText)public void AddToHistory(String queryText)Public Function AddToHistory(queryText As String) As void// You can use this method in JavaScript.
Parameters
queryText
PlatForm::String String String String

The query.

Remarks

The SearchBox control calls the AddToHistory method when the query entry is committed, to add it to the current history context.

Calling the AddToHistory method doesn't immediately update the suggestions in the Suggestions property. Call SetQuery to update the Suggestions property.

See Also

AddToHistory(String, String) AddToHistory(String, String) AddToHistory(String, String) AddToHistory(String, String)

Stores the specified query and input language in the search history.

public : void AddToHistory(PlatForm::String queryText, PlatForm::String language)public void AddToHistory(String queryText, String language)Public Function AddToHistory(queryText As String, language As String) As void// You can use this method in JavaScript.
Parameters
queryText
PlatForm::String String String String

The query.

language
PlatForm::String String String String

The input language. The input language ensures that the query string is displayed in the search history for the correct language.

Remarks

The SearchBox control calls the AddToHistory method when the query entry is committed, to add it to the current history context.

Calling the AddToHistory method doesn't immediately update the suggestions in the Suggestions property. Call SetQuery to update the Suggestions property.

See Also

ClearHistory() ClearHistory() ClearHistory() ClearHistory()

Clears all search history contexts for the current app.

public : void ClearHistory()public void ClearHistory()Public Function ClearHistory() As void// You can use this method in JavaScript.

SetLocalContentSuggestionSettings(LocalContentSuggestionSettings) SetLocalContentSuggestionSettings(LocalContentSuggestionSettings) SetLocalContentSuggestionSettings(LocalContentSuggestionSettings) SetLocalContentSuggestionSettings(LocalContentSuggestionSettings)

Specifies whether suggestions based on local files are added automatically to the Suggestions collection, and defines the criteria that Windows uses to locate and filter these suggestions.

public : void SetLocalContentSuggestionSettings(LocalContentSuggestionSettings settings)public void SetLocalContentSuggestionSettings(LocalContentSuggestionSettings settings)Public Function SetLocalContentSuggestionSettings(settings As LocalContentSuggestionSettings) As void// You can use this method in JavaScript.
Parameters

Remarks

When local content suggestions are enabled, Windows provides search suggestions from the user's local files as the user enters query text. For example, a picture application can configure local content suggestions so that search suggestions come only from a particular kind of image file that is stored in the user's picture library.

Changing the value of the SetLocalContentSuggestionSettings property doesn't immediately update the suggestions in the Suggestions property. Call SetQuery to update the Suggestions property.

SetQuery(String) SetQuery(String) SetQuery(String) SetQuery(String)

Assigns the current search query.

public : void SetQuery(PlatForm::String queryText)public void SetQuery(String queryText)Public Function SetQuery(queryText As String) As void// You can use this method in JavaScript.
Parameters
queryText
PlatForm::String String String String

The query.

Remarks

The SearchBox control calls the SetQuery method when the query text changes.

See Also

SetQuery(String, String) SetQuery(String, String) SetQuery(String, String) SetQuery(String, String)

Assigns the current search query with the specified input language.

public : void SetQuery(PlatForm::String queryText, PlatForm::String language)public void SetQuery(String queryText, String language)Public Function SetQuery(queryText As String, language As String) As void// You can use this method in JavaScript.
Parameters
queryText
PlatForm::String String String String

The query.

language
PlatForm::String String String String

The input language.

Remarks

The SearchBox control calls the SetQuery method when the query text changes.

See Also

SetQuery(String, String, SearchQueryLinguisticDetails) SetQuery(String, String, SearchQueryLinguisticDetails) SetQuery(String, String, SearchQueryLinguisticDetails) SetQuery(String, String, SearchQueryLinguisticDetails)

Assigns the current search query with the specified input language and Input Method Editor (IME) info.

public : void SetQuery(PlatForm::String queryText, PlatForm::String language, SearchQueryLinguisticDetails linguisticDetails)public void SetQuery(String queryText, String language, SearchQueryLinguisticDetails linguisticDetails)Public Function SetQuery(queryText As String, language As String, linguisticDetails As SearchQueryLinguisticDetails) As void// You can use this method in JavaScript.
Parameters
queryText
PlatForm::String String String String

The query.

language
PlatForm::String String String String

The input language.

linguisticDetails
SearchQueryLinguisticDetails SearchQueryLinguisticDetails SearchQueryLinguisticDetails SearchQueryLinguisticDetails

Info about the query text that the user enters through an Input Method Editor (IME).

Remarks

The SearchBox control calls the SetQuery method when the query text changes.

See Also

Events

RequestingFocusOnKeyboardInput RequestingFocusOnKeyboardInput RequestingFocusOnKeyboardInput RequestingFocusOnKeyboardInput

Raised when the user presses a key that initiates type-to-search.

public : event TypedEventHandler RequestingFocusOnKeyboardInput<SearchSuggestionManager,  RequestingFocusOnKeyboardInputEventArgs>public event TypedEventHandler RequestingFocusOnKeyboardInput<SearchSuggestionManager,  RequestingFocusOnKeyboardInputEventArgs>Public Event RequestingFocusOnKeyboardInput<SearchSuggestionManager,  RequestingFocusOnKeyboardInputEventArgs>// You can use this event in JavaScript.

Remarks

The app's UI handles this event by setting focus to the search box control so that subsequent keystrokes result in entering a search query.

SuggestionsRequested SuggestionsRequested SuggestionsRequested SuggestionsRequested

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

public : event TypedEventHandler SuggestionsRequested<SearchSuggestionManager,  SearchSuggestionsRequestedEventArgs>public event TypedEventHandler SuggestionsRequested<SearchSuggestionManager,  SearchSuggestionsRequestedEventArgs>Public Event SuggestionsRequested<SearchSuggestionManager,  SearchSuggestionsRequestedEventArgs>// You can use this event in JavaScript.

Remarks

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 QueryText.

Note

If you want to respond to this event asynchronously, you must get a deferral from the Request property.

Suggestions can't be provided for an empty search box, so this event isn't raised 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 box control

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

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.