Search Panel
- 6 minutes to read
Windows UI View supports the search panel out-of-the-box. The panel allows your end-users to search for the required content throughout content containers and tiles and instantly navigate to it. In this topic, you will learn how to use the search panel and tweak it for your WindowsUIView-based applications.
The Search Panel is enabled out-of-the-box and invoked by pressing the key combination assigned to the ISearchPanelProperties.Shortcut property (Ctrl+F by default). To close the panel, you can click anywhere outside it or press the Esc key. By default, the panel is docked to the right edge of the Windows UI View. You can dock it to the left edge by setting the ISearchPanelProperties.AnchorType property to SearchPanelAnchor.Left.
Visual Elements
The search panel displays the following visual elements.
- Search Bar - a text box for the input of text to be searched for on the internet and in databases. You can automatically search for the entered text after a certain time interval set by using the ISearchControlProperties.FindDelay property. The text box displays the ISearchControlProperties.NullValuePrompt text if empty.
- Find button - searches for the text entered in the Search Bar.
- Clear button - a button that erases the text currently entered in the search bar. This button’s visibility depends on the ISearchControlProperties.ClearButtonShowMode property value, and can be set to always visible, visible only if there is any text to erase or never visible.
Drop-down panel - a drop-down for the Search Bar that displays recent search queries similar to the currently entered text. End-users can remove specific drop-down items by clicking the remove button to their right (see the image below).
- Search results pane - a list of found elements, grouped by types of places where these elements were found. There can be three possible groups: active container (the currently visible content container), children (content containers owned by the currently visible containers) and other groups (other content containers). By default, each group displays five search results. You can modify this number by setting the VisibleRowCount property to the required value. If more items were found, end-users can click the group button to expand this group to see the complete list.
Concepts
After an end-user has entered the desired text and clicked the Find button, the panel searches for this text in the following places:
- content container titles (the BaseContentContainer.Caption property);
- document captions and headers (the BaseDocument.Caption and BaseDocument.Header properties);
- tile elements (the BaseTile.Elements collection);
- search tags (see the group below);
- document content, if this content was assigned to the e.Content property when handling the WindowsUIView.CustomizeSearchItems event.
The search is not performed in navigation bars, container actions, etc.
Any tile, document or content container is included in the search. To exclude a specific element from it, set its ExcludeFromSearch property to true (the BaseContentContainer.ExcludeFromSearch, BaseTile.ExcludeFromSearch and Document.ExcludeFromSearch properties).
To completely disable the Search Panel, handle the WindowsUIView.SearchPanelShowing event and set its e.Cancel parameter to true.
Search Tags
Documents, Tiles and Content Containers support search tags - collections of string values used to identify these objects. To access search tag collections in code, use the Document.SearchTags, BaseTile.SearchTags and BaseContentContainer.SearchTags properties respectively. At design-time, you can do the same by locating these properties in the Visual Studio’s Properties window and using the String Collection Editor to modify tag collections accessed through these properties.
Search Operators
End-users can use search operators to perform advanced searches. For example, using the colon operator, end-users are able to input the search string in the ‘parameter: text’ format where the word parameter specifies the place to search for the text. There are three possible parameters:
- text (e.g., text: employees) - specifies the search panel to search for the target text only within content container and document titles;
- tag (e.g., tag: shared) - forces the search panel to look for the text only within the search tags;
- content (e.g., content: Washington) - the search panel will return only documents whose content includes the desired text. This parameter is initially not in effect, since Documents may contain a lot of irrelevant textual content that should not be checked for the desired text. Thus, you have to handle the WindowsUIView.CustomizeSearchItems event and assign an IEnumerable object with a string value that will be considered to be document content (see the Customizing Search Results section below).
Other operators are quite standard and you may know them from online search engines. These are quote characters that force the search panel to search for the whole quoted string, and +/- operators that allow you to add or remove the results that include the target text.
Search operators work in the same way as our Data Grid‘s find panel. You can see detailed examples in this help article.
Customizing Search Results
You can handle the WindowsUIView.CustomizeSearchItems event to manually set images and subtitles for search results, as well as the search content for the entire application.
The event handler receives an argument of the CustomizeSearchItemsEventArgs type, which provides the properties listed below:
- e.Image - gets or sets the search item’s glyph;
- e.SubTitle - allows you to change the search item’s subtitle displayed below its name. By default, the subtitle points to a parent container related to this search item;
- e.SourceContainer - a content container that owns the element (document, tile) related to this search item;
- e.Source - returns the element related to this search item. If this element is a content container, the e.Source and e.SourceContainer parameters are equal.
The code below modifies search items subtitles depending on whether their related elements are documents, tiles or content containers. For search items corresponding to documents, their parent container captions are additionally displayed in brackets. The code also turns off the Glyph Skinning feature for all search item icons.
void OnCustomizeSearchItems(object sender, CustomizeSearchItemsEventArgs e) {
e.Image = GetResourceImage(e.Source);
if(e.Image != null)
e.AllowGlyphSkinning = Utils.DefaultBoolean.False;
if (e.Source is Document) {
e.SubTitle = string.Format("Document ({0})", e.SourceContainer.Caption);
}
if (e.Source is IContentContainer)
e.SubTitle = "Container";
if (e.Source is BaseTile)
e.SubTitle = "Tile";
}
The result is illustrated in the figure below.
- e.Content - gets or sets the search content. This parameter is only indirectly related to customizing search items, but affects the entire search process. You can assign to the Content property any text-containing object (e.g., grid column) in which the panel will search for the required text in addition to element captions and search tags. This step is required since the search panel cannot ‘look into’ document content itself, so you have to manually ‘show’ the search panel where exactly it should search for the required text.