SearchSuggestionManager
SearchSuggestionManager
SearchSuggestionManager
SearchSuggestionManager
Class
Definition
public : sealed class SearchSuggestionManager : ISearchSuggestionManagerpublic sealed class SearchSuggestionManager : ISearchSuggestionManagerPublic NotInheritable Class SearchSuggestionManager Implements ISearchSuggestionManager// You can use this class in JavaScript.
- Attributes
| 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.
- 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.
- 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.
- settings
- LocalContentSuggestionSettings LocalContentSuggestionSettings LocalContentSuggestionSettings LocalContentSuggestionSettings
The new settings for local content suggestions.
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.
- 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.
- 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.
- 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:
- From an app-defined, static, local list
- From a URL that supports suggestions in OpenSearch format
- From a URL that supports suggestions in XML search suggestions format
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.