SearchControl Class

The control that provides the search and filter functionality for the attached object.

Assembly: DevExpress.XtraEditors.v18.2.dll

Declaration

C#
VB.NET

[SmartTagFilter(typeof(SearchControlFilter))]
[ToolboxBitmap(typeof(ToolboxIconsRootNS), "SearchControl")]
public class SearchControl :
    MRUEdit,
    ISearchControl

<SmartTagFilter(GetType(SearchControlFilter))>
<ToolboxBitmap(GetType(ToolboxIconsRootNS), "SearchControl")>
Public Class SearchControl
    Inherits MRUEdit
    Implements ISearchControl

The following members return SearchControl objects:

Remarks

The SearchControl can receive a textual search request from an end-user and filter the attached object based on this request. The SearchControl can be attached to the following controls, which support the ISearchControlClient interface:

To specify the attached control, use the SearchControl.Client property.

The figure below shows a sample SearchControl contained in the FlyoutPanel that appears at the top right corner of the attached GridControl.

SearchControl_InGridQuery

Specific controls, to which the SearchControl can be attached, can display data from multiple data source fields (for instance, the GridControl contains columns that are bound to different fields). By default, the SearchControl searches in all available fields (columns). You can use the SearchControl.QueryIsSearchColumn event, which is raised before a search, to specify the fields (columns) in which the search should be performed. In the figure displayed above, the search is performed against the Ship Country column.

The control’s SearchControl.Properties provide access to the RepositoryItemSearchControl object which stores miscellaneous settings applied to the SearchControl:

the RepositoryItemSearchControl.ShowDefaultButtonsMode property — allows you to specify the mode in which the predefined Search and Clear buttons are displayed,
the RepositoryItemSearchControl.ShowMRUButton property — allows you to specify whether to show the dropdown button that invokes the list of most recently used search requests,
the RepositoryItemSearchControl.Buttons collection — allows you to add custom buttons to the SearchControl,
the RepositoryItemSearchControl.AllowAutoApply and RepositoryItemSearchControl.FindDelay properties — allow you to customize an automatic search,
the RepositoryItemTextEdit.NullValuePrompt and RepositoryItemSearchControl.NullValuePromptShowForEmptyValue properties — allow you to customize the text displayed grayed out when the search box is empty.

The RepositoryItemSearchControl object, when it is created as a standalone object, enables you to embed the SearchControl into container controls (XtraGrid, XtraVerticalGrid, Tree List and XtraBars). So, the SearchControl can be placed on a menu bar or ribbon page group as an in-place editor. To accomplish this at design time, drop the BarManager or RibbonControl on the form and add the SearchControl to a bar as in the following picture.

SearchControl_OnBar

In code, first - create a BarEditItem object, which is designed to store editors within bars, and assign a RepositoryItemSearchControl instance to its BarEditItem.Edit property. Then, add the created BarEditItem to a bar. This can be done as follows. It is assumed that the BarManager on your form contains a Bar named bar1.

C#
VB.NET


using DevExpress.XtraBars;
using DevExpress.XtraEditors.Repository;

RepositoryItemSearchControl repositoryItemSearchControl1 = new RepositoryItemSearchControl();
BarEditItem barEditItem1 = new BarEditItem();
barEditItem1.Edit = repositoryItemSearchControl1;
bar1.AddItem(barEditItem1);


Imports DevExpress.XtraBars
Imports DevExpress.XtraEditors.Repository

Dim repositoryItemSearchControl1 As New RepositoryItemSearchControl()
Dim barEditItem1 As New BarEditItem()
barEditItem1.Edit = repositoryItemSearchControl1
bar1.AddItem(barEditItem1)

The result is shown in the picture below.

SearchControl_WithinBar

To specify the control through which a search is performed by an in-place SearchControl, use the RepositoryItemSearchControl.Client property.

To learn more on how repository items are used to embed editors to container controls such as XtraGrid, XtraVerticalGrid, Tree List and XtraBars, see the Repositories and Repository Items topic.

Search Syntax

In its simplest form, a search criterion consists of a single word. If you want to search for a string containing a space character, specify this string in quotation marks. Without quotation marks, words separated by the space character are treated as individual conditions.

You can search against a specific column by preceding a search string with the column’s display name plus a colon character.

ColumnDisplayName:SearchString

Instead of the complete name, it is possible to partially specify the display name, using the initial characters of a column’s display name. A search will be performed against the first column whose display name starts with the specified substring. If you want to search against a column whose display caption contains space characters, specify the column’s display caption in quotation marks.

If the search string contains multiple conditions separated by space characters, and at least one condition defines a search against a specific column, only records that match all of these conditions are shown (i.e., the conditions are combined by the AND logical operator). If there is no column specification, records that match at least one of these conditions are shown (i.e., the conditions are combined by the OR logical operator).

Precede a condition with “+” to display only records that match this condition. The “+” specifier allows you to implement the logical AND operator. There should be no space character between the “+” sign and the condition.

Precede a condition with “-“ to exclude records that match this condition from the result set. There should be no space between the “-“ sign and the condition.

Examples

Search Criteria	Description
`register`	Selects records that contain the “register” string in any search column.
`check register Dave`	Selects records that contain either “check” OR “register” OR “Dave” strings in any search column.
`"check register"`	Selects records that contain “check register” in any search column.
`screen +"Richard Fisher"`	Selects records that contain both “screen” AND “Richard Fisher” in search columns.
`Product:Tofu Seattle`	Selects records that contain “Tofu” in the column that starts with “Product”, AND also contain “Seattle” in any search column.
`data +entry -mark`	Selects records that contain both “data” AND “entry” in search columns, excluding records that contain “mark”.
`menu mask -file`	Selects records that contain “menu” OR “mask”, excluding records that contain “file”.
`From:Roller Subj:"currency mask"`	Selects records that contain “Roller” in the column that starts with “From”, AND also contain “currency mask” in the column that starts with “Subj”.
`import -From:Steve`	Selects records that contain “import” in any search column, excluding records that contain “Steve” in the column that starts with “From”.

Note

Searches performed using a Find Panel are case insensitive.

Note

Searches via the Find Panel for case-sensitive data sources in Server Mode are not supported. The Find Panel always converts a search string to lower-case before searching.

Note

When the SearchControl is attached to a ListBoxControl, you can use the RepositoryItemSearchControl.FilterCondition property to specify the comparison operator to combine individual filter conditions in the search box.