Export (0) Print
Expand All

ItemsControl.ItemsSource Property

Gets or sets a collection used to generate the content of this ItemsControl. This is a dependency property.

Namespace: System.Windows.Controls
Assembly: PresentationFramework (in presentationframework.dll)
XML Namespace:  http://schemas.microsoft.com/winfx/2006/xaml/presentation

[BindableAttribute(true)] 
public IEnumerable ItemsSource { get; set; }
/** @property */
public IEnumerable get_ItemsSource ()

/** @property */
public void set_ItemsSource (IEnumerable value)

public function get ItemsSource () : IEnumerable

public function set ItemsSource (value : IEnumerable)

<object ItemsSource="bindingDeclaration"/>
 bindingDeclaration  A Binding declaration. See Binding Markup Extension for more information. 

Property Value

A collection that is used to generate the content of this ItemsControl. The default value is a null reference (Nothing in Visual Basic).

Identifier field

ItemsSourceProperty

Metadata properties set to true

None

Content Model: This property may be used to add items to an ItemsControl. For more information on the content model for ItemsControl, see Items Control Content Model.

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, ItemsSource property is the property to use. Note that the ItemsSource property supports OneWay binding by default.

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

When ItemsSource is in use, setting the property to a null reference (Nothing in Visual Basic) 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 a null reference (Nothing in Visual Basic), and setting it to a null reference (Nothing in Visual Basic) has no effect.

NoteNote:

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

This example shows how to create and bind to a collection that derives from the ObservableCollection 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 : ObservableCollection<PersonName>
{
    public NameList() : base()
    {
        Add(new PersonName("Willa", "Cather"));
        Add(new PersonName("Isak", "Dinesen"));
        Add(new PersonName("Victor", "Hugo"));
        Add(new PersonName("Jules", "Verne"));
    }
  }

  public class PersonName
  {
      private string firstName;
      private string lastName;

      public PersonName(string first, string last)
      {
          this.firstName = first;
          this.lastName = last;
      }

      public string FirstName
      {
          get { return firstName; }
          set { firstName = value; }
      }

      public string LastName
      {
          get { return lastName; }
          set { lastName = value; }
      }
  }

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. For the complete sample, see Implementing Parameterized MultiBinding Sample.

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 Selection

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

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0

Community Additions

ADD
Show:
© 2014 Microsoft