ItemsControl.ItemsSource Property

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

Gets or sets a collection used to generate the content of the ItemsControl.

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

Syntax

'Declaration
Public Property ItemsSource As IEnumerable
public IEnumerable ItemsSource { get; set; }
<itemsControl ItemsSource="bindingDeclaration"/>
-or-
<itemsControl ItemsSource="resourceReferenceToIEnumerable"/>

XAML Values

  • bindingDeclaration
    A Binding declaration using a {Binding ....} markup extension. For more information, see Binding Markup Extension or Binding.

  • resourceReferenceToIEnumerable
    A resource reference to an existing object of type IEnumerable from a resources collection. The resource reference must specify the desired IEnumerable by key.

Property Value

Type: System.Collections.IEnumerable
The object that is used to generate the content of the ItemsControl. The default is nulla null reference (Nothing in Visual Basic).

Remarks

Dependency property identifier field: ItemsSourceProperty

You can add items to an ItemsControl by adding items to the Items property or by setting 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.

You should set the ItemsSource to an object that implements the INotifyCollectionChanged interface so that changes in the collection will be reflected in the ItemsControl. The ObservableCollection<T> class defines such an object.

Examples

The following example creates a ListBox, which inherits from ItemsControl, and binds it to a collection of Customer objects. The example sets the DisplayMemberPathProperty to the LastName property of the customer. Therefore, the ListBox displays the following values:

  • Anderberg

  • Ashton

  • Hicks

  • Pica

<Grid>
    <Grid.Resources>
        <src:Customers x:Key="customers"/>
    </Grid.Resources>
    <ListBox ItemsSource="{StaticResource customers}" Width="250" Margin="0,5,0,10" 
       DisplayMemberPath="LastName"/>
</Grid>

The following example shows the Customer class and the collection that the ListBox is bound to.

Public Class Customer
    Private _firstName As String
    Private _lastName As String
    Private _address As String

    Public Property FirstName() As String
        Get
            Return _firstName
        End Get

        Set(ByVal value As String)
            _firstName = value
        End Set
    End Property

    Public Property LastName() As String
        Get
            Return _lastName
        End Get

        Set(ByVal value As String)
            _lastName = value
        End Set
    End Property

    Public Property Address() As String
        Get
            Return _address
        End Get

        Set(ByVal value As String)
            _address = value
        End Set
    End Property

    Public Sub New(ByVal firstName As String, ByVal lastName As String, ByVal address As String)
        Me.FirstName = firstName
        Me.LastName = lastName
        Me.Address = address
    End Sub

End Class

Public Class Customers
    Inherits ObservableCollection(Of Customer)

    Public Sub New()
        Add(New Customer("Michael", "Anderberg", "12 North Third Street, Apartment 45"))
        Add(New Customer("Chris", "Ashton", "34 West Fifth Street, Apartment 67"))
        Add(New Customer("Cassie", "Hicks", "56 East Seventh Street, Apartment 89"))
        Add(New Customer("Guido", "Pica", "78 South Ninth Street, Apartment 10"))
    End Sub

End Class
public class Customer
{
    public String FirstName { get; set; }
    public String LastName { get; set; }
    public String Address { get; set; }

    public Customer(String firstName, String lastName, String address)
    {
        this.FirstName = firstName;
        this.LastName = lastName;
        this.Address = address;
    }

}

public class Customers : ObservableCollection<Customer>
{
    public Customers()
    {
        Add(new Customer("Michael", "Anderberg",
                "12 North Third Street, Apartment 45"));
        Add(new Customer("Chris", "Ashton",
                "34 West Fifth Street, Apartment 67"));
        Add(new Customer("Cassie", "Hicks",
                "56 East Seventh Street, Apartment 89"));
        Add(new Customer("Guido", "Pica",
                "78 South Ninth Street, Apartment 10"));
    }

}

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.