ItemContainerGenerator Class
Definition
Generates containers for an Avalonia.Controls.ItemsControl.
public class ItemContainerGenerator
Remarks
When creating a container for an item from a Avalonia.Controls.VirtualizingPanel, the following process should be followed:
- Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,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 Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,object@) returns true then the Avalonia.Controls.Generators.ItemContainerGenerator.CreateContainer(object,int,object) method should be called to create a new container, passing the recycle key returned from Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,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).
- Avalonia.Controls.Generators.ItemContainerGenerator.PrepareItemContainer(Avalonia.Controls.Control,object,int) method should be called for the container.
- The container should then be added to the panel using Avalonia.Controls.VirtualizingPanel.AddInternalChild(Avalonia.Controls.Control)
- Finally, Avalonia.Controls.Generators.ItemContainerGenerator.ItemContainerPrepared(Avalonia.Controls.Control,object,int) should be called.
NOTE: If Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,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 Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,object@) for the item returned false then the item cannot be unrealized or recycled.
- Otherwise, Avalonia.Controls.Generators.ItemContainerGenerator.ClearItemContainer(Avalonia.Controls.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
Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,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:
- Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,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.
- Avalonia.Controls.Generators.ItemContainerGenerator.PrepareItemContainer(Avalonia.Controls.Control,object,int) method should be called for the container.
- Avalonia.Controls.Generators.ItemContainerGenerator.ItemContainerPrepared(Avalonia.Controls.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
| Name | Description |
|---|---|
| ClearItemContainer | Undoes the effects of the Avalonia.Controls.Generators.ItemContainerGenerator.PrepareItemContainer(Avalonia.Controls.Control,object,int) method. |
| CreateContainer | Creates a new container control. |
| ItemContainerIndexChanged | Called when the index for a container changes due to an insertion or removal in the items collection. |
| ItemContainerPrepared | Notifies the Avalonia.Controls.ItemsControl that a container has been fully prepared to display an item. |
| NeedsContainer | No summary available. |
| PrepareItemContainer | Prepares the specified element as the container for the corresponding item. |
ClearItemContainer Method
Undoes the effects of the Avalonia.Controls.Generators.ItemContainerGenerator.PrepareItemContainer(Avalonia.Controls.Control,object,int) method.
public void ClearItemContainer(Avalonia.Controls.Control container)
Parameters
container Avalonia.Controls.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 Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,object@) returned false for the item.
CreateContainer Method
Creates a new container control.
public Avalonia.Controls.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 Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,object@)
Returns
The newly created container control.
Remarks
Before calling this method, Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,object@) should be called to determine whether the item itself should be used as a container. After calling this method, Avalonia.Controls.Generators.ItemContainerGenerator.PrepareItemContainer(Avalonia.Controls.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 Method
Called when the index for a container changes due to an insertion or removal in the items collection.
public void ItemContainerIndexChanged(Avalonia.Controls.Control container, int oldIndex, int newIndex)
Parameters
container Avalonia.Controls.Control
The container whose index changed.
oldIndex int
The old index.
newIndex int
The new index.
ItemContainerPrepared Method
Notifies the Avalonia.Controls.ItemsControl that a container has been fully prepared to display an item.
public void ItemContainerPrepared(Avalonia.Controls.Control container, object item, int index)
Parameters
container Avalonia.Controls.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 Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,object@) but if that method returned false then must be called only a single time.
NeedsContainer Method
public bool NeedsContainer(object item, int index, object& recycleKey)
Parameters
item object
index int
recycleKey object&
Returns
bool
PrepareItemContainer Method
Prepares the specified element as the container for the corresponding item.
public void PrepareItemContainer(Avalonia.Controls.Control container, object item, int index)
Parameters
container Avalonia.Controls.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 Avalonia.Controls.Generators.ItemContainerGenerator.NeedsContainer(object,int,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.