Find Panel

• Mar 21, 2024
• 6 minutes to read

Overview

The grid can display a find panel that enables users to search for keywords in visible columns.

Run Demo: Find Panel

Keyboard Operations

Filter and Search Modes

• Press Ctrl+F to open the find panel.
• Press Esc once to clear the panel, and press it again to close it.
• Press the Down Arrow key to move focus from the panel to the grid.

If the InHeaderSearchMode option is set to TextFilter, the Ctrl+F shortcut opens the focused column’s header search box. If the focused column’s AllowInHeaderSearch option is disabled, the Ctrl+F shortcut opens the find panel.

Note

The Find Panel and In-Header Search are mutually exclusive options. They are not intended to be used together.

Search Mode Only

To go to the next result, press one of the following shortcuts:

• F3
• Enter (only if the find panel is focused)

To go to the previous result, press one of the following shortcuts:

• Shift+F3
• Alt/Ctrl/Shift+Enter (only if the find panel is focused)

Note

Enable the ColumnViewOptionsFind.AllowFindInExpandedDetails option to allow users to search data in expanded detail views.

Tip

Note that GridLookUpEdit does not support the Find Panel. Use SearchLookUpEdit instead.

Options

The ColumnView.OptionsFind property provides access to find panel options.

Behavior: Filter or Search

The ColumnView.OptionsFind.Behavior property specifies how to show search results:

• Filter — hides records that do not match the query, and (optionally) highlights results in the view.

  

• Search — highlights results in the view and on the scrollbar.

  

If this property is set to Default, the behavior depends on the static (Shared in VB) WindowsFormsSettings.FindPanelBehavior property. If FindPanelBehavior is also set to Default, the Filter mode is applied.

Highlight Results

To specify whether search queries are highlighted, use the ColumnView.OptionsFind.HighlightFindResults property.

Note

The Grid control does not highlight text displayed in RepositoryItemTokenEdit and RepositoryItemRichTextEdit.

Panel Visibility

• ColumnView.ShowFindPanel — opens and focuses the panel. To open and focus the panel when the control is displayed for the first time, use the BeginInvoke method to call this method asynchronously (see an example).
• ColumnView.HideFindPanel — closes the panel.
• ColumnView.OptionsFind.AllowFindPanel — set to false to prevent the panel from being opened.
• ColumnView.OptionsFind.AlwaysVisible — set to true to prevent the panel from being closed.

Panel Location

The GridView.OptionsFind.FindPanelLocation property specifies where the panel is displayed:

• GroupPanel — the find panel is embedded into the group panel. Ensure that the ShowGroupPanel option is enabled.

  

  This mode has no effect if the InHeaderSearchMode option is set to TextFilter.

• Panel — the find panel is displayed in a separate panel.

  

The default location depends on the Version Compatibility setting. The find panel is embedded in the group panel as of v19.2.

Specify Search Queries in Code

• ColumnView.ApplyFindFilter — enters the specified query in the find panel and applies it.
• ColumnView.ClearFindFilter — discards the query and clears the find panel.
• ColumnView.CustomRowFilter — specifies row visibility regardless of the currently applied filter.
• ColumnView.OptionsFind.FindFilterColumns — names of columns in which to search for keywords. Note that the find panel searches for keywords in visible columns only (see Visible).
• ColumnView.ColumnFilterChanged — occurs when the Find Panel finishes its search.

Search Syntax

Search syntax may vary depending on the GridView.OptionsFind.ParserKind and GridView.OptionsFind.Condition properties. See the following help topic for more information: Find Panel Syntax.

Parse Search Query

If standard search syntax does not fit your needs or you need to highlight search results in a custom manner, you can handle the ColumnView.ParseFindPanelText event. The event allows you to create a filter condition based on the query and specify how to highlight results in the control.

Operation Buttons

Use the following properties to show/hide the operation buttons:

• ColumnView.OptionsFind.ShowCloseButton - the X button that closes the panel.

  

• ColumnView.OptionsFind.ShowClearButton - the Clear button.

  

  To display the Clear button as a separate button, set the DefaultSettingsCompatibilityMode to v19_1 or earlier.

  

  The separate Clear button is only displayed in Filter mode and if the find panel is not embedded into the group panel.

• ColumnView.OptionsFind.ShowSearchNavButtons - the Previous and Next buttons allow users to navigate between search results. These buttons are only displayed in Search mode.

  

• ColumnView.OptionsFind.ShowFindButton - the Find button that applies the query. This button is only displayed in Filter mode and if the find panel is not embedded into the group panel.

  

Display Custom Items within the Find Panel

The ColumnView.FindPanelItems object contains the following methods that allow you to display buttons, check buttons, or other controls within the Find Panel:

• AddButton
• AddCheckButton
• AddControl

The following code sample adds a check button that switches the ColumnView.OptionsFind.Behavior property at runtime:

C#

void button_AddCheck_Click(object sender, System.EventArgs e) {
    var checkItem = gridView1.FindPanelItems.AddCheckButton(
        "btnBehavior",
        "Filter",
        false,
        (s, args) => {
            CheckButton checkButton = s as CheckButton;
            gridView1.OptionsFind.Behavior = checkButton.Checked ? FindPanelBehavior.Search : FindPanelBehavior.Filter;
            checkButton.Text = checkButton.Checked ? "Search" : "Filter";
        }
    );
    checkItem.ImageOptions.ImageUri.Uri = "Filter;Size16x16;Svg";
}

VB.NET

Private Sub button_AddCheck_Click(ByVal sender As Object, ByVal e As System.EventArgs)
    Dim checkItem = gridView1.FindPanelItems.AddCheckButton(
        "btnBehavior", 
        "Filter", 
        False, 
        Function(s, args)
            Dim checkButton As CheckButton = TryCast(s, CheckButton)
            gridView1.OptionsFind.Behavior = If(checkButton.Checked, FindPanelBehavior.Search, FindPanelBehavior.Filter)
            checkButton.Text = If(checkButton.Checked, "Search", "Filter")
        End Function)
    checkItem.ImageOptions.ImageUri.Uri = "Filter;Size16x16;Svg"
End Sub

Apply Search Queries

After a user types in the search box, the search starts automatically or manually depending on the underlying data source. You can use use the ColumnView.OptionsFind.FindMode property to specify this behavior explicitly. If the search begins automatically after a query is entered, the ColumnView.OptionsFind.FindDelay property specifies the delay before the search is initiated.

Server Mode Limitations

The find panel has the following limitations in server mode:

• only numeric and text columns are supported;
• only focused row and selected row scrollbar annotations are supported;
• only case-insensitive queries are supported. See the following KB article for more information: How to make the Grid’s filter case- and accent-insensitive in Server Mode;
• a search behavior (when a column’s OptionsFind.Behavior property is set to Search) is not supported;

• columns that show custom text instead of actual values are not supported.

  Tip

  To use these columns, store custom text in a data source field and set the GridColumn.FieldNameSortGroup property to the field’s name. You can also specify the ColumnViewOptionsFind.FindFilterColumns property to exclude these columns from the search.