All docs
V20.2
20.2
20.1
The page you are viewing does not exist in version 20.1. This link will take you to the root page.
19.2
The page you are viewing does not exist in version 19.2. This link will take you to the root page.
19.1
The page you are viewing does not exist in version 19.1. This link will take you to the root page.
1.1
The page you are viewing does not exist in version 1.1. This link will take you to the root page.

AutoCompleteEdit Class

A text editor that suggests values as a user enters characters into the edit box.

Namespace: DevExpress.XamarinForms.Editors

Assembly: DevExpress.XamarinForms.Editors.dll

Declaration

public class AutoCompleteEdit :
    ItemsEditBase,
    IAutoCompleteEditController,
    IItemsController,
    IEditController,
    IElementController,
    IBindingContextParent

The following members accept/return AutoCompleteEdit objects:

Remarks

The AutoCompleteEdit displays suggestions in a drop-down list as a user types in the edit box.

Suggestions

The ItemsSource property specifies the collection of suggestions displayed in the drop-down list. To populate this collection you can handle the TextChanged event (see an example below) or use one of the following data providers:

  • AsyncItemsSourceProvider — a data provider that uses the specified delegate to get suggestions in asynchronous mode.
  • FilteredItemsSourceProvider — a data provider that uses the specified filter settings to get suggestions from an existing collection in synchronous mode.

The providers automatically assign the suggestion collection to the ItemsSource property. To assign a data provider to the editor, use the ItemsSourceProvider property.

When suggestions are loaded, the editor displays them in the drop-down window. After a suggestion is selected, it is automatically displayed in the edit box. Use the following members to obtain the selected suggestion and respond to user interactions:

Property/Event

Description

ChosenSuggestion

Gets the selected suggestion in the drop-down list.

SuggestionChosen

Fires when a user selects a suggestion in the drop-down list.

SuggestionChosenCommand / SuggestionChosenCommandParameter

Specifies the command executed when a suggestion in the drop-down list is selected.

The NoSuggestionsText property specifies the text displayed in the drop-down list if no suggestions are found.

Asynchronous Data Provider

Attach the AsyncItemsSourceProvider to the editor and handle its SuggestionsRequested event. Use the Request event argument to specify the method that returns suggestions. The provider assigns the returned collection to the ItemsSource property. To get the text entered in the edit box and pass it to the specified method, use the Text event argument.

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 SuggestionsRequested="OnDelegateRequested" />
    </dxe:AutoCompleteEdit.ItemsSourceProvider>
</dxe:AutoCompleteEdit>

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 SuggestionsSource 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

FilterMode

Specifies whether suggestions should start with or contain the entered text.

FilterComparisonType

Specifies culture and case rules used to compare the entered text with suggestions.

FilterMembers

Specifies which data fields to search.

Example

The example below uses the FilteredItemsSourceProvider to supply suggestions for the AutoCompleteEdit.

<ContentPage.BindingContext>
    <local:AutoCompleteEditViewModel/>
</ContentPage.BindingContext>

<dxe:AutoCompleteEdit>
    <dxe:AutoCompleteEdit.ItemsSourceProvider>
        <dxe:FilteredItemsSourceProvider SuggestionsSource="{Binding ItemsSource}"
                                         FilterMode="Contains"
                                         FilterComparisonType="CurrentCultureIgnoreCase"
                                         FilterMembers="Name, Capital"/>
    </dxe:AutoCompleteEdit.ItemsSourceProvider>

    <dxe:AutoCompleteEdit.ItemTemplate>
        <DataTemplate>
            <Grid>
                <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>

Display Member

You can also use a collection of custom objects as a source for suggestions. 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>

Item Template

To define a drop-down list item template, use the ItemTemplate property. 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>
                <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" SuggestionsRequested="OnDelegateRequested"/>
    </dxe:AutoCompleteEdit.ItemsSourceProvider>
</dxe:AutoCompleteEdit>

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

TextColor / DisabledTextColor

Specify the text color for different editor states.

TextFontSize
TextFontFamily
TextFontAttributes

Configure the font settings.

TextHorizontalAlignment

Gets or sets the horizontal alignment of text entered in the editor.

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 suggestion, 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 suggestions. Ensure that the Reason event argument is set to UserInput and update the collection bound to the ItemsSource property.

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://xamarin.com/schemas/2014/forms"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:dxe="clr-namespace:DevExpress.XamarinForms.Editors;assembly=DevExpress.XamarinForms.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>

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:

Property

Description

LabelColor / FocusedLabelColor
DisabledLabelColor / ErrorColor

Specify the label color for each state of the auto-complete editor.

LabelFontSize
TextFontFamily
TextFontAttributes

Configure the label font settings.

Help Text and Error Message

You can display the following labels below an editor:

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

HelpTextColor
DisabledHelpTextColor

Specify the help text color for different states of an editor.

ErrorColor

Specifies the error message text color.

BottomTextFontSize
BottomTextFontFamily
BottomTextFontAttributes

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 can display the following icons within the edit box:

  • Clear icon - removes the text entered in the editor.
  • Submit icon - submits a query.

Use the following members to specify the editor's icons:

Icon

Property

Description

Submit Icon

SubmitIconVisibility

Specifies when the submit icon is displayed.

SubmitIconColor

Gets or sets the color of the submit icon.

SubmitIcon

Specifies the submit icon.

QuerySubmitted

Fires when a user taps the submit icon in the edit box or selects a suggestion in the drop-down list.

QuerySubmittedCommand / QuerySubmittedCommandParameter

Specifies the command executed when a user taps the submit icon.

Clear Icon

ClearIconVisibility

Specifies when the clear icon is displayed.

ClearIcon

Specifies the clear icon image.

ClearIconClicked

Allows you to assign an additional action to the clear icon.

ClearIconCommand / ClearIconCommandParameter

Allow you to assign an additional action to the clear icon.

Common

IconColor / DisabledIconColor

Specify icon colors for different text editor states.

IconIndent

Gets or sets the distance between an icon and input text (affix).

IconSpacing

Gets or sets the distance between icons.

IconVerticalAlignment

Gets or sets the vertical alignment of icons.

The editor can also display two custom icons and an error icon. See the following properties for more information: StartIcon, EndIcon, and ErrorIcon.

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
BorderThickness
BackgroundColor
TextColor

Focused

FocusedBorderColor
FocusedBorderThickness
DropDownBackgroundColor
DropDownItemTextColor
DropDownSelectedItemBackgroundColor
DropDownSelectedItemTextColor

Disabled

DisabledBorderColor
DisabledBorderThickness
DisabledBackgroundColor
DisabledTextColor

Error

ErrorColor

The following list shows common appearance settings applied in all states:

Property

Description

CornerMode

Gets or sets whether edit box corners are rounded or cut.

CornerRadius

Specifies the radius of the combo box and drop-down list corners.

TextFontAttributes
TextFontFamily
TextFontSize

Adjust the font settings.

Implements

Xamarin.Forms.IAnimatable
Xamarin.Forms.ITabStopElement
Xamarin.Forms.IViewController
Xamarin.Forms.IVisualElementController
Xamarin.Forms.Internals.IGestureController
Xamarin.Forms.IGestureRecognizers
Xamarin.Forms.IElementController

Inheritance

Object
Xamarin.Forms.BindableObject
Xamarin.Forms.Element
Xamarin.Forms.NavigableElement
Xamarin.Forms.VisualElement
See Also