Article
11/18/2011

ItemsControl.Items Property

Microsoft Silverlight will reach end of support after October 2021. Learn more.

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

Namespace: System.Windows.Controls
Assembly: System.Windows (in System.Windows.dll)

Syntax

'Declaration
Public ReadOnly Property Items As ItemCollection

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, nulla null reference (Nothing in Visual Basic). The default is an empty collection.

Remarks

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 nulla null reference (Nothing in Visual Basic), the items in the items property are read-only. You cannot add an object or change the objects in the Items property.

Examples

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.

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

    <ListBox Name="lb1" Width="350" 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.

Dim sb As System.Text.StringBuilder = New System.Text.StringBuilder()

lb1.Items(0) = "Change this item"
Dim item As Object
For Each item In lb1.Items
    sb.AppendLine(item.ToString())
Next

tb1.Text = sb.ToString()

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>
  <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.

Dim sb2 As System.Text.StringBuilder = New System.Text.StringBuilder()

'lb2.Items[0] = "Change this item"; 'Raises an exception.
For Each item In lb2.Items
    sb2.AppendLine(item.ToString())
Next

tb2.Text = sb2.ToString()

//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
    Inherits System.Collections.ObjectModel.ObservableCollection(Of String)

    Public Sub New()
        Add("Item 1")
        Add("Item 2")
        Add("Item 3")
        Add("Item 4")
        Add("Item 5")
    End Sub
End Class

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");
    }
}

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Partager via