ItemsControl.Items Property

May 11, 2014

Gets the collection used to generate the content of the control.

Namespace:  System.Windows.Controls
Assembly:  System.Windows (in System.Windows.dll)
XMLNS for XAML: Not mapped to an xmlns.

public ItemCollection Items { get; }
<itemsControl>
  oneOrMoreItems
</itemsControl>

XAML Values

oneOrMoreItems

One or more object elements.

Property Value

Type: System.Windows.Controls.ItemCollection
The collection that is used to generate the content of the control, if it exists; otherwise, null. The default is an empty collection.

You can add items to an ItemsControl by adding items to the Items property or by binding the ItemsSource property to a data collection. You can add objects of different types to Items. If ItemsSource is not null, the items in the items property are read-only. You cannot add an object or change the objects in the Items property.

The following example creates a ListBox, which inherits from ItemsControl, and adds multiple types of objects to the Items property. Note that the example does not use the <ListBox.Items> or <ItemCollection> tag. You can add items as direct child elements to <ListBox> or any other ItemsControl.


<ListBox xmlns:sys="clr-namespace:System;assembly=mscorlib">

  <sys:String>This is a string in a ListBox</sys:String>

  <Rectangle Height="40" Width="40"  Fill="Blue"/>

  <StackPanel Name="itemToSelect">
    <Ellipse Height="40" Fill="Blue"/>
    <TextBlock>Text below an Ellipse</TextBlock>
  </StackPanel>

  <TextBlock>String in a TextBlock</TextBlock>
</ListBox>


The previous example produces output that resembles the following illustration.

ListBox with multiple types of objects

A ListBox that contains strings and UIElements.

The following example creates a ListBox, which inherits from ItemsControl, and adds strings to the Items property. For this example, src is defined as xmlns:src="clr-namespace:ItemsControlSnippets".


  <StackPanel Grid.Column="0" xmlns:sys="clr-namespace:System;assembly=mscorlib">
    <StackPanel.Resources>
      <src:Items x:Key="items"/>
    </StackPanel.Resources>

    <ListBox Name="lb1" Margin="0,5,0,5" >
      <sys:String>Item 1</sys:String>
      <sys:String>Item 2</sys:String>
      <sys:String>Item 3</sys:String>
      <sys:String>Item 4</sys:String>
      <sys:String>Item 5</sys:String>
    </ListBox>
    <TextBlock Name="tb1" />
</StackPanel>


The following example iterates through each string in the Items property of the ListBox in the previous example and adds each item to the TextBlock, tb1. It also changes the value of the first item in the ListBox. This is possible because the previous example adds items to the Items property, instead of setting the ItemsSource property.


lb1.Items[0] = "Change this item";
System.Text.StringBuilder sb = new System.Text.StringBuilder();

foreach (object item in lb1.Items)
{
    sb.AppendLine(item.ToString());

}

tb1.Text = sb.ToString();


The following example creates a ListBox and sets the ItemsSource property to a collection of strings.


<StackPanel Grid.Column="1">
  <StackPanel.Resources>
    <src:Items x:Key="items"/>
  </StackPanel.Resources>

  <ListBox Name="lb2" ItemsSource="{Binding Source={StaticResource items}}"/>
  <TextBlock Name="tb2"/>
</StackPanel>


The following example iterates through each string in the Items property of the ListBox in the previous example and adds each item to the TextBlock, tb2. The Items property contains the collection of strings that the ListBox is bound to. You can get the strings by using the Items property, but you cannot add or change the strings.


//lb2.Items[0] = "Change this item"; //Raises an exception.
System.Text.StringBuilder sb2 = new System.Text.StringBuilder();

foreach (object item in lb2.Items)
{
    sb2.AppendLine(item.ToString());

}

tb2.Text = sb2.ToString();


The following example shows the collection of strings that the ListBox is bound to.


public class Items : 
    System.Collections.ObjectModel.ObservableCollection<string>
{
    public Items()
    {
        Add("Item 1");
        Add("Item 2");
        Add("Item 3");
        Add("Item 4");
        Add("Item 5");
    }
}


Windows Phone OS

Supported in: 8.1, 8.0, 7.1, 7.0

Windows Phone

Show:
© 2014 Microsoft