Export (0) Print
Expand All

ItemsControl.ItemsSource Property

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

Namespace:  System.Windows.Controls
Assembly:  PresentationFramework (in PresentationFramework.dll)
XMLNS for XAML: http://schemas.microsoft.com/winfx/2006/xaml/presentation, http://schemas.microsoft.com/netfx/2007/xaml/presentation

'Declaration
<BindableAttribute(True)> _
Public Property ItemsSource As IEnumerable
<object ItemsSource="bindingDeclaration"/>

XAML Values

bindingDeclaration

A Binding declaration. See Binding Markup Extension for more information.

Property Value

Type: System.Collections.IEnumerable
A collection that is used to generate the content of the ItemsControl. The default is Nothing.

Identifier field

ItemsSourceProperty

Metadata properties set to true

None

Content Model: This property may be used to add items to an ItemsControl.

A common scenario is to use an ItemsControl such as a ListBox, ListView, or TreeView to display a data collection, or to bind an ItemsControl to a collection object. To bind an ItemsControl to a collection object, use the ItemsSource property. Note that the ItemsSource property supports OneWay binding by default.

When the ItemsSource property is set, the Items collection is made read-only and fixed-size.

When ItemsSource is in use, setting the property to Nothing removes the collection and restores usage to Items, which will be an empty ItemCollection. When ItemsSource is not in use, the value of this property is Nothing, and setting it to Nothing has no effect.

NoteNote

In most cases you do not need to implement your own collections. Instead, consider using ObservableCollection(Of T) or other existing collections. For more information, see the "Collection Objects Used as Binding Source" in Binding Sources Overview.

This example shows how to create and bind to a collection that derives from the ObservableCollection(Of T) class, which is a collection class that provides notifications when items get added or removed.

The following example shows the implementation of a NameList collection:

Public Class NameList
    Inherits ObservableCollection(Of PersonName)

    ' Methods 
    Public Sub New()
        MyBase.Add(New PersonName("Willa", "Cather"))
        MyBase.Add(New PersonName("Isak", "Dinesen"))
        MyBase.Add(New PersonName("Victor", "Hugo"))
        MyBase.Add(New PersonName("Jules", "Verne"))
    End Sub 

End Class 

Public Class PersonName
    ' Methods 
    Public Sub New(ByVal first As String, ByVal last As String)
        Me._firstName = first
        Me._lastName = last
    End Sub 


    ' Properties 
    Public Property FirstName() As String 
        Get 
            Return Me._firstName
        End Get 
        Set(ByVal value As String)
            Me._firstName = value
        End Set 
    End Property 

    Public Property LastName() As String 
        Get 
            Return Me._lastName
        End Get 
        Set(ByVal value As String)
            Me._lastName = value
        End Set 
    End Property 


    ' Fields 
    Private _firstName As String 
    Private _lastName As String 
End Class

You can make the collection available for binding the same way you would with other common language runtime (CLR) objects, as described in How to: Make Data Available for Binding in XAML. For example, you can instantiate the collection in XAML and specify the collection as a resource, as shown here:


<Window
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:c="clr-namespace:SDKSample"
  x:Class="SDKSample.Window1"
  Width="400"
  Height="280"
  Title="MultiBinding Sample">
	
  <Window.Resources>
    <c:NameList x:Key="NameListData"/>


...


</Window.Resources>

You can then bind to the collection:

<ListBox Width="200"
         ItemsSource="{Binding Source={StaticResource NameListData}}"
         ItemTemplate="{StaticResource NameItemTemplate}"
         IsSynchronizedWithCurrentItem="True"/>

The definition of NameItemTemplate is not shown here.

NoteNote

The objects in your collection must satisfy the requirements described in the Binding Sources Overview. In particular, if you are using OneWay or TwoWay (for example, you want your UI to update when the source properties change dynamically), you must implement a suitable property changed notification mechanism such as the INotifyPropertyChanged interface.

For more information, see the Binding to Collections section in the Data Binding Overview.

More Code

How to: Bind to a Collection and Display Information Based on SelectionIn a simple master-detail scenario, you have a data-bound ItemsControl such as a ListBox. Based on user selection, you display more information about the selected item. This example shows how to implement this scenario.

.NET Framework

Supported in: 4.5, 4, 3.5, 3.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Show:
© 2014 Microsoft