UIElementCollection UIElementCollection UIElementCollection Class

Represents an ordered collection of UIElement objects.

Syntax

Declaration

public sealed class UIElementCollectionpublic sealed class UIElementCollectionPublic NotInheritable Class UIElementCollection
<panelobject>
  oneOrMoreChildren
</panelobject>

Remarks

A UIElementCollection is the type of object that you get from the Children property of a Panel. For example, if you get a value from Grid.Children, that value is a UIElementCollection instance. All the properties that use a UIElementCollection in the Windows Runtime API are read-only properties, where the property is initialized with zero items when an object is first instantiated. But you can then add, remove or query items in the collection at run time, using the UIElementCollection properties and methods.

The type of the items in the UIElementCollection is constrained as UIElement. But UIElement is a base element class in Windows Runtime using XAML, so there are hundreds of element types that can be treated as a UIElement and can thus be one of the items in a UIElementCollection.

Enumerating the collection in C# or Microsoft Visual Basic

A UIElementCollection is enumerable, so you can use language-specific syntax such as foreach in C# to enumerate the items in the UIElementCollection. The compiler does the type-casting for you and you won't need to cast to IEnumerable<UIElement> explicitly. If you do need to cast explicitly, for example if you want to call GetEnumerator, cast to IEnumerable<T> with a UIElement constraint.

Properties summary

Gets the size (count) of the collection.

Methods summary

Adds a new item to the collection.

Removes all items from the collection.

Returns the iterator object that can iterate over the items in the UIElementCollection.

Returns the item located at the specified index.

Retrieves multiple elements in a single pass through the iterator.

Gets an immutable view into the collection.

Retrieves the index of the specified item.

Inserts the specified item at the specified index.

Moves the item at the specified index to a new location in the collection.

Removes the item at the specified index.

Removes the last item in the collection.

Initially clears the collection, then inserts the provided array as new items.

Sets the value at the specified index to the UIElement value specified.

Properties

  • Size
    Size
    Size
    Size

    Gets the size (count) of the collection.

    public uint Size { get; }public uint Size { get; }Public ReadOnly Property Size As uint

    Property Value

    • uint
      uint
      uint

      The count of items in the collection.

    Remarks

    The Size value returns the true number of items. API that use the index, such as GetAt(System.UInt32), use a zero-based index, so you would subtract one from Size in order to specify that you want the last item in the collection.

    If you are programming using C# or Microsoft Visual Basic, see Count.

Methods

  • Append(Windows.UI.Xaml.UIElement)
    Append(Windows.UI.Xaml.UIElement)
    Append(Windows.UI.Xaml.UIElement)
    Append(Windows.UI.Xaml.UIElement)

    Adds a new item to the collection.

    public void Append(Windows.UI.Xaml.UIElement)public void Append(Windows.UI.Xaml.UIElement)Public Function Append(Windows.UI.Xaml.UIElement) As void

    Parameters

    Remarks

    Append(Windows.UI.Xaml.UIElement) adds the item to the end of the collection. If you want to insert an item into the beginning or middle of a collection, use InsertAt(System.UInt32,Windows.UI.Xaml.UIElement).

    If you are programming using C# or Microsoft Visual Basic, see Add.

  • Clear()
    Clear()
    Clear()
    Clear()

    Removes all items from the collection.

    public void Clear()public void Clear()Public Function Clear() As void

    Remarks

    The Clear() method can be used when programming in C#, Microsoft Visual Basic or Visual C++ component extensions (C++/CX). The method signature is the same in each of these languages, and the behavior is the same.

  • First()
    First()
    First()
    First()

    Returns the iterator object that can iterate over the items in the UIElementCollection.

    public IIterator<UIElement> First()public IIterator<UIElement> First()Public Function First() As IIterator( Of UIElement )

    Returns

    • The iterator object. The iterator's current position is at the 0-index position, or at the collection end if the collection is empty.

    Remarks

    A convenient way to hold the iterator returned by First() is to assign the return value to a variable that is declared with the auto type deduction keyword. Then use IIterator<T> API as part of a while loop. For example:

    auto iterator1 = uieCollection->First();
    while (iterator1->HasCurrent)
    {
        auto currentItem = iterator1->Current;
        //your logic here that does something with currentItem
        iterator1->MoveNext();
    }
    
  • GetAt(System.UInt32)
    GetAt(System.UInt32)
    GetAt(System.UInt32)
    GetAt(System.UInt32)

    Returns the item located at the specified index.

    public UIElement GetAt(System.UInt32)public UIElement GetAt(System.UInt32)Public Function GetAt(System.UInt32) As UIElement

    Parameters

    • index
      System.UInt32
      System.UInt32
      System.UInt32

      The integer index for the value to retrieve.

    Returns

    Remarks

    If you are programming using C# or Microsoft Visual Basic, see Item (indexer).

  • GetMany(System.UInt32,Windows.UI.Xaml.UIElement[])
    GetMany(System.UInt32,Windows.UI.Xaml.UIElement[])
    GetMany(System.UInt32,Windows.UI.Xaml.UIElement[])
    GetMany(System.UInt32,Windows.UI.Xaml.UIElement[])

    Retrieves multiple elements in a single pass through the iterator.

    public uint GetMany(System.UInt32,Windows.UI.Xaml.UIElement[])public uint GetMany(System.UInt32,Windows.UI.Xaml.UIElement[])Public Function GetMany(System.UInt32,Windows.UI.Xaml.UIElement[]) As uint

    Parameters

    • startIndex
      System.UInt32
      System.UInt32
      System.UInt32

      The index from which to start retrieval.

    • items
      Windows.UI.Xaml.UIElement[]
      Windows.UI.Xaml.UIElement[]
      Windows.UI.Xaml.UIElement[]

      Provides the destination for the result. Size the initial array size as a "capacity" in order to specify how many results should be retrieved.

    Returns

    • uint
      uint
      uint

      The number of items retrieved.

    Remarks

    If you are programming using C# or Microsoft Visual Basic, see CopyTo.

  • GetView()
    GetView()
    GetView()
    GetView()

    Gets an immutable view into the collection.

    public IVectorView<UIElement> GetView()public IVectorView<UIElement> GetView()Public Function GetView() As IVectorView( Of UIElement )

    Returns

    • An object representing the immutable collection view. This object implements IVectorView<T> with a UIElement constraint.

    Remarks

    If you are programming using C# or Microsoft Visual Basic, see CopyTo.

  • IndexOf(Windows.UI.Xaml.UIElement,System.UInt32)
    IndexOf(Windows.UI.Xaml.UIElement,System.UInt32)
    IndexOf(Windows.UI.Xaml.UIElement,System.UInt32)
    IndexOf(Windows.UI.Xaml.UIElement,System.UInt32)

    Retrieves the index of the specified item.

    public bool IndexOf(Windows.UI.Xaml.UIElement,System.UInt32)public bool IndexOf(Windows.UI.Xaml.UIElement,System.UInt32)Public Function IndexOf(Windows.UI.Xaml.UIElement,System.UInt32) As bool

    Parameters

    • value

      The value to find in the collection.

    • index
      System.UInt32
      System.UInt32
      System.UInt32

      The index of the item to find, if found.

    Returns

    • bool
      bool
      bool

      true if an item with the specified value was found; otherwise, false.

    Remarks

    If you are programming using C# or Microsoft Visual Basic, see IndexOf(Windows.UI.Xaml.UIElement,System.UInt32).

  • InsertAt(System.UInt32,Windows.UI.Xaml.UIElement)
    InsertAt(System.UInt32,Windows.UI.Xaml.UIElement)
    InsertAt(System.UInt32,Windows.UI.Xaml.UIElement)
    InsertAt(System.UInt32,Windows.UI.Xaml.UIElement)

    Inserts the specified item at the specified index.

    public void InsertAt(System.UInt32,Windows.UI.Xaml.UIElement)public void InsertAt(System.UInt32,Windows.UI.Xaml.UIElement)Public Function InsertAt(System.UInt32,Windows.UI.Xaml.UIElement) As void

    Parameters

    • index
      System.UInt32
      System.UInt32
      System.UInt32

      The index at which to set the value.

    • value

      The value to set.

    Remarks

    InsertAt(System.UInt32,Windows.UI.Xaml.UIElement) expands the collection and moves all subsequent index items by one. In contrast, SetAt(System.UInt32,Windows.UI.Xaml.UIElement) replaces the item at the index, and the collection count remains the same.

    If you are programming using C# or Microsoft Visual Basic, see InsertAt(System.UInt32,Windows.UI.Xaml.UIElement).

  • Move(System.UInt32,System.UInt32)
    Move(System.UInt32,System.UInt32)
    Move(System.UInt32,System.UInt32)
    Move(System.UInt32,System.UInt32)

    Moves the item at the specified index to a new location in the collection.

    public void Move(System.UInt32,System.UInt32)public void Move(System.UInt32,System.UInt32)Public Function Move(System.UInt32,System.UInt32) As void

    Parameters

    • oldIndex
      System.UInt32
      System.UInt32
      System.UInt32

      The zero-based index specifying the location of the item to be moved.

    • newIndex
      System.UInt32
      System.UInt32
      System.UInt32

      The zero-based index specifying the new location of the item.

    Remarks

    Calling this method offers advantages over removing an item and adding it to a new location. Specifically, not as much tree rebuilding is required internally, and panels or controls that use UIElementCollection for items can be more responsive.

    An example of a scenario where using Move(System.UInt32,System.UInt32) may be useful is if you have a collection view or a specialized panel that supports a user experience where items wrap around. In this case you might want to move an item from the start of the collection to the end or vice versa, without forcing the entire visual tree under the panel or view to be rebuilt.

  • RemoveAt(System.UInt32)
    RemoveAt(System.UInt32)
    RemoveAt(System.UInt32)
    RemoveAt(System.UInt32)

    Removes the item at the specified index.

    public void RemoveAt(System.UInt32)public void RemoveAt(System.UInt32)Public Function RemoveAt(System.UInt32) As void

    Parameters

    • index
      System.UInt32
      System.UInt32
      System.UInt32

      The index position of the item to remove.

    Remarks

    If successful, calling this method reduces the collection size by one. Items with index values greater than the called index have their index values reduced by one.

    If you are programming using C# or Microsoft Visual Basic, see RemoveAt(System.UInt32). The behavior of each language's RemoveAt is basically the same.

  • RemoveAtEnd()
    RemoveAtEnd()
    RemoveAtEnd()
    RemoveAtEnd()

    Removes the last item in the collection.

    public void RemoveAtEnd()public void RemoveAtEnd()Public Function RemoveAtEnd() As void

    Remarks

    If successful, calling this method reduces the collection size by one.

    If you are programming using C# or Microsoft Visual Basic, see RemoveAt(System.UInt32) (pass an index value of Count minus one).

  • ReplaceAll(Windows.UI.Xaml.UIElement[])
    ReplaceAll(Windows.UI.Xaml.UIElement[])
    ReplaceAll(Windows.UI.Xaml.UIElement[])
    ReplaceAll(Windows.UI.Xaml.UIElement[])

    Initially clears the collection, then inserts the provided array as new items.

    public void ReplaceAll(Windows.UI.Xaml.UIElement[])public void ReplaceAll(Windows.UI.Xaml.UIElement[])Public Function ReplaceAll(Windows.UI.Xaml.UIElement[]) As void

    Parameters

    • items
      Windows.UI.Xaml.UIElement[]
      Windows.UI.Xaml.UIElement[]
      Windows.UI.Xaml.UIElement[]

      The new collection items.

    Remarks

    For implementations that track a "changed" event, the initial reset fires an event, but the items added do not fire discrete per-item events.

    If you are programming using C# or Microsoft Visual Basic, there is no single-call equivalent to ReplaceAll(Windows.UI.Xaml.UIElement[]). Use Clear() and then successive calls to Add.

  • SetAt(System.UInt32,Windows.UI.Xaml.UIElement)
    SetAt(System.UInt32,Windows.UI.Xaml.UIElement)
    SetAt(System.UInt32,Windows.UI.Xaml.UIElement)
    SetAt(System.UInt32,Windows.UI.Xaml.UIElement)

    Sets the value at the specified index to the UIElement value specified.

    public void SetAt(System.UInt32,Windows.UI.Xaml.UIElement)public void SetAt(System.UInt32,Windows.UI.Xaml.UIElement)Public Function SetAt(System.UInt32,Windows.UI.Xaml.UIElement) As void

    Parameters

    • index
      System.UInt32
      System.UInt32
      System.UInt32

      The index at which to set the value.

    • value

      The value to set.

    Remarks

    If you are programming using C# or Microsoft Visual Basic, see Item (indexer).

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll