LookUpEdit.AutoSuggest Event

Fires only when the SearchMode property equals AutoSuggest. In this mode, the editor runs the asynchronous Task assigned in the event handler to retrieve a list of drop-down panel items. See the LookUpEdit class description for more information.

Namespace: DevExpress.XtraEditors

Assembly: DevExpress.XtraEditors.v24.2.dll

Declaration

C#

[DXCategory("Events")]
public event LookUpEditAutoSuggestEventHandler AutoSuggest

VB.NET

<DXCategory("Events")>
Public Event AutoSuggest As LookUpEditAutoSuggestEventHandler

Event Data

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

Property	Description
Cancel	Cancels the Task assigned to the QuerySuggestions parameter. Inherited from LookUpEditSearchHighlightEventArgs.
CancellationToken	An object that cancels the Task assigned to the GetSuggestions method. This object is generated when you call the Cancel method.
ClearSuggestions	Clears the editor drop-down menu, removing all items returned by the GetSuggestions task.
EditorText	Inherited from LookUpEditSearchHighlightEventArgs.
QuerySuggestions	Gets or sets a System.Threading.Tasks.Task object that returns the collection of items, which match the current user text. These items are displayed in the editor drop-down menu.
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.
SetMinimumAnimationDuration(Int32)	Sets the minimum duration for the loading indicator that plays while the GetSuggestion task is ongoing. This allows you to prevent this animation from flickering when the task completes too quickly.
SetMinimumAnimationDuration(TimeSpan)	Sets the minimum duration for the loading indicator that plays while the GetSuggestion task is ongoing. This allows you to prevent this animation from flickering when the task completes too quickly.
SetQuerySuggestionsTask<T>(Task<List<T>>)	Sets a Task that defines the items the LookUpEdit or GridLookUpEdit display in AutoSuggest mode.

Remarks

In AutoSuggest mode, the Lookup editor fires the AutoSuggest event whenever a user enters text within it and dynamically changes the editor’s data source.

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

The code below illustrates how to assign a Task that returns a suggestions collection, and implement a custom text highlight logic. See the LookUpEdit class description for more information.

C#

lookUpEdit1.AutoSuggest += OnAutoSuggest;

void OnAutoSuggest(object sender, LookUpEditAutoSuggestEventArgs e) {
    // Set delay (if needed)
    e.SetMinimumAnimationDuration(TimeSpan.FromMilliseconds(1000));
    // Assign a Task that returns suggestions
    e.QuerySuggestions = WorldCities.QueryAsync(e.Text, e.CancellationToken);
    // Set Custom Highlight Strategy
    e.SetHighlightRanges(HighlightTags(e.Text));
}

static Func<string, string, DisplayTextHighlightRange[]> HighlightTags(string pattern) {
    var indexOf = IgnoreCaseComparisonFunctions.GetIndexOf(
        CultureInfo.CurrentCulture.CompareInfo, CompareOptions.IgnoreCase);
    var parts = pattern.Split(new char[] { ' ' },
        StringSplitOptions.RemoveEmptyEntries);
    return (displayText, fieldName) => {
        var tags = displayText.Split(new string[] { ", " },
            StringSplitOptions.RemoveEmptyEntries);
        var ranges = new List<DisplayTextHighlightRange>();
        for(int i = 1/*skip country tag*/; i < tags.Length; i++) {
            int tagStart = displayText.IndexOf(tags[i]);
            for(int j = 0; j < parts.Length; j++) {
                int index = indexOf(tags[i], parts[j]);
                if(index != -1)
                    ranges.Add(new DisplayTextHighlightRange(tagStart + index, parts[j].Length));
            }
        }
        return ranges.ToArray();
    };
}

VB.NET

AddHandler lookUpEdit1.AutoSuggest, AddressOf OnAutoSuggest

Private Sub OnAutoSuggest(ByVal sender As Object, ByVal e As LookUpEditAutoSuggestEventArgs)
    ' Set delay (if needed)
    e.SetMinimumAnimationDuration(TimeSpan.FromMilliseconds(1000))
    ' Assign a Task that returns suggestions
    e.QuerySuggestions = WorldCities.QueryAsync(e.Text, e.CancellationToken)
    ' Set Custom Highlight Strategy
    e.SetHighlightRanges(HighlightTags(e.Text))
End Sub

Shared Function HighlightTags(ByVal pattern As String) As Func(Of String, String, DisplayTextHighlightRange())
    Dim indexOf = IgnoreCaseComparisonFunctions.GetIndexOf(CultureInfo.CurrentCulture.CompareInfo, CompareOptions.IgnoreCase)
    Dim parts = pattern.Split(New Char() { " "c }, StringSplitOptions.RemoveEmptyEntries)
    Return Function(displayText, fieldName)
        Dim tags = displayText.Split(New String() { ", " }, StringSplitOptions.RemoveEmptyEntries)
        Dim ranges = New List(Of DisplayTextHighlightRange)()
        For i As Integer = 1 To tags.Length - 1 'skip country tag
            Dim tagStart As Integer = displayText.IndexOf(tags(i))
            For j As Integer = 0 To parts.Length - 1
                Dim index As Integer = indexOf(tags(i), parts(j))
                If index <> -1 Then
                    ranges.Add(New DisplayTextHighlightRange(tagStart + index, parts(j).Length))
                End If
            Next j
        Next i
        Return ranges.ToArray()
    End Function
End Function