SearchPane class

Applies to Windows only

Represents and manages the search pane that opens when a user activates the Search charm. The search pane provides a consistent, touch-friendly search box and optional search suggestions.

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.'"

Syntax


public sealed class SearchPane

Attributes

[MarshalingBehavior(Standard)]
[Muse()]
[Version(0x06020000)]

Members

The SearchPane class has these types of members:

Events

The SearchPane class has these events.

EventDescription
QueryChanged Fires when the user changes the text in the search box.
QuerySubmitted Fires when the user submits the text in the search box and the app needs to display search results.
ResultSuggestionChosen Fires when the user selects one of the suggested results that was provided by the app and displayed in the search pane.
SuggestionsRequested Fires when the user's query text changes and the app needs to provide new suggestions to display in the search pane.
VisibilityChanged Fires when the user opens or closes the search pane.

 

Methods

The SearchPane class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
GetForCurrentView Retrieves an instance of the search pane from which users can search within the app.
HideThisApplication Hides the current app's UI.
SetLocalContentSuggestionSettings 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.
Show Shows the search pane.
Show(String) Shows the search pane with the specified initial query string.
TrySetQueryText Attempts to set the text in the search box of the search pane.

 

Properties

The SearchPane class has these properties.

PropertyAccess typeDescription

Language

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

PlaceholderText

Read/writeThe placeholder text in the search box when the user hasn't entered any characters.

QueryText

Read-onlyThe current text in the search box of the search pane.

SearchHistoryContext

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

SearchHistoryEnabled

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

ShowOnKeyboardInput

Read/writeGets or sets whether the user can open the search pane by typing.

Visible

Read-onlyIndicates whether the search pane is open.

 

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 search 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 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
};

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

None supported

Namespace

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

Metadata

Windows.winmd

See also

Search contract sample
Quickstart: Adding search
How to handle app activation (JS)
How to activate an app (C#/C++/VB)
Reference
SearchPane.GetForCurrentView method
Windows.ApplicationModel.Activation.ActivationKind enum
Windows.ApplicationModel.Activation.SearchActivatedEventArgs class
Windows.ApplicationModel.Core.CoreApplicationView.Activated event

 

 

Show:
© 2014 Microsoft. All rights reserved.