Table of Contents

Class AutoCompleteBox

Namespace
Avalonia.Controls
Assembly
Avalonia.Controls.dll

Represents a control that provides a text box for user input and a drop-down that contains possible matches based on the input in the text box.

[TemplatePart("PART_Popup", typeof(Popup))]
[TemplatePart("PART_SelectingItemsControl", typeof(SelectingItemsControl))]
[TemplatePart("PART_SelectionAdapter", typeof(ISelectionAdapter))]
[TemplatePart("PART_TextBox", typeof(TextBox))]
[PseudoClasses(new string[] { ":dropdownopen" })]
public class AutoCompleteBox : TemplatedControl, INotifyPropertyChanged, IDataContextProvider, ILogical, IThemeVariantHost, IResourceHost, IResourceNode, IStyleHost, ISetLogicalParent, ISetInheritanceParent, ISupportInitialize, IStyleable, INamed, IInputElement, IDataTemplateHost, ISetterValue
Inheritance
AutoCompleteBox
Implements
Inherited Members
Extension Methods

Constructors

AutoCompleteBox()

Initializes a new instance of the AutoCompleteBox class.

public AutoCompleteBox()

Fields

AsyncPopulatorProperty

Identifies the AsyncPopulator property.

public static readonly StyledProperty<Func<string?, CancellationToken, Task<IEnumerable<object>>>?> AsyncPopulatorProperty

Field Value

StyledProperty<Func<string, CancellationToken, Task<IEnumerable<object>>>>

The identifier for the AsyncPopulator property.

CaretIndexProperty

Defines see CaretIndex property.

public static readonly StyledProperty<int> CaretIndexProperty

Field Value

StyledProperty<int>

FilterModeProperty

Gets the identifier for the FilterMode property.

public static readonly StyledProperty<AutoCompleteFilterMode> FilterModeProperty

Field Value

StyledProperty<AutoCompleteFilterMode>

InnerLeftContentProperty

Defines the InnerLeftContent property

public static readonly StyledProperty<object?> InnerLeftContentProperty

Field Value

StyledProperty<object>

InnerRightContentProperty

Defines the InnerRightContent property

public static readonly StyledProperty<object?> InnerRightContentProperty

Field Value

StyledProperty<object>

IsDropDownOpenProperty

Identifies the IsDropDownOpen property.

public static readonly StyledProperty<bool> IsDropDownOpenProperty

Field Value

StyledProperty<bool>

The identifier for the IsDropDownOpen property.

IsTextCompletionEnabledProperty

Identifies the IsTextCompletionEnabled property.

public static readonly StyledProperty<bool> IsTextCompletionEnabledProperty

Field Value

StyledProperty<bool>

The identifier for the IsTextCompletionEnabled property.

ItemFilterProperty

Identifies the ItemFilter property.

public static readonly StyledProperty<AutoCompleteFilterPredicate<object?>?> ItemFilterProperty

Field Value

StyledProperty<AutoCompleteFilterPredicate<object>>

The identifier for the ItemFilter property.

ItemSelectorProperty

Identifies the ItemSelector property.

public static readonly StyledProperty<AutoCompleteSelector<object>?> ItemSelectorProperty

Field Value

StyledProperty<AutoCompleteSelector<object>>

The identifier for the ItemSelector property.

ItemTemplateProperty

Identifies the ItemTemplate property.

public static readonly StyledProperty<IDataTemplate> ItemTemplateProperty

Field Value

StyledProperty<IDataTemplate>

The identifier for the ItemTemplate property.

ItemsSourceProperty

Identifies the ItemsSource property.

public static readonly StyledProperty<IEnumerable?> ItemsSourceProperty

Field Value

StyledProperty<IEnumerable>

The identifier for the ItemsSource property.

MaxDropDownHeightProperty

Identifies the MaxDropDownHeight property.

public static readonly StyledProperty<double> MaxDropDownHeightProperty

Field Value

StyledProperty<double>

The identifier for the MaxDropDownHeight property.

MaxLengthProperty

Defines the MaxLength property

public static readonly StyledProperty<int> MaxLengthProperty

Field Value

StyledProperty<int>

MinimumPopulateDelayProperty

Identifies the MinimumPopulateDelay property.

public static readonly StyledProperty<TimeSpan> MinimumPopulateDelayProperty

Field Value

StyledProperty<TimeSpan>

The identifier for the MinimumPopulateDelay property.

MinimumPrefixLengthProperty

Identifies the MinimumPrefixLength property.

public static readonly StyledProperty<int> MinimumPrefixLengthProperty

Field Value

StyledProperty<int>

The identifier for the MinimumPrefixLength property.

SearchTextProperty

Identifies the SearchText property.

public static readonly DirectProperty<AutoCompleteBox, string?> SearchTextProperty

Field Value

DirectProperty<AutoCompleteBox, string>

The identifier for the SearchText property.

SelectedItemProperty

Identifies the SelectedItem property.

public static readonly StyledProperty<object?> SelectedItemProperty

Field Value

StyledProperty<object>

The identifier the SelectedItem property.

SelectionChangedEvent 

public static readonly RoutedEvent<SelectionChangedEventArgs> SelectionChangedEvent

Field Value

RoutedEvent<SelectionChangedEventArgs>

TextChangedEvent

Defines the TextChanged event.

public static readonly RoutedEvent<TextChangedEventArgs> TextChangedEvent

Field Value

RoutedEvent<TextChangedEventArgs>

TextFilterProperty

Identifies the TextFilter property.

public static readonly StyledProperty<AutoCompleteFilterPredicate<string?>?> TextFilterProperty

Field Value

StyledProperty<AutoCompleteFilterPredicate<string>>

The identifier for the TextFilter property.

TextProperty

Identifies the Text property.

public static readonly StyledProperty<string?> TextProperty

Field Value

StyledProperty<string>

The identifier for the Text property.

TextSelectorProperty

Identifies the TextSelector property.

public static readonly StyledProperty<AutoCompleteSelector<string?>?> TextSelectorProperty

Field Value

StyledProperty<AutoCompleteSelector<string>>

The identifier for the TextSelector property.

WatermarkProperty 

public static readonly StyledProperty<string?> WatermarkProperty

Field Value

StyledProperty<string>

Properties

AsyncPopulator 

public Func<string?, CancellationToken, Task<IEnumerable<object>>>? AsyncPopulator { get; set; }

Property Value

Func<string, CancellationToken, Task<IEnumerable<object>>>

CaretIndex

Gets or sets the caret index

public int CaretIndex { get; set; }

Property Value

int

FilterMode

Gets or sets how the text in the text box is used to filter items specified by the ItemsSource property for display in the drop-down.

public AutoCompleteFilterMode FilterMode { get; set; }

Property Value

AutoCompleteFilterMode

One of the AutoCompleteFilterMode values The default is StartsWith.

Remarks

Use the FilterMode property to specify how possible matches are filtered. For example, possible matches can be filtered in a predefined or custom way. The search mode is automatically set to Custom if you set the ItemFilter property.

Exceptions

ArgumentException

The specified value is not a valid AutoCompleteFilterMode.

InnerLeftContent

Gets or sets custom content that is positioned on the left side of the text layout box

public object? InnerLeftContent { get; set; }

Property Value

object

InnerRightContent

Gets or sets custom content that is positioned on the right side of the text layout box

public object? InnerRightContent { get; set; }

Property Value

object

IsDropDownOpen

Gets or sets a value indicating whether the drop-down portion of the control is open.

public bool IsDropDownOpen { get; set; }

Property Value

bool

True if the drop-down is open; otherwise, false. The default is false.

IsTextCompletionEnabled

Gets or sets a value indicating whether the first possible match found during the filtering process will be displayed automatically in the text box.

public bool IsTextCompletionEnabled { get; set; }

Property Value

bool

True if the first possible match found will be displayed automatically in the text box; otherwise, false. The default is false.

ItemFilter

Gets or sets the custom method that uses user-entered text to filter the items specified by the ItemsSource property for display in the drop-down.

public AutoCompleteFilterPredicate<object?>? ItemFilter { get; set; }

Property Value

AutoCompleteFilterPredicate<object>

The custom method that uses the user-entered text to filter the items specified by the ItemsSource property. The default is null.

Remarks

The filter mode is automatically set to Custom if you set the ItemFilter property.

ItemSelector

Gets or sets the custom method that combines the user-entered text and one of the items specified by the ItemsSource.

public AutoCompleteSelector<object>? ItemSelector { get; set; }

Property Value

AutoCompleteSelector<object>

The custom method that combines the user-entered text and one of the items specified by the ItemsSource.

ItemTemplate

Gets or sets the Avalonia.DataTemplate used to display each item in the drop-down portion of the control.

public IDataTemplate ItemTemplate { get; set; }

Property Value

IDataTemplate

The Avalonia.DataTemplate used to display each item in the drop-down. The default is null.

Remarks

You use the ItemTemplate property to specify the visualization of the data objects in the drop-down portion of the AutoCompleteBox control. If your AutoCompleteBox is bound to a collection and you do not provide specific display instructions by using a DataTemplate, the resulting UI of each item is a string representation of each object in the underlying collection.

ItemsSource

Gets or sets a collection that is used to generate the items for the drop-down portion of the AutoCompleteBox control.

public IEnumerable? ItemsSource { get; set; }

Property Value

IEnumerable

The collection that is used to generate the items of the drop-down portion of the AutoCompleteBox control.

MaxDropDownHeight

Gets or sets the maximum height of the drop-down portion of the AutoCompleteBox control.

public double MaxDropDownHeight { get; set; }

Property Value

double

The maximum height of the drop-down portion of the AutoCompleteBox control. The default is PositiveInfinity.

Exceptions

ArgumentException

The specified value is less than 0.

MaxLength

Gets or sets the maximum number of characters that the AutoCompleteBox can accept. This constraint only applies for manually entered (user-inputted) text.

public int MaxLength { get; set; }

Property Value

int

MinimumPopulateDelay

Gets or sets the minimum delay, after text is typed in the text box before the AutoCompleteBox control populates the list of possible matches in the drop-down.

public TimeSpan MinimumPopulateDelay { get; set; }

Property Value

TimeSpan

The minimum delay, after text is typed in the text box, but before the AutoCompleteBox populates the list of possible matches in the drop-down. The default is 0.

MinimumPrefixLength

Gets or sets the minimum number of characters required to be entered in the text box before the AutoCompleteBox displays possible matches.

public int MinimumPrefixLength { get; set; }

Property Value

int

The minimum number of characters to be entered in the text box before the AutoCompleteBox displays possible matches. The default is 1.

Remarks

If you set MinimumPrefixLength to -1, the AutoCompleteBox will not provide possible matches. There is no maximum value, but setting MinimumPrefixLength to value that is too large will prevent the AutoCompleteBox from providing possible matches as well.

SearchText

Gets the text that is used to filter items in the ItemsSource item collection.

public string? SearchText { get; }

Property Value

string

The text that is used to filter items in the ItemsSource item collection.

Remarks

The SearchText value is typically the same as the Text property, but is set after the TextChanged event occurs and before the Populating event.

SelectedItem

Gets or sets the selected item in the drop-down.

public object? SelectedItem { get; set; }

Property Value

object

The selected item in the drop-down.

Remarks

If the IsTextCompletionEnabled property is true and text typed by the user matches an item in the ItemsSource collection, which is then displayed in the text box, the SelectedItem property will be a null reference.

SelectionAdapter

Gets or sets the selection adapter used to populate the drop-down with a list of selectable items.

protected ISelectionAdapter? SelectionAdapter { get; set; }

Property Value

ISelectionAdapter

The selection adapter used to populate the drop-down with a list of selectable items.

Remarks

You can use this property when you create an automation peer to use with AutoCompleteBox or deriving from AutoCompleteBox to create a custom control.

Text

Gets or sets the text in the text box portion of the AutoCompleteBox control.

public string? Text { get; set; }

Property Value

string

The text in the text box portion of the AutoCompleteBox control.

TextFilter

Gets or sets the custom method that uses the user-entered text to filter items specified by the ItemsSource property in a text-based way for display in the drop-down.

public AutoCompleteFilterPredicate<string?>? TextFilter { get; set; }

Property Value

AutoCompleteFilterPredicate<string>

The custom method that uses the user-entered text to filter items specified by the ItemsSource property in a text-based way for display in the drop-down.

Remarks

The search mode is automatically set to Custom if you set the TextFilter property.

TextSelector

Gets or sets the custom method that combines the user-entered text and one of the items specified by the ItemsSource in a text-based way.

public AutoCompleteSelector<string?>? TextSelector { get; set; }

Property Value

AutoCompleteSelector<string>

The custom method that combines the user-entered text and one of the items specified by the ItemsSource in a text-based way.

ValueMemberBinding

Gets or sets the Binding that is used to get the values for display in the text portion of the AutoCompleteBox control.

[AssignBinding]
[InheritDataTypeFromItems("ItemsSource")]
public IBinding? ValueMemberBinding { get; set; }

Property Value

IBinding

The IBinding object used when binding to a collection property.

Watermark 

public string? Watermark { get; set; }

Property Value

string

Methods

FormatValue(object?)

Converts the specified object to a string by using the Avalonia.Data.Binding.Converter and Avalonia.Data.Binding.ConverterCulture values of the binding object specified by the ValueMemberBinding property.

protected virtual string? FormatValue(object? value)

Parameters

value object

The object to format as a string.

Returns

string

The string representation of the specified object.

Remarks

Override this method to provide a custom string conversion.

GetSelectionAdapterPart(INameScope)

Returns the Avalonia.Controls.ISelectionAdapter part, if possible.

protected virtual ISelectionAdapter? GetSelectionAdapterPart(INameScope nameScope)

Parameters

nameScope INameScope

Returns

ISelectionAdapter

A Avalonia.Controls.ISelectionAdapter object, if possible. Otherwise, null.

HasFocus()

Determines whether the text box or drop-down portion of the AutoCompleteBox control has focus.

protected bool HasFocus()

Returns

bool

true to indicate the AutoCompleteBox has focus; otherwise, false.

OnApplyTemplate(TemplateAppliedEventArgs)

Builds the visual tree for the AutoCompleteBox control when a new template is applied.

protected override void OnApplyTemplate(TemplateAppliedEventArgs e)

Parameters

e TemplateAppliedEventArgs

OnDropDownClosed(EventArgs)

Raises the DropDownClosed event.

protected virtual void OnDropDownClosed(EventArgs e)

Parameters

e EventArgs

A EventArgs which contains the event data.

OnDropDownClosing(CancelEventArgs)

Raises the DropDownClosing event.

protected virtual void OnDropDownClosing(CancelEventArgs e)

Parameters

e CancelEventArgs

A Avalonia.Controls.CancelEventArgs that contains the event data.

OnDropDownOpened(EventArgs)

Raises the DropDownOpened event.

protected virtual void OnDropDownOpened(EventArgs e)

Parameters

e EventArgs

A EventArgs that contains the event data.

OnDropDownOpening(CancelEventArgs)

Raises the DropDownOpening event.

protected virtual void OnDropDownOpening(CancelEventArgs e)

Parameters

e CancelEventArgs

A Avalonia.Controls.CancelEventArgs that contains the event data.

OnGotFocus(GotFocusEventArgs)

Provides handling for the Avalonia.UIElement.GotFocus event.

protected override void OnGotFocus(GotFocusEventArgs e)

Parameters

e GotFocusEventArgs

A Avalonia.RoutedEventArgs that contains the event data.

OnKeyDown(KeyEventArgs)

Provides handling for the Avalonia.InputElement.KeyDown event.

protected override void OnKeyDown(KeyEventArgs e)

Parameters

e KeyEventArgs

A KeyEventArgs that contains the event data.

OnLostFocus(RoutedEventArgs)

Provides handling for the Avalonia.UIElement.LostFocus event.

protected override void OnLostFocus(RoutedEventArgs e)

Parameters

e RoutedEventArgs

A Avalonia.RoutedEventArgs that contains the event data.

OnPopulated(PopulatedEventArgs)

Raises the Populated event.

protected virtual void OnPopulated(PopulatedEventArgs e)

Parameters

e PopulatedEventArgs

A PopulatedEventArgs that contains the event data.

OnPopulating(PopulatingEventArgs)

Raises the Populating event.

protected virtual void OnPopulating(PopulatingEventArgs e)

Parameters

e PopulatingEventArgs

A PopulatingEventArgs that contains the event data.

OnSelectionChanged(SelectionChangedEventArgs)

Raises the SelectionChanged event.

protected virtual void OnSelectionChanged(SelectionChangedEventArgs e)

Parameters

e SelectionChangedEventArgs

A SelectionChangedEventArgs that contains the event data.

OnTextChanged(TextChangedEventArgs)

Raises the TextChanged event.

protected virtual void OnTextChanged(TextChangedEventArgs e)

Parameters

e TextChangedEventArgs

A TextChangedEventArgs that contains the event data.

PopulateComplete()

Notifies the AutoCompleteBox that the Avalonia.Controls.AutoCompleteBox.Items property has been set and the data can be filtered to provide possible matches in the drop-down.

public void PopulateComplete()

Remarks

Call this method when you are providing custom population of the drop-down portion of the AutoCompleteBox, to signal the control that you are done with the population process. Typically, you use PopulateComplete when the population process is a long-running process and you want to cancel built-in filtering of the ItemsSource items. In this case, you can handle the Populated event and set PopulatingEventArgs.Cancel to true. When the long-running process has completed you call PopulateComplete to indicate the drop-down is populated.

UpdateDataValidation(AvaloniaProperty, BindingValueType, Exception?)

Called to update the validation state for properties for which data validation is enabled.

protected override void UpdateDataValidation(AvaloniaProperty property, BindingValueType state, Exception? error)

Parameters

property AvaloniaProperty

The property.

state BindingValueType

The current data binding state.

error Exception

The current data binding error, if any.

Events

DropDownClosed

Occurs when the IsDropDownOpen property was changed from true to false and the drop-down is open.

public event EventHandler? DropDownClosed

Event Type

EventHandler

DropDownClosing

Occurs when the IsDropDownOpen property is changing from true to false.

public event EventHandler<CancelEventArgs>? DropDownClosing

Event Type

EventHandler<CancelEventArgs>

DropDownOpened

Occurs when the value of the IsDropDownOpen property has changed from false to true and the drop-down is open.

public event EventHandler? DropDownOpened

Event Type

EventHandler

DropDownOpening

Occurs when the value of the IsDropDownOpen property is changing from false to true.

public event EventHandler<CancelEventArgs>? DropDownOpening

Event Type

EventHandler<CancelEventArgs>

Populated

Occurs when the AutoCompleteBox has populated the drop-down with possible matches based on the Text property.

public event EventHandler<PopulatedEventArgs>? Populated

Event Type

EventHandler<PopulatedEventArgs>

Populating

Occurs when the AutoCompleteBox is populating the drop-down with possible matches based on the Text property.

public event EventHandler<PopulatingEventArgs>? Populating

Event Type

EventHandler<PopulatingEventArgs>

Remarks

If the event is canceled, by setting the PopulatingEventArgs.Cancel property to true, the AutoCompleteBox will not automatically populate the selection adapter contained in the drop-down. In this case, if you want possible matches to appear, you must provide the logic for populating the selection adapter.

SelectionChanged

Occurs when the selected item in the drop-down portion of the AutoCompleteBox has changed.

public event EventHandler<SelectionChangedEventArgs> SelectionChanged

Event Type

EventHandler<SelectionChangedEventArgs>

TextChanged

Occurs asynchronously when the text in the Avalonia.Controls.AutoCompleteBox.TextBox portion of the AutoCompleteBox changes.

public event EventHandler<TextChangedEventArgs>? TextChanged

Event Type

EventHandler<TextChangedEventArgs>