SearchPane SearchPane SearchPane SearchPane Class

Definition

Deprecated. Use the SearchBox (XAML) or the WinJS.UI.SearchBox (HTML) control instead. Represents and manages the search pane that opens when a user activates the Search charm.

Note

An app can't use both the search box (SearchBox for XAMLUniversal Windows Platform (UWP) app, WinJS.UI.SearchBox for HTMLUniversal Windows Platform (UWP) app) 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.'"

public sealed class SearchPanepublic sealed class SearchPanePublic NotInheritable Class SearchPanepublic sealed class SearchPane
Attributes
Windows 10 requirements
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)

Remarks

This object is available to apps that participate in the Search contract; you can learn more about adding the Search contract to your app in Quickstart: Adding search. In order to provide users with search results, you must add code to your activated event handler that responds when your app is activated for search. To learn more about responding to ActivationKind activation events see WebUISearchActivatedEventArgs (JavaScript) or SearchActivatedEventArgs (C#/C++/VB).

You can see code examples that demonstrate how to respond to search events and manage the search pane in the Search contract sample.

Examples

For C#/C++/VB: This example demonstrates how to ensure that your app can respond to user queries at any time by overriding OnWindowCreated(WindowCreatedEventArgs) in App.xaml.cs/App.xaml.cpp/App.xaml.vb to access the SearchPane object and register handlers for SearchPane events (like QuerySubmitted ).

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)
    // Register a ResultSuggestionChosen if your app uses result suggestions in the search pane    
}

For JavaScript: This example demonstrates how to access the SearchPane to register a QuerySubmitted event handler.

Note

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.


// Register event handler for QuerySubmitted
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onquerysubmitted = function (eventObject) {
    // Respond to query and perform search
};

Properties

Language Language Language Language

The Internet Engineering Task Force (IETF) language tag (BCP 47 standard) that identifies the language currently associated with the user's text input device.

public string Language { get; }public string Language { get; }Public ReadOnly Property Language As stringpublic string Language { get; }
Value
string string string string

The Internet Engineering Task Force (IETF) BCP 47 standard language tag.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

PlaceholderText PlaceholderText PlaceholderText PlaceholderText

The placeholder text in the search box when the user hasn't entered any characters.

public string PlaceholderText { get; set; }public string PlaceholderText { get; set; }Public ReadWrite Property PlaceholderText As stringpublic string PlaceholderText { get; set; }
Value
string string string string

The placeholder text to display in the search box.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

You can use the placeholder text to give the user an indication about what he or she can search for.

If the placeholder text is too long to fit in the search box, the system truncates the text without raising an exception.

QueryText QueryText QueryText QueryText

The current text in the search box of the search pane.

public string QueryText { get; }public string QueryText { get; }Public ReadOnly Property QueryText As stringpublic string QueryText { get; }
Value
string string string string

The current query text. If the search pane was not used, this is an empty string.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

You can get the query text at any time, even if the search pane isn't open.

SearchHistoryContext SearchHistoryContext SearchHistoryContext SearchHistoryContext

A string that identifies the context of the search and is used to store the user's search history with the app.

public string SearchHistoryContext { get; set; }public string SearchHistoryContext { get; set; }Public ReadWrite Property SearchHistoryContext As stringpublic string SearchHistoryContext { get; set; }
Value
string string string string

The search history context string.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

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.

If you don't set this property, Windows assumes that all searches in your app occur in the same context. If you update this property while the search pane is open with suggestions showing, the changes won't take effect until the user enters the next character.

SearchHistoryEnabled SearchHistoryEnabled SearchHistoryEnabled SearchHistoryEnabled

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

public bool SearchHistoryEnabled { get; set; }public bool SearchHistoryEnabled { get; set; }Public ReadWrite Property SearchHistoryEnabled As boolpublic bool SearchHistoryEnabled { get; set; }
Value
bool 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.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

You can set this property to false to opt out of automatic suggestions; your app can optionally provide its own suggestions to users 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.

If you set this property while the search pane is open, the change won't take effect until the user enters the next character of their query.

ShowOnKeyboardInput ShowOnKeyboardInput ShowOnKeyboardInput ShowOnKeyboardInput

Gets or sets whether the user can open the search pane by typing.

public bool ShowOnKeyboardInput { get; set; }public bool ShowOnKeyboardInput { get; set; }Public ReadWrite Property ShowOnKeyboardInput As boolpublic bool ShowOnKeyboardInput { get; set; }
Value
bool bool bool bool

True if the user can type to search. Otherwise, false.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

To learn more about when you should let users type to search, see Guidelines and checklist for search.

Visible Visible Visible Visible

Indicates whether the search pane is open.

public bool Visible { get; }public bool Visible { get; }Public ReadOnly Property Visible As boolpublic bool Visible { get; }
Value
bool bool bool bool

True if the search pane is being displayed; otherwise false.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

Methods

GetForCurrentView() GetForCurrentView() GetForCurrentView() GetForCurrentView()

Retrieves an instance of the search pane from which users can search within the app.

public static SearchPane GetForCurrentView()public static SearchPane GetForCurrentView()Public Static Function GetForCurrentView() As SearchPanepublic static SearchPane GetForCurrentView()
Returns

An instance of the search pane, which provides a consistent, touch-friendly search box and optional search suggestions for searching within the current application.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

Examples

For C#/C++/VB: This example demonstrates how to ensure that your app can respond to user queries at any time by overriding OnWindowCreated(WindowCreatedEventArgs) in App.xaml.cs/App.xaml.cpp/App.xaml.vb to access the SearchPane object and register handlers for SearchPane events (like QuerySubmitted ).

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)
    // Register a ResultSuggestionChosen if your app uses result suggestions in the search pane    
}

For JavaScript: This example demonstrates how to access the SearchPane to register a QuerySubmitted event handler.

Note

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.


// Register event handler for QuerySubmitted
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onquerysubmitted = function (eventObject) {
    // Respond to query and perform search
};

HideThisApplication() HideThisApplication() HideThisApplication() HideThisApplication()

Hides the current app's UI.

public static void HideThisApplication()public static void HideThisApplication()Public Static Function HideThisApplication() As voidpublic static void HideThisApplication()
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

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

Specifies whether suggestions based on local files are automatically displayed in the search pane, 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 voidpublic void SetLocalContentSuggestionSettings(LocalContentSuggestionSettings settings)
Parameters
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

When local content suggestions are enabled, Windows will provide 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.

Examples

The Search contract sample demonstrates how to customize local suggestions by restricting the locations and kinds of files that the suggestions are based on.

Tip

You should add this code to your app's global scope and run it as soon as your app is launched.

// Have Windows provide suggestions from local files.
// This code should be placed in your apps global scope and run as soon as your app is launched.
var settings = new LocalContentSuggestionSettings();
settings.Enabled = true;
if (isLocal)
{
    settings.Locations.Add(KnownFolders.MusicLibrary);
    settings.AqsFilter = "kind:Music";
}
SearchPane.GetForCurrentView().SetLocalContentSuggestionSettings(settings);
var settings = new Windows.ApplicationModel.Search.LocalContentSuggestionSettings();
settings.enabled = true;
settings.locations.append(Windows.Storage.KnownFolders.musicLibrary);
settings.aqsFilter = "kind:=music";

Windows.ApplicationModel.Search.SearchPane.getForCurrentView().setLocalContentSuggestionSettings(settings);

In the example, suggestions are restricted to one kind of file, music files, using an Advanced Query Syntax (AQS) string. Two of the most common Advanced Query Syntax (AQS) filters restrict based on file kind, like "kind:=.music" in the example; and based on file name extension, like "ext:=.mp3". You can learn more about Advanced Query Syntax (AQS) in .

Show() Show() Show() Show()

Shows the search pane.

public void Show()public void Show()Public Function Show() As voidpublic void Show()
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

If the search pane is already being shown, this function gives focus to the search pane.

Show(String) Show(String) Show(String) Show(String)

Shows the search pane with the specified initial query string.

public void Show(String query)public void Show(String query)Public Function Show(query As String) As voidpublic void Show(String query)
Parameters
query
System.String System.String System.String System.String

The initial query string.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

If the search pane is already being shown, this function gives focus to the search pane.

TrySetQueryText(String) TrySetQueryText(String) TrySetQueryText(String) TrySetQueryText(String)

Attempts to set the text in the search box of the search pane.

public bool TrySetQueryText(String query)public bool TrySetQueryText(String query)Public Function TrySetQueryText(query As String) As boolpublic bool TrySetQueryText(String query)
Parameters
query
System.String System.String System.String System.String

The query text to show in the search pane's search box.

Returns
bool bool bool bool

True if the search box text was set successfully. Otherwise, false.

Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

If you have an in-app search box, use this method to maintain consistency between the search pane and your search box. Most apps should reply on the search pane instead of using in-app search UI. To learn more, see Guidelines and checklist for search.

Events

QueryChanged QueryChanged QueryChanged QueryChanged

Fires when the user changes the text in the search box.

public event TypedEventHandler QueryChangedpublic event TypedEventHandler QueryChangedPublic Event QueryChangedpublic event TypedEventHandler QueryChanged
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

Register to be notified when this event fires by adding an event listener to the SearchPane and assigning a handler function for the event. You can access information about the event with the SearchPaneQueryChangedEventArgs object that is passed to your event handler.

QuerySubmitted QuerySubmitted QuerySubmitted QuerySubmitted

Fires when the user submits the text in the search box and the app needs to display search results.

public event TypedEventHandler QuerySubmittedpublic event TypedEventHandler QuerySubmittedPublic Event QuerySubmittedpublic event TypedEventHandler QuerySubmitted
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

If your app participates in the Search contract, register an event handler to respond when this event fires. In your QuerySubmitted event handler, respond by taking the user to your search results page and populating it with results based on the @Windows.ApplicationModel.Search.SearchPaneQuerySubmittedEventArgs.@Windows.ApplicationModel.Search.SearchPaneQuerySubmittedEventArgs.QueryText.

Examples

For C#/C++/VB: This example demonstrates how to ensure that your app can respond to user queries at any time by overriding OnWindowCreated(WindowCreatedEventArgs) in App.xaml.cs/App.xaml.cpp/App.xaml.vb to access the SearchPane object and register handlers for SearchPane events (like QuerySubmitted ).

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 = SearchPane.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)
    // Register a ResultSuggestionChosen if your app uses result suggestions in the search pane    
}

For JavaScript: This example demonstrates how to access the SearchPane to register a QuerySubmitted event handler.

Note

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.


// Register event handler for QuerySubmitted
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onquerysubmitted = function (eventObject) {
    // Respond to query and perform search
};

ResultSuggestionChosen ResultSuggestionChosen ResultSuggestionChosen ResultSuggestionChosen

Fires when the user selects one of the suggested results that was provided by the app and displayed in the search pane.

public event TypedEventHandler ResultSuggestionChosenpublic event TypedEventHandler ResultSuggestionChosenPublic Event ResultSuggestionChosenpublic event TypedEventHandler ResultSuggestionChosen
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

If your app participates in the Search contract and displays suggestions for possible results in the search pane, you should register an event handler to respond when this event fires. In your ResultSuggestionChosen event handler, respond by getting the @Windows.ApplicationModel.Search.SearchPaneResultSuggestionChosenEventArgs.@Windows.ApplicationModel.Search.SearchPaneResultSuggestionChosenEventArgs.Tag of the chosen result and using it to take the user to the result in your app UI.

Note

If you want to display result suggestions, you must also listen for and handle the SuggestionsRequested event.

Examples

For C#/C++/VB: This example demonstrates how to ensure that your app can respond to user queries at any time by overriding OnWindowCreated(WindowCreatedEventArgs) in App.xaml.cs/App.xaml.cpp/App.xaml.vb to access the SearchPane object and register handlers for SearchPane events (like QuerySubmitted and ResultSuggestionChosen ).

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
    searchPane.ResultSuggestionChosen += new TypedEventHandler<SearchPane, SearchPaneResultSuggestionChosenEventArgs>(OnResultSuggestionChosen);

}

For JavaScript: This example demonstrates how to access the SearchPane to register a ResultSuggestionChosen event handler.

Note

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.


// Register event handler for ResultSuggestionChosen
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onresultsuggestionchosen = function (eventObject) {
    // Respond when user chooses a result suggestion
};

SuggestionsRequested SuggestionsRequested SuggestionsRequested SuggestionsRequested

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

public event TypedEventHandler SuggestionsRequestedpublic event TypedEventHandler SuggestionsRequestedPublic Event SuggestionsRequestedpublic event TypedEventHandler SuggestionsRequested
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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 @Windows.ApplicationModel.Search.SearchPaneSuggestionsRequestedEventArgs.@Windows.ApplicationModel.Search.SearchPaneSuggestionsRequestedEventArgs.QueryText.

Note

If you want to respond to this event asynchronously, you must use @Windows.ApplicationModel.Search.SearchPaneSuggestionsRequestedEventArgs.@Windows.ApplicationModel.Search.SearchPaneSuggestionsRequestedEventArgs.Request.@Windows.ApplicationModel.Search.SearchPaneSuggestionsRequest.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 @Windows.ApplicationModel.Search.SearchPaneSuggestionsRequestedEventArgs.Request.@Windows.ApplicationModel.Search.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(String). 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.

private 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
    {
        var request = e.Request;
        var linguisticDetails = e.LinguisticDetails;
        foreach (string alternative in linguisticDetails.QueryTextAlternatives)
        {
            foreach (string suggestion in suggestionList)
            {
                if (suggestion.StartsWith(alternative, StringComparison.CurrentCultureIgnoreCase))
                {
                    // Add suggestion to Search Pane
                    request.SearchSuggestionCollection.AppendQuerySuggestion(suggestion);

                    // Break since the Search Pane can show at most 5 suggestions
                    if (request.SearchSuggestionCollection.Size >= MainPage.SearchPaneMaxSuggestions)
                    {
                        break;
                    }
                }
            }

            // Break since the Search Pane can show at most 5 suggestions
            if (request.SearchSuggestionCollection.Size >= MainPage.SearchPaneMaxSuggestions)
            {
                break;
            }
        }

        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);
        }
    }
}
// Register the onsuggestionsrequested event in your apps global scope, for example default.js, so that it is registered as soon as your app is launched.
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onsuggestionsrequested = function (eventObject) {
    var queryText = eventObject.queryText, suggestionRequest = eventObject.request, linguisticDetails = eventObject.linguisticDetails;

    var queryAlternatives = linguisticDetails.queryTextAlternatives;
    var maxNumberOfSuggestions = 5;
    for (var i = 0, len = queryAlternatives.length, done = false; i < len && !done; i++) {
        // toLowerCase not necessary for East Asian languages. Preserves compatibility when non East Asian suggestions are mixed in with East Asian suggestions.
        var alternative = queryAlternatives[i].toLowerCase();
        for (var j = 0, suggestionLength = suggestionList.length; j < suggestionLength; j++) {
            if (suggestionList[j].substr(0, alternative.length).toLowerCase() === alternative) {
                suggestionRequest.searchSuggestionCollection.appendQuerySuggestion(suggestionList[j]);
                if (suggestionRequest.searchSuggestionCollection.size === maxNumberOfSuggestions) {
                    done = true;
                    break;
                }
            }
        }
    }

    // Construct list of alternatives so we can output them.
    var alternatives = "";
    for (var k = 0, alternativeCount = queryAlternatives.length; k < alternativeCount; k++) {
        alternatives += queryAlternatives[k];
    }
    if (suggestionRequest.searchSuggestionCollection.size > 0) {
        WinJS.log && WinJS.log("Suggestions provided for query: " + queryText + "\nUsing alternatives: " + alternatives, "sample", "status");
    } else {
        WinJS.log && WinJS.log("No suggestions provided for query: " + queryText + "\nUsing alternatives: " + alternatives, "sample", "status");
    }
};
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
}

VisibilityChanged VisibilityChanged VisibilityChanged VisibilityChanged

Fires when the user opens or closes the search pane.

public event TypedEventHandler VisibilityChangedpublic event TypedEventHandler VisibilityChangedPublic Event VisibilityChangedpublic event TypedEventHandler VisibilityChanged
Attributes
Additional features and requirements
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)

Remarks

Note

An app can't use both the search box (SearchBox for Windows Store app using C++, C#, or Visual Basic, WinJS.UI.SearchBox for Windows app 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.'"

Register to be notified when this event fires by adding an event listener to the SearchPane and assigning a handler function for the event. You can access information about the event with the SearchPaneVisibilityChangedEventArgs object that is passed to your event handler.