Table of Contents

Class ItemsControl

Namespace
Avalonia.Controls
Assembly
Avalonia.Controls.dll

Displays a collection of items.

[PseudoClasses(new string[] { ":empty", ":singleitem" })]
public class ItemsControl : TemplatedControl, INotifyPropertyChanged, IDataContextProvider, ILogical, IThemeVariantHost, IResourceHost, IResourceNode, IStyleHost, ISetLogicalParent, ISetInheritanceParent, ISupportInitialize, IStyleable, INamed, IInputElement, IDataTemplateHost, ISetterValue, IChildIndexProvider
Inheritance
ItemsControl
Implements
Derived
Inherited Members
Extension Methods

Constructors

ItemsControl()

Initializes a new instance of the ItemsControl class.

public ItemsControl()

Fields

DisplayMemberBindingProperty

Defines the DisplayMemberBinding property

public static readonly StyledProperty<IBinding?> DisplayMemberBindingProperty

Field Value

StyledProperty<IBinding>

ItemContainerThemeProperty

Defines the ItemContainerTheme property.

public static readonly StyledProperty<ControlTheme?> ItemContainerThemeProperty

Field Value

StyledProperty<ControlTheme>

ItemCountProperty

Defines the ItemCount property.

public static readonly DirectProperty<ItemsControl, int> ItemCountProperty

Field Value

DirectProperty<ItemsControl, int>

ItemTemplateProperty

Defines the ItemTemplate property.

public static readonly StyledProperty<IDataTemplate?> ItemTemplateProperty

Field Value

StyledProperty<IDataTemplate>

ItemsPanelProperty

Defines the ItemsPanel property.

public static readonly StyledProperty<ITemplate<Panel?>> ItemsPanelProperty

Field Value

StyledProperty<ITemplate<Panel>>

ItemsSourceProperty

Defines the ItemsSource property.

public static readonly StyledProperty<IEnumerable?> ItemsSourceProperty

Field Value

StyledProperty<IEnumerable>

Properties

DefaultRecycleKey

Gets a default recycle key that can be used when an ItemsControl supports a single container type.

protected static object DefaultRecycleKey { get; }

Property Value

object

DisplayMemberBinding

Gets or sets the IBinding to use for binding to the display member of each item.

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

Property Value

IBinding

ItemContainerGenerator

Gets the ItemContainerGenerator for the control.

public ItemContainerGenerator ItemContainerGenerator { get; }

Property Value

ItemContainerGenerator

ItemContainerTheme

Gets or sets the ControlTheme that is applied to the container element generated for each item.

public ControlTheme? ItemContainerTheme { get; set; }

Property Value

ControlTheme

ItemCount

Gets the number of items being displayed by the ItemsControl.

public int ItemCount { get; }

Property Value

int

ItemTemplate

Gets or sets the data template used to display the items in the control.

[InheritDataTypeFromItems("ItemsSource")]
public IDataTemplate? ItemTemplate { get; set; }

Property Value

IDataTemplate

Items

Gets the items to display.

[Content]
public ItemCollection Items { get; }

Property Value

ItemCollection

Remarks

You use either the Items or the ItemsSource property to specify the collection that should be used to generate the content of your ItemsControl. When the ItemsSource property is set, the Items collection is made read-only and fixed-size.

When ItemsSource is in use, setting the ItemsSource property to null removes the collection and restores usage to Items, which will be an empty ItemCollection.

ItemsPanel

Gets or sets the panel used to display the items.

public ITemplate<Panel?> ItemsPanel { get; set; }

Property Value

ITemplate<Panel>

ItemsPanelRoot

Gets the Panel specified by ItemsPanel.

public Panel? ItemsPanelRoot { get; }

Property Value

Panel

ItemsSource

Gets or sets a collection used to generate the content of the ItemsControl.

public IEnumerable? ItemsSource { get; set; }

Property Value

IEnumerable

Remarks

A common scenario is to use an ItemsControl such as a ListBox to display a data collection, or to bind an ItemsControl to a collection object. To bind an ItemsControl to a collection object, use the ItemsSource property.

When the ItemsSource property is set, the Items collection is made read-only and fixed-size.

When ItemsSource is in use, setting the property to null removes the collection and restores usage to Items, which will be an empty ItemCollection.

ItemsView

Gets a read-only view of the items in the ItemsControl.

public ItemsSourceView ItemsView { get; }

Property Value

ItemsSourceView

Presenter

Gets the items presenter control.

public ItemsPresenter? Presenter { get; }

Property Value

ItemsPresenter

Methods

ClearContainerForItemOverride(Control)

Undoes the effects of the PrepareContainerForItemOverride(Control, object?, int) method.

protected virtual void ClearContainerForItemOverride(Control container)

Parameters

container Control

The container element.

ContainerForItemPreparedOverride(Control, object?, int)

Called when a container has been fully prepared to display an item.

protected virtual void ContainerForItemPreparedOverride(Control container, object? item, int index)

Parameters

container Control

The container control.

item object

The item being displayed.

index int

The index of the item being displayed.

Remarks

This method will be called when a container has been fully prepared and added to the logical and visual trees, but may be called before a layout pass has completed. It is called immediately before the ContainerPrepared event is raised.

ContainerFromIndex(int)

Returns the container for the item at the specified index.

public Control? ContainerFromIndex(int index)

Parameters

index int

The index of the item to retrieve.

Returns

Control

The container for the item at the specified index within the item collection, if the item has a container; otherwise, null.

ContainerFromItem(object)

Returns the container corresponding to the specified item.

public Control? ContainerFromItem(object item)

Parameters

item object

The item to retrieve the container for.

Returns

Control

A container that corresponds to the specified item, if the item has a container and exists in the collection; otherwise, null.

ContainerIndexChangedOverride(Control, int, int)

Called when the index for a container changes due to an insertion or removal in the items collection.

protected virtual void ContainerIndexChangedOverride(Control container, int oldIndex, int newIndex)

Parameters

container Control

The container whose index changed.

oldIndex int

The old index.

newIndex int

The new index.

CreateContainerForItemOverride(object?, int, object?)

Creates or a container that can be used to display an item.

protected virtual Control CreateContainerForItemOverride(object? item, int index, object? recycleKey)

Parameters

item object
index int
recycleKey object

Returns

Control

GetNextControl(INavigableContainer, NavigationDirection, IInputElement?, bool) 

protected static IInputElement? GetNextControl(INavigableContainer container, NavigationDirection direction, IInputElement? from, bool wrap)

Parameters

container INavigableContainer
direction NavigationDirection
from IInputElement
wrap bool

Returns

IInputElement

GetRealizedContainers()

Gets the currently realized containers.

public IEnumerable<Control> GetRealizedContainers()

Returns

IEnumerable<Control>

IndexFromContainer(Control)

Returns the index to the item that has the specified, generated container.

public int IndexFromContainer(Control container)

Parameters

container Control

The generated container to retrieve the item index for.

Returns

int

The index to the item that corresponds to the specified generated container, or -1 if container is not found.

ItemFromContainer(Control)

Returns the item that corresponds to the specified, generated container.

public object? ItemFromContainer(Control container)

Parameters

container Control

The control that corresponds to the item to be returned.

Returns

object

The contained item, or the container if it does not contain an item.

ItemsControlFromItemContainer(Control)

Returns the ItemsControl that owns the specified container control.

public static ItemsControl? ItemsControlFromItemContainer(Control container)

Parameters

container Control

The container.

Returns

ItemsControl

The owning ItemsControl or null if the control is not an items container.

NeedsContainerOverride(object?, int, out object?)

Determines whether the specified item can be its own container.

protected virtual bool NeedsContainerOverride(object? item, int index, out object? recycleKey)

Parameters

item object

The item to check.

index int

The index of the item.

recycleKey object

When the method returns, contains a key that can be used to locate a previously recycled container of the correct type, or null if the item cannot be recycled. If the item is its own container then by definition it cannot be recycled, so recycleKey shoud be set to null.

Returns

bool

true if the item needs a container; otherwise false if the item can itself be used as a container.

NeedsContainer<T>(object?, out object?)

A default implementation of NeedsContainerOverride(object?, int, out object?) that returns true and sets the recycle key to DefaultRecycleKey if the item is not a T .

protected bool NeedsContainer<T>(object? item, out object? recycleKey) where T : Control

Parameters

item object

The item.

recycleKey object

When the method returns, contains DefaultRecycleKey if item is not of type T; otherwise null.

Returns

bool

true if item is of type T; otherwise false.

Type Parameters

T

The container type.

OnApplyTemplate(TemplateAppliedEventArgs)

Called when the control's template is applied. In simple terms, this means the method is called just before the control is displayed.

protected override void OnApplyTemplate(TemplateAppliedEventArgs e)

Parameters

e TemplateAppliedEventArgs

The event args.

OnCreateAutomationPeer()

Returns a new, type-specific AutomationPeer implementation for the control.

protected override AutomationPeer OnCreateAutomationPeer()

Returns

AutomationPeer

The type-specific AutomationPeer implementation.

OnGotFocus(GotFocusEventArgs)

Called before the GotFocus event occurs.

protected override void OnGotFocus(GotFocusEventArgs e)

Parameters

e GotFocusEventArgs

The event args.

OnKeyDown(KeyEventArgs)

Handles directional navigation within the ItemsControl.

protected override void OnKeyDown(KeyEventArgs e)

Parameters

e KeyEventArgs

The key events.

OnPropertyChanged(AvaloniaPropertyChangedEventArgs)

Called when a avalonia property changes on the object.

protected override void OnPropertyChanged(AvaloniaPropertyChangedEventArgs change)

Parameters

change AvaloniaPropertyChangedEventArgs

The property change details.

PrepareContainerForItemOverride(Control, object?, int)

Prepares the specified element to display the specified item.

protected virtual void PrepareContainerForItemOverride(Control container, object? item, int index)

Parameters

container Control

The element that's used to display the specified item.

item object

The item to display.

index int

The index of the item to display.

RefreshContainers()

Refreshes the containers displayed by the control.

protected void RefreshContainers()

Remarks

Causes all containers to be unrealized and re-realized.

ScrollIntoView(int)

Scrolls the specified item into view.

public void ScrollIntoView(int index)

Parameters

index int

The index of the item.

ScrollIntoView(object)

Scrolls the specified item into view.

public void ScrollIntoView(object item)

Parameters

item object

The item.

Events

ContainerClearing

Occurs each time a container is cleared.

public event EventHandler<ContainerClearingEventArgs>? ContainerClearing

Event Type

EventHandler<ContainerClearingEventArgs>

Remarks

This event is raised immediately each time an container is cleared, such as when it falls outside the range of realized items or the corresponding item is removed.

ContainerIndexChanged

Occurs for each realized container when the index for the item it represents has changed.

public event EventHandler<ContainerIndexChangedEventArgs>? ContainerIndexChanged

Event Type

EventHandler<ContainerIndexChangedEventArgs>

Remarks

This event is raised for each realized container where the index for the item it represents has changed. For example, when another item is added or removed in the data source, the index for items that come after in the ordering will be impacted.

ContainerPrepared

Occurs each time a container is prepared for use.

public event EventHandler<ContainerPreparedEventArgs>? ContainerPrepared

Event Type

EventHandler<ContainerPreparedEventArgs>

Remarks

The prepared element might be newly created or an existing container that is being re- used.

PreparingContainer

Occurs immediately before a container is prepared for use.

public event EventHandler<ContainerPreparedEventArgs>? PreparingContainer

Event Type

EventHandler<ContainerPreparedEventArgs>

Remarks

The prepared element might be newly created or an existing container that is being re- used.