DataTemplate.RecycleElement(ElementFactoryRecycleArgs) Method

  • Reference

Definition

Namespace:
Windows.UI.Xaml
Edit

Recycles a UIElement that was previously retrieved using GetElement.

void RecycleElement(ElementFactoryRecycleArgs const& args);
public void RecycleElement(ElementFactoryRecycleArgs args);
function recycleElement(args)
Public Sub RecycleElement (args As ElementFactoryRecycleArgs)

Parameters

args
ElementFactoryRecycleArgs

An instance of ElementFactoryRecycleArgs.

Implements

RecycleElement(ElementFactoryRecycleArgs)

Windows requirements

Device family
Windows 10, version 1809 (introduced in 10.0.17763.0)
API contract
Windows.Foundation.UniversalApiContract (introduced in v7.0)

Remarks

The RecycleElement method is used to set aside an element for later re-use, but does not automatically reset the current state of the element. For example, if a Control's Background is programmatically set the value persists when added to the live tree again.

Recycled elements returned from GetElement can be added to the live tree in the same way as newly created elements.

GetElement tries to retrieve an existing instance from those that were recycled. If none are found then it will create a new instance using LoadContent.

Recycling an element may not immediately cause it to be removed from the live element tree. In that situation the Unloaded/Loaded events are not raised unless it is added to a different parent element in the live tree.

Specifying the Parent is not required when calling RecycleElement. However, its use is recommended to enable a performance optimization. When GetElement is called with a Parent value it will look for elements that where recycled for that same Parent. If they're still attached to the parent element then they can be re-used without incurring the additional overhead of re-parenting the element.

Note

RecycleElement does not automatically exclude the recycled element from participating in the tab order. Nor does it hide the element's automation peer from appearing in the automation tree. The platform's built-in virtualizing controls manage this for the elements under their control.

If you're creating a custom virtualizing control from scratch or calling RecycleElement in one-off scenarios then be aware it is your responsibility to exclude recycled elements from the tab order and the tree of automation peers.

You can override GetChildrenInTabFocusOrder and provide the subset of realized elements the framework should use for Tab focus. Similarly, the automation peer for the control should override its GetChildrenCore and exclude recycled elements.

Applies to

See also