Class ItemContainerGenerator

Namespace

Avalonia.Controls.Generators

Assembly

Avalonia.Controls.dll

Generates containers for an ItemsControl.

public class ItemContainerGenerator

Inheritance

object

ItemContainerGenerator

Derived

TreeItemContainerGenerator

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

When creating a container for an item from a VirtualizingPanel, the following process should be followed:

• NeedsContainer(object?, int, out object?) should first be called to determine whether the item needs a container. This method will return true if the item should be wrapped in a container control, or false if the item itself can be used as a container.
• If NeedsContainer(object?, int, out object?) returns true then the CreateContainer(object?, int, object?) method should be called to create a new container, passing the recycle key returned from NeedsContainer(object?, int, out object?).
• If the panel supports recycling and the recycle key is non-null then the recycle key should be recorded for the container (e.g. in an attached property or the realized container list).
• PrepareItemContainer(Control, object?, int) method should be called for the container.
• The container should then be added to the panel using AddInternalChild(Control)
• Finally, ItemContainerPrepared(Control, object?, int) should be called.

NOTE: If NeedsContainer(object?, int, out object?) in the first step above returns false then the above steps should be carried out a single time: the first time the item is displayed. Otherwise the steps should be carried out each time a new container is realized for an item.

When unrealizing a container, the following process should be followed:

• If NeedsContainer(object?, int, out object?) for the item returned false then the item cannot be unrealized or recycled.
• Otherwise, ClearItemContainer(Control) should be called for the container
• If recycling is supported by the panel and the container then the container should be added to a recycle pool keyed on the recycle key returned from NeedsContainer(object?, int, out object?). It is assumed that recycled containers will not be removed from the panel but instead hidden from view using e.g. container.IsVisible = false.
• If recycling is not supported then the container should be removed from the panel.

When recycling an unrealized container, the following process should be followed:

• NeedsContainer(object?, int, out object?) should be called to determine whether the item needs a container, and if so, the recycle key.
• A container should be taken from the recycle pool keyed on the returned recycle key.
• The container should be made visible.
• PrepareItemContainer(Control, object?, int) method should be called for the container.
• ItemContainerPrepared(Control, object?, int) should be called.

NOTE: Although this class is similar to that found in WPF/UWP, in Avalonia this class only concerns itself with generating and clearing item containers; it does not maintain a record of the currently realized containers, that responsibility is delegated to the items panel.

Methods

ClearItemContainer(Control)

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

public void ClearItemContainer(Control container)

Parameters

container Control

The container control.

Remarks

This method must be called when a container is unrealized. The container must have already have been removed from the virtualizing panel's list of realized containers before this method is called. This method must not be called if NeedsContainer(object?, int, out object?) returned false for the item.

CreateContainer(object?, int, object?)

Creates a new container control.

public Control CreateContainer(object? item, int index, object? recycleKey)

Parameters

item object

The item to display.

index int

The index of the item.

recycleKey object

The recycle key returned from NeedsContainer(object?, int, out object?)

Returns

Control

The newly created container control.

Remarks

Before calling this method, NeedsContainer(object?, int, out object?) should be called to determine whether the item itself should be used as a container. After calling this method, PrepareItemContainer(Control, object?, int) must be called to prepare the container to display the specified item.

If the panel supports recycling then the returned recycle key should be stored alongside the container and when container becomes eligible for recycling the container should be placed in a recycle pool using this key. If the returned recycle key is null then the container cannot be recycled.

ItemContainerIndexChanged(Control, int, int)

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

public void ItemContainerIndexChanged(Control container, int oldIndex, int newIndex)

Parameters

container Control

The container whose index changed.

oldIndex int

The old index.

newIndex int

The new index.

ItemContainerPrepared(Control, object?, int)

Notifies the ItemsControl that a container has been fully prepared to display an item.

public void ItemContainerPrepared(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 must 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 must be called regardless of the result of NeedsContainer(object?, int, out object?) but if that method returned false then must be called only a single time.

NeedsContainer(object?, int, out object?)

Determines whether the specified item needs to be wrapped in a container control.

public bool NeedsContainer(object? item, int index, out object? recycleKey)

Parameters

item object

The item to display.

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.

Returns

bool

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

PrepareItemContainer(Control, object?, int)

Prepares the specified element as the container for the corresponding item.

public void PrepareItemContainer(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.

Remarks

If NeedsContainer(object?, int, out object?) is false for an item, then this method must only be called a single time; otherwise this method must be called after the container is created, and each subsequent time the container is recycled to display a new item.