LookUpEdit.AutoSearch Event

Fires only when the editor SearchMode property equals AutoSearch. In this mode, the editor filters out data source records that do not match the currently entered text, and displays remaining records in the drop-down panel. The AutoSearch event is optional, it allows you to fine-tune the search. See the LookUpEdit class description to learn more.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v23.2.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Events")]
public event LookUpEditAutoSearchEventHandler AutoSearch

VB.NET

<DXCategory("Events")>
Public Event AutoSearch As LookUpEditAutoSearchEventHandler

Event Data

The AutoSearch event's data class is LookUpEditAutoSearchEventArgs. The following properties provide information specific to this event:

Property	Description
Cancel	Cancels the Task assigned to the QuerySuggestions parameter. Inherited from LookUpEditSearchHighlightEventArgs.
EditorText	Inherited from LookUpEditSearchHighlightEventArgs.
Text	Returns the current user text. Inherited from LookUpEditSearchHighlightEventArgs.

The event data class exposes the following methods:

Method	Description
ClearHighlight()	Removes any active highlight pattern from lookup items. Inherited from LookUpEditSearchHighlightEventArgs.
GetHighlighter()	This member supports internal infrastucture and is not intended to be used in code. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightAny(CompareOptions)	Highlights any part of a record that matches the text entered by a user. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightAny(String, CompareOptions)	Highlights any part of a record that matches the given text. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightAny(String, String, CompareOptions)	Highlights any part of a record that belongs to the specific data field and matches the given text. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightAny(String[], String, CompareOptions)	Highlights any part of a record that belongs to certain data fields and matches the given text. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFirst(CompareOptions)	In every data field value, selects the first found text portion that matches the user text. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFirst(String, CompareOptions)	In every data field value, selects the first found text sequence if it matches the user text. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFirst(String, String, CompareOptions)	Selects the first found text sequence if it matches the user text and belongs to the specific data field. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFirst(String[], String, CompareOptions)	Selects the first found text portion that matches the user text and belongs to any of the given data fields. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFromStart(CompareOptions)	If a record starts with the user text, this text portion is highlighted. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFromStart(String, CompareOptions)	If a record starts with the given text, this text portion is higlighted. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFromStart(String, String, CompareOptions)	If a record belongs to the given data field and starts with the specific text, this text portion is highlighted. Inherited from LookUpEditSearchHighlightEventArgs.
HighlightFromStart(String[], String, CompareOptions)	If record belongs to any of the given data fields and starts with the specific text, this text portion is higlighted. Inherited from LookUpEditSearchHighlightEventArgs.
SetHighlightRange(Func<String, Nullable<DisplayTextHighlightRange>>)	Sets a specific highlight range. Inherited from LookUpEditSearchHighlightEventArgs.
SetHighlightRange(Func<String, String, Nullable<DisplayTextHighlightRange>>)	Sets a specific highlight range. Inherited from LookUpEditSearchHighlightEventArgs.
SetHighlightRanges(Func<String, String, DisplayTextHighlightRange[]>)	Sets specific highlight ranges. Inherited from LookUpEditSearchHighlightEventArgs.
SetParameters(FindPanelParserKind, FilterCondition)	Allows you to change how the lookup editor searches for items in its drop-down panel.
SetParameters(String, FindPanelParserKind, FilterCondition)	Allows you to change how the lookup editor searches for items in its drop-down panel.
SetParameters(String, String, FindPanelParserKind, FilterCondition)	Allows you to change how the lookup editor searches for items in its drop-down panel.
SetParameters(String[], String, FindPanelParserKind, FilterCondition)	Allows you to change how the lookup editor searches for items in its drop-down panel.

Remarks

The AutoSearch event fires if the RepositoryItemLookUpEditBase.TextEditStyle property is set to Standard.

The AutoSearch mode allows users to search for required data source items.

Change Search Logic

Handle the AutoSearch event (LookUpEdit.AutoSearch \ GridLookUpEdit.AutoSearch) and use a SetParameters method overload to specify how the editor should compare user text with editor items.

• parserKind parameter - specifies how user text parts divided by a space character should be combined (see the ColumnViewOptionsFind.ParserKind property for examples).
• condition parameter - specifies which function should be used to build filter expressions (see the ColumnViewOptionsFind.Condition Data Grid property for examples).
• field or fields[] parameter - allows you to limit the search by specific data fields only.
• text parameter - allows you to replace the user text.

The example below illustrates how to make the editor look for items whose text starts with the user text.

C#

lookUpEdit1.AutoSearch += OnAutoSearch;

void OnAutoSearch(object sender, LookUpEditAutoSearchEventArgs e) {
    string[] fields = new string[] { "ShipCity", "ShipCountry" };
    e.SetParameters(fields, e.Text, FindPanelParserKind.And, FilterCondition.StartsWith);
}

VB.NET

Private lookUpEdit1.AutoSearch += AddressOf OnAutoSearch

Private Sub OnAutoSearch(ByVal sender As Object, ByVal e As LookUpEditAutoSearchEventArgs)
    Dim fields() As String = { "ShipCity", "ShipCountry" }
    e.SetParameters(fields, e.Text, FindPanelParserKind.And, FilterCondition.StartsWith)
End Sub

You can call the LookUpEditBase.StartAutoSearch method to manually trigger the AutoSearch event.

Custom Text Highlight Ranges

Lookup editors highlight text portions that match user text. Handle the AutoSearch event to implement custom highlight ranges. This mode uses same highlight API as the AutoSuggest mode does.

The example below illustrates how to make a lookup editor highlight the entire field value if it starts with the specified user text.

C#

private void LookUpEdit1_AutoSearch(object sender, LookUpEditAutoSearchEventArgs e)
{
    e.SetAutoSearchParameters(FindPanelParserKind.And, FilterCondition.StartsWith);
    e.SetHighlightRanges(CustomHightlight(e.Text));
}

static Func<string, string, DisplayTextHighlightRange[]> CustomHightlight(string userText)
{
    return (displayText, fieldName) =>
    {
        if (fieldName == "ShipCity" || fieldName == "ShipCountry")
        {
            if (displayText.StartsWith(userText))
                return new DisplayTextHighlightRange[] {
                    new DisplayTextHighlightRange(0, displayText.Length) };
        }
        return null;
    };
}

VB.NET

Private Sub LookUpEdit1_AutoSearch(ByVal sender As Object, ByVal e As LookUpEditAutoSearchEventArgs)
    e.SetAutoSearchParameters(FindPanelParserKind.And, FilterCondition.StartsWith)
    e.SetHighlightRanges(CustomHightlight(e.Text))
End Sub

Shared Function CustomHightlight(ByVal userText As String) As Func(Of String, String, DisplayTextHighlightRange())
    Return Function(displayText, fieldName)
        If fieldName = "ShipCity" OrElse fieldName = "ShipCountry" Then
            If displayText.StartsWith(userText) Then
                Return New DisplayTextHighlightRange() { New DisplayTextHighlightRange(0, displayText.Length) }
            End If
        End If
        Return Nothing
    End Function
End Function