AutoCompleteEdit Class
A text editor that suggests values as a user enters characters into the edit box.
Namespace: DevExpress.Maui.Editors
Assembly: DevExpress.Maui.Editors.dll
NuGet Package: DevExpress.Maui.Editors
Declaration
public class AutoCompleteEdit :
AutoCompleteEditBase,
IBindingContextParentRemarks
The AutoCompleteEdit displays suggestions in a drop-down list as a user types in the edit box.
Items
The ItemsSource property specifies the collection of items displayed in the drop-down list. To populate this collection, you can handle the TextChanged event (see the example in the Text Changed section) or use one of the following data providers:
- AsyncItemsSourceProvider
- A data provider that uses the specified delegate to get items in asynchronous mode.
- FilteredItemsSourceProvider
- A data provider that uses specified filter settings to get items from an existing collection in synchronous mode.
The providers automatically assign the item collection to the ItemsSource property. To assign a data provider to the editor, use the ItemsSourceProvider property.
When items are loaded, the editor displays them in the drop-down window. After an item is selected, it is automatically displayed in the edit box. Use the following members to obtain the selected item and respond to user interactions:
Property/Event | Description |
|---|---|
Gets or sets the item that is selected in the AutoCompleteEdit‘s drop-down list. This is a bindable property. | |
Fires when a user selects or deselects an item. | |
Specifies the command executed when an item in the drop-down list is selected. |
The NoResultsFoundText property specifies the text displayed in the drop-down list if no suitable items are found.
Asynchronous Data Provider
Follow the steps below to supply items to the editor in asynchronous mode:
- Attach the AsyncItemsSourceProvider to the editor and handle its ItemsRequested event.
- Use the RequestAsync or Request event argument to specify the method that returns items. The provider assigns the returned collection to the ItemsSource property.
- Use the Text event argument to obtain the text entered in the edit box and pass it to the specified method.
You can also specify the following options:
- RequestDelay – the time that should elapse after the text is changed and the request is called. Use this parameter to reduce the number of requests as a user types.
- CharacterCountThreshold – the number of entered characters after which the provider starts to make requests. For example, the provider can make requests only if a user enters at least three characters.
The provider cancels the previous request if a new request is submitted. You can use the CancellationToken event argument to cancel the previous request.
Example
The example below uses the AsyncItemsSourceProvider to supply suggestions for the AutoCompleteEdit.
<dxe:AutoCompleteEdit LabelText="State"
PlaceholderText="Type here to search..."
VerticalOptions="Center"
Margin="16,0">
<dxe:AutoCompleteEdit.ItemsSourceProvider>
<dxe:AsyncItemsSourceProvider ItemsRequested="OnDelegateRequested" />
</dxe:AutoCompleteEdit.ItemsSourceProvider>
</dxe:AutoCompleteEdit>
using System.Collections.Generic;
using System.ComponentModel;
using Microsoft.Maui.Controls;
namespace AutoCompleteEditExample {
public partial class MainPage : ContentPage {
public MainPage() {
InitializeComponent();
States = new List<string>();
States.AddRange(new string[] { "California", "Colorado", "Connecticut" /*...*/ });
}
public List<string> States { get; }
void OnDelegateRequested(object sender, ItemsRequestEventArgs e) {
e.Request = () => {
return States.Where(i => i.StartsWith(e.Text, StringComparison.CurrentCultureIgnoreCase)).ToList();
};
}
}
}
Synchronous Data Provider
The FilteredItemsSourceProvider filters the data item collection based on the filter settings. The filtered collection is then automatically assigned to the editor’s ItemsSource property.
Use the provider’s ItemsSource property to specify the collection of suggestions. The table below contains options that define how the provider searches for suggestions in the collection.
Property/Event | Description |
|---|---|
Specifies whether suggestions should start with or contain the entered text. | |
Specifies culture and case rules used to compare the entered text with suggestions. | |
Specifies which data fields to search. |
Example
The example below uses the FilteredItemsSourceProvider to supply items for the AutoCompleteEdit.
<ContentPage.BindingContext>
<local:AutoCompleteEditViewModel/>
</ContentPage.BindingContext>
<dxe:AutoCompleteEdit>
<dxe:AutoCompleteEdit.ItemsSourceProvider>
<dxe:FilteredItemsSourceProvider ItemsSource="{Binding ItemsSource}"
FilterCondition="Contains"
FilterComparisonType="CurrentCultureIgnoreCase"
FilterMembers="Name, Capital"/>
</dxe:AutoCompleteEdit.ItemsSourceProvider>
<dxe:AutoCompleteEdit.ItemTemplate>
<DataTemplate>
<Grid>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*"/>
<ColumnDefinition Width="*"/>
<ColumnDefinition Width="*"/>
</Grid.ColumnDefinitions>
<Label Padding="10" Text="{Binding Name}" FontAttributes="Bold"/>
<Label Padding="10" Grid.Column="1" Text="{Binding Abbr}"/>
<Label Padding="10" Grid.Column="2" Text="{Binding Capital}" HorizontalTextAlignment="End"/>
</Grid>
</DataTemplate>
</dxe:AutoCompleteEdit.ItemTemplate>
</dxe:AutoCompleteEdit>
using System.Collections.Generic;
using System.ComponentModel;
using Microsoft.Maui.Controls;
namespace AutoCompleteEditExample {
public partial class MainPage : ContentPage {
public MainPage() {
InitializeComponent();
}
}
public class State {
public string Name { get; init; }
public string Abbr { get; init; }
public string Capital { get; init; }
}
public class AutoCompleteEditViewModel : INotifyPropertyChanged {
List<State> itemsSource = new List<State>();
public List<State> ItemsSource { get { return itemsSource; } set { itemsSource = value; OnPropertyChanged(nameof(ItemsSource)); } }
public AutoCompleteEditViewModel() {
ItemsSource.Add(new State() { Name = "California", Abbr = "CA", Capital = "Sacramento" });
ItemsSource.Add(new State() { Name = "Colorado", Abbr = "CO", Capital = "Denver" });
ItemsSource.Add(new State() { Name = "Connecticut", Abbr = "CT", Capital = "Hartford" });
}
public event PropertyChangedEventHandler PropertyChanged;
protected void OnPropertyChanged(string propertyName) {
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}
}
}
Display Member
You can also use a collection of custom objects as a source for items. Use the DisplayMember property to specify the data source field that contains data to be displayed in the drop-down list.
The code below uses the DisplayMember property to specify the data source field that contains the data that should be displayed in the drop-down list.
<dxe:AutoCompleteEdit DisplayMember="Name">
<dxe:AutoCompleteEdit.ItemsSourceProvider>
<dxe:AsyncItemsSourceProvider RequestDelay="500" SuggestionsRequested="OnDelegateRequested" />
</dxe:AutoCompleteEdit.ItemsSourceProvider>
</dxe:AutoCompleteEdit>
using System.Collections.Generic;
using System.ComponentModel;
using Microsoft.Maui.Controls;
namespace AutoCompleteEditExample {
public partial class MainPage : ContentPage {
public MainPage() {
InitializeComponent();
States = new List<State>();
States.Add(new State() { Name = "California", Abbr = "CA", Capital = "Sacramento" });
States.Add(new State() { Name = "Colorado", Abbr = "CO", Capital = "Denver" });
States.Add(new State() { Name = "Connecticut", Abbr = "CT", Capital = "Hartford" });
//...
}
public List<State> States { get; }
void OnDelegateRequested(object sender, SuggestionsRequestEventArgs e) {
e.Request = () => {
return States.Where(i => i.Name.StartsWith(e.Text, StringComparison.CurrentCultureIgnoreCase)).ToList();
};
}
public class State {
public string Name { get; set; }
public string Abbr { get; set; }
public string Capital { get; set; }
}
}
}
Item Template
Use the ItemTemplate property to define a drop-down list item template. To specify the data source field whose values are displayed in the edit box when a user selects an item, use the DisplayMember property.
The code below uses the ItemTemplate property to specify how data items are displayed in the drop-down list.
<dxe:AutoCompleteEdit DisplayMember="Name">
<dxe:AutoCompleteEdit.ItemTemplate>
<DataTemplate>
<Grid>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="*"/>
<ColumnDefinition Width="*"/>
<ColumnDefinition Width="*"/>
</Grid.ColumnDefinitions>
<Label Padding="10" Text="{Binding Name}" FontAttributes="Bold"/>
<Label Padding="10" Grid.Column="1" Text="{Binding Abbr}"/>
<Label Padding="10" Grid.Column="2" Text="{Binding Capital}" HorizontalTextAlignment="End"/>
</Grid>
</DataTemplate>
</dxe:AutoCompleteEdit.ItemTemplate>
<dxe:AutoCompleteEdit.ItemsSourceProvider>
<dxe:AsyncItemsSourceProvider RequestDelay="500" ItemsRequested="OnDelegateRequested"/>
</dxe:AutoCompleteEdit.ItemsSourceProvider>
</dxe:AutoCompleteEdit>
using System.Collections.Generic;
using System.ComponentModel;
using Microsoft.Maui.Controls;
namespace AutoCompleteEditExample {
public partial class MainPage : ContentPage {
public MainPage() {
InitializeComponent();
States = new List<State>();
States.Add(new State() { Name = "California", Abbr = "CA", Capital = "Sacramento" });
States.Add(new State() { Name = "Colorado", Abbr = "CO", Capital = "Denver" });
States.Add(new State() { Name = "Connecticut", Abbr = "CT", Capital = "Hartford" });
//...
}
public List<State> States { get; }
void OnDelegateRequested(object sender, SuggestionsRequestEventArgs e) {
e.Request = () => {
return States.Where(i => i.Name.StartsWith(e.Text, StringComparison.CurrentCultureIgnoreCase)).ToList();
};
}
public class State {
public string Name { get; init; }
public string Abbr { get; init; }
public string Capital { get; init; }
}
}
}
Input Text
Use the Text property to obtain or set the text entered in the editor. The following properties specify the input text appearance and alignment:
Property | Description |
|---|---|
Specify the text color for different editor states. | |
Configure the font settings. | |
Gets or sets the horizontal alignment of text entered in the editor. This is a bindable property. |
To manage the cursor position and text selection, use the CursorPosition and SelectionStart/SelectionLength properties.
Text Changed
The TextChanged event fires when the edit box content is changed. Use the Reason event argument to determine whether the content is updated because the user entered new text or selected an autocomplete item, or the content was revised in code. You can also use the TextChangedCommand property to specify the command executed when text is changed.
You can handle the TextChanged event to supply items. Ensure that the Reason event argument is set to UserInput and update the collection bound to the ItemsSource property. The TextChanged event allows you to load items one by one, which can be helpful when data loads slowly from the source.
The TextChanged event allows you to load items one by one, which can be helpful if there is a slow connection between the app and the data source.
Wait Indicator
If the LoadingProgressMode property is set to Auto, the editor automatically displays a wait indicator in the drop-down window when the text in the edit box changes, and automatically hides it when the ItemsSource collection is updated.
In Manual mode, use the IsLoadingInProgress property to show and hide the wait indicator. You can also use the WaitIndicatorColor property to specify its color.
Example
The code below handles the TextChanged event to supply suggestions.
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:dxe="clr-namespace:DevExpress.Maui.Editors;assembly=DevExpress.Maui.Editors"
xmlns:local="clr-namespace:DemoCenter.Forms.Views"
x:Class="DemoCenter.Forms.Views.AutoCompleteEditView">
<ContentPage.BindingContext>
<local:AutoCompleteEditViewModel/>
</ContentPage.BindingContext>
<ContentPage.Content>
<dxe:AutoCompleteEdit TextChanged="AutoCompleteEdit_TextChanged"
ItemsSource="{Binding ItemsSource}"
LoadingProgressMode="Manual"/>
</ContentPage.Content>
</ContentPage>
using System;
using System.ComponentModel;
using System.Linq;
using System.Threading.Tasks;
using DevExpress.Maui.Editors;
namespace DemoCenter.Forms.Views {
// View
public partial class AutoCompleteEditView : ContentPage {
private void AutoCompleteEdit_TextChanged(object sender, DevExpress.Maui.Editors.AutoCompleteEditTextChangedEventArgs e) {
AutoCompleteEdit edit = sender as AutoCompleteEdit;
AutoCompleteEditViewModel viewModel = edit.BindingContext as AutoCompleteEditViewModel;
if (e.Reason == DevExpress.Maui.Editors.AutoCompleteEditTextChangeReason.UserInput) {
edit.IsLoadingInProgress = true;
Task.Factory.StartNew(new Action(() => {
Thread.Sleep(3000);
Dispatcher.Dispatch(new Action(() => {
viewModel.ItemsSource = Model.Queries.Where(i => i.Contains(edit.Text)).ToList<string>();
edit.IsLoadingInProgress = false;
}));
}));
}
}
}
// View Model
public class AutoCompleteEditViewModel : INotifyPropertyChanged {
List<string> itemsSource = new List<string>();
public List<string> ItemsSource { get { return itemsSource; } set { itemsSource = value; OnPropertyChanged(nameof(ItemsSource)); } }
public event PropertyChangedEventHandler PropertyChanged;
protected void OnPropertyChanged(string propertyName) {
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}
}
// Model
class Model {
public static List<string> Queries = new List<string>();
static Model() {
Queries.Add("California");
Queries.Add("Colorado");
Queries.Add("Connecticut");
}
}
}
Label
A label is the editor’s input prompt string (LabelText). Editors display this string inside the edit box (when the editor is empty and not focused) or at the top of the editor.
To pin the label to the top edge of the editor box, set the IsLabelFloating property to false.
To customize the label’s appearance settings, use the following properties:
LabelColor, FocusedLabelColor, and DisabledLabelColor – Specify label text color for different editor states.
LabelFontSize, TextFontFamily, TextFontAttributes – Configure the label font settings.
Help Text and Error Message
You can display the following labels below an editor:
- HelpText - A brief editor description.
- ErrorText - A message shown when an error occurs (HasError is true).
The BottomTextTopIndent property specifies the indent between the editor’s bottom border and the help or error text.
To specify the color and font attributes for the help/error text, use the following properties:
Property | Description |
|---|---|
Specify the help text color for different states of an editor. | |
Specifies the error message text color. | |
BottomTextFontSize | Specify font settings. |
If HelpText is not set, ErrorText appears as an additional line below the edit box and page content shifts down. To prevent this behavior, set the ReserveBottomTextLine property to true.
Icons
The AutoCompleteEdit control can display all common icons within its box. You can also configure the default Submit icon that allows a user to submit a query.
Use the following API to configure the Submit icon in the AutoCompleteEdit component:
Icon | Property | Description |
|---|---|---|
Submit Icon | Gets or sets whether the submit icon is displayed. This is a bindable property. | |
Gets or sets the color of the submit icon. This is a bindable property. | ||
Gets or sets the submit icon. This is a bindable property. | ||
Occurs when a user taps the submit icon in the edit box or selects an item in the drop-down list. | ||
Gets or sets the command executed when a user taps the submit icon. This is a bindable property. |
User Interaction
Editors raise the following events on user interaction:
- Tap - Fires when the user taps the editor.
- DoubleTap - Fires when the user double taps the editor.
- LongPress - Fires when the user presses and holds the editor.
Editor Appearance
You can use the following properties to customize the editor’s appearance settings for different states:
Auto Complete Edit State | Properties |
|---|---|
Default | BorderColor |
Focused | FocusedBorderColor |
Disabled | DisabledBorderColor |
Error |
The following list shows common appearance settings applied in all states:
Property | Description |
|---|---|
Gets or sets whether edit box corners are rounded or cut. This is a bindable property. | |
Gets or sets the radius of the combo box and drop-down list corners. | |
Adjust the font settings. |
Example
- Implement a Phone Book App – Shows how to use a
text editor with autocompleteto implement a search UI in a phone book. Editor items are loaded in synchronous mode.