ItemsControl ItemsControl ItemsControl Class

Represents a control that can be used to present a collection of items.

Syntax

Declaration

public class ItemsControlpublic class ItemsControlPublic Class ItemsControl
<ItemsControl ...>
  oneOrMoreItems
</ItemsControl>

Inheritance Hierarchy

Inherited Members

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

An ItemsControl object can serve two roles. It can be used to present a fixed set of items, or it can be used to display a list obtained from data binding to a data source. Using an ItemsControl for data is more common. To display data, specify the binding to the data as the ItemsSource value (or use the data context) and don't populate Items. If you want to display a fixed list, populate Items with one or more FrameworkElement child objects, and don't specify ItemsSource.

There are several controls that inherit from ItemsControl that you can use in your app, but you can also use an ItemsControl directly, because it does offer a basic presentation of data or items. Controls that derive from ItemsControl and which add additional presentation features include: ListView, GridView, ListBox, other Selector derived controls (ComboBox, FlipView ), MenuFlyoutPresenter.

ListView and GridView are the two most commonly used controls for displaying data. For more info on how to use these controls, including sample code, see Adding ListView and GridView controls.

ItemsSource typically references a list of items. This can be a fixed list from a business object, or a list that's designed to fire notifications if the underlying data changes. The list might be a generic interface (for example IList<T>) or a practical class that implements the collection interfaces that Windows Runtime data binding supports. When you display items in an ItemsControl, you can use the ItemTemplate property, the ItemsPanel property, or both to specify the appearance of the items. The DisplayMemberPath property can be used for a master-details view of the data. For more info on how to use these properties in data binding scenarios, how lists are supported, and how to implement two-way bindings or notifications on changes, see the "Binding to collections" section of Data binding in depth. Support for data and items is one of the areas where you'll use different interfaces and techniques for Visual C++ component extensions (C++/CX) than you do for C# or Microsoft Visual Basic; Data binding in depth also includes a table for that info.

You can provide a custom template for an ItemsControl because it is a Control class. But before retemplating ItemsControl you should check whether one of the derived classes already offers a similar template and gives you the presentation experience you want. In particular, if you're looking for data presentation that has an association with the orientation of the items (list is either horizontal or vertical) you should look at ListView and GridView.

ItemsControl implements IItemContainerMapping, which is mainly a helper interface that supports other features. App code seldom calls the IItemContainerMapping methods directly, and controls that derive from ItemsControl or any of the deeper classes typically don't have to reimplement IItemContainerMapping.

ItemsControl derived classes

ItemsControl is the parent class for MenuFlyoutPresenter and Selector. Most of the practical items controls derive from Selector in some way, either through ListViewBase or directly from Selector.

Constructors summary

Initializes a new instance of the ItemsControl class.

Properties summary

Gets or sets the name or path of the property that is displayed for each data item.

Identifies the DisplayMemberPath dependency property.

Gets a collection of GroupStyle objects that define the appearance of each level of groups.

Gets or sets a reference to a custom GroupStyleSelector logic class. The GroupStyleSelector returns different GroupStyle values to use for content based on the characteristics of that content.

Identifies the GroupStyleSelector dependency property.

Gets a value that indicates whether the control is using grouping.

Identifies the IsGrouping dependency property.

Gets the ItemContainerGenerator associated with this ItemsControl.

Gets or sets the style that is used when rendering the item containers.

Identifies the ItemContainerStyle dependency property.

Gets or sets a reference to a custom StyleSelector logic class. The StyleSelector returns different Style values to use for the item container based on characteristics of the object being displayed.

Identifies the ItemContainerStyleSelector dependency property.

Gets or sets the collection of Transition style elements that apply to the item containers of an ItemsControl.

Identifies the ItemContainerTransitions dependency property.

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

Gets or sets the template that defines the panel that controls the layout of items.

Identifies the ItemsPanel dependency property.

Gets the Panel specified by ItemsPanel.

Gets or sets an object source used to generate the content of the ItemsControl.

Identifies the ItemsSource dependency property.

Gets or sets the DataTemplate used to display each item.

Identifies the ItemTemplate dependency property.

Gets or sets a reference to a custom DataTemplateSelector logic class. The DataTemplateSelector referenced by this property returns a template to apply to items.

Identifies the ItemTemplateSelector dependency property.

Methods summary

Returns the container for the item at the specified index within the ItemCollection.

Returns the container corresponding to the specified item.

Returns the ItemsControl that the specified element hosts items for.

Returns the group header container that corresponds to the specified container element.

Returns the index to the item that has the specified, generated container.

Returns the item that corresponds to the specified, generated container.

Returns the ItemsControl that owns the specified container element.

Constructors

  • ItemsControl()
    ItemsControl()
    ItemsControl()
    ItemsControl()

    Initializes a new instance of the ItemsControl class.

    public ItemsControl()public ItemsControl()Public Function ItemsControl() As

Properties

  • DisplayMemberPath
    DisplayMemberPath
    DisplayMemberPath
    DisplayMemberPath

    Gets or sets the name or path of the property that is displayed for each data item.

    public string DisplayMemberPath { get; set; }public string DisplayMemberPath { get; set; }Public ReadWrite Property DisplayMemberPath As string
    <itemsControl DisplayMemberPath="propertyPath"/>
    

    Property Value

    • string
      string
      string

      The name or path of the property that is displayed for each the data item in the control. The default is an empty string ("").

  • DisplayMemberPathProperty
    DisplayMemberPathProperty
    DisplayMemberPathProperty
    DisplayMemberPathProperty

    Identifies the DisplayMemberPath dependency property.

    public static DependencyProperty DisplayMemberPathProperty { get; }public static DependencyProperty DisplayMemberPathProperty { get; }Public Static ReadOnly Property DisplayMemberPathProperty As DependencyProperty

    Property Value

  • GroupStyle
    GroupStyle
    GroupStyle
    GroupStyle

    Gets a collection of GroupStyle objects that define the appearance of each level of groups.

    public IObservableVector<GroupStyle> GroupStyle { get; }public IObservableVector<GroupStyle> GroupStyle { get; }Public ReadOnly Property GroupStyle As IObservableVector<GroupStyle>
    <itemsControl>
      <itemsControl.GroupStyle>
        oneOrMoreGroupStyleObjects
      </itemsControl.GroupStyle>
    </itemsControl>
    
    

    Property Value

    • A collection of GroupStyle objects that define the appearance of each level of groups.

    Remarks

    Note

    ContainerStyle and ContainerStyleSelector are deprecated in Windows 8.1, and are ignored in GroupStyle.

  • GroupStyleSelector
    GroupStyleSelector
    GroupStyleSelector
    GroupStyleSelector

    Gets or sets a reference to a custom GroupStyleSelector logic class. The GroupStyleSelector returns different GroupStyle values to use for content based on the characteristics of that content.

    public GroupStyleSelector GroupStyleSelector { get; set; }public GroupStyleSelector GroupStyleSelector { get; set; }Public ReadWrite Property GroupStyleSelector As GroupStyleSelector
    <itemsControl GroupStyleSelector="groupStyleSelectorReference" />
    

    Property Value

  • GroupStyleSelectorProperty
    GroupStyleSelectorProperty
    GroupStyleSelectorProperty
    GroupStyleSelectorProperty

    Identifies the GroupStyleSelector dependency property.

    public static DependencyProperty GroupStyleSelectorProperty { get; }public static DependencyProperty GroupStyleSelectorProperty { get; }Public Static ReadOnly Property GroupStyleSelectorProperty As DependencyProperty

    Property Value

  • IsGrouping
    IsGrouping
    IsGrouping
    IsGrouping

    Gets a value that indicates whether the control is using grouping.

    public bool IsGrouping { get; }public bool IsGrouping { get; }Public ReadOnly Property IsGrouping As bool

    Property Value

    • bool
      bool
      bool

      true if a control is using grouping; otherwise, false.

  • IsGroupingProperty
    IsGroupingProperty
    IsGroupingProperty
    IsGroupingProperty

    Identifies the IsGrouping dependency property.

    public static DependencyProperty IsGroupingProperty { get; }public static DependencyProperty IsGroupingProperty { get; }Public Static ReadOnly Property IsGroupingProperty As DependencyProperty

    Property Value

  • ItemContainerGenerator
    ItemContainerGenerator
    ItemContainerGenerator
    ItemContainerGenerator

    Gets the ItemContainerGenerator associated with this ItemsControl.

    public ItemContainerGenerator ItemContainerGenerator { get; }public ItemContainerGenerator ItemContainerGenerator { get; }Public ReadOnly Property ItemContainerGenerator As ItemContainerGenerator

    Property Value

  • ItemContainerStyle
    ItemContainerStyle
    ItemContainerStyle
    ItemContainerStyle

    Gets or sets the style that is used when rendering the item containers.

    public Style ItemContainerStyle { get; set; }public Style ItemContainerStyle { get; set; }Public ReadWrite Property ItemContainerStyle As Style
    <itemsControl>
      <itemsControl.ItemContainerStyle>
        inlineStyle
      </itemsControl.ItemContainerStyle>
    </itemsControl>
    

    Property Value

    • The style applied to the item containers. The default is null.

  • ItemContainerStyleProperty
    ItemContainerStyleProperty
    ItemContainerStyleProperty
    ItemContainerStyleProperty

    Identifies the ItemContainerStyle dependency property.

    public static DependencyProperty ItemContainerStyleProperty { get; }public static DependencyProperty ItemContainerStyleProperty { get; }Public Static ReadOnly Property ItemContainerStyleProperty As DependencyProperty

    Property Value

  • ItemContainerStyleSelector
    ItemContainerStyleSelector
    ItemContainerStyleSelector
    ItemContainerStyleSelector

    Gets or sets a reference to a custom StyleSelector logic class. The StyleSelector returns different Style values to use for the item container based on characteristics of the object being displayed.

    public StyleSelector ItemContainerStyleSelector { get; set; }public StyleSelector ItemContainerStyleSelector { get; set; }Public ReadWrite Property ItemContainerStyleSelector As StyleSelector
    <itemsControl ItemContainerStyleSelector="styleSelectorReference" />
    

    Property Value

  • ItemContainerStyleSelectorProperty
    ItemContainerStyleSelectorProperty
    ItemContainerStyleSelectorProperty
    ItemContainerStyleSelectorProperty

    Identifies the ItemContainerStyleSelector dependency property.

    public static DependencyProperty ItemContainerStyleSelectorProperty { get; }public static DependencyProperty ItemContainerStyleSelectorProperty { get; }Public Static ReadOnly Property ItemContainerStyleSelectorProperty As DependencyProperty

    Property Value

  • ItemContainerTransitions
    ItemContainerTransitions
    ItemContainerTransitions
    ItemContainerTransitions

    Gets or sets the collection of Transition style elements that apply to the item containers of an ItemsControl.

    public TransitionCollection ItemContainerTransitions { get; set; }public TransitionCollection ItemContainerTransitions { get; set; }Public ReadWrite Property ItemContainerTransitions As TransitionCollection
    <itemsControl>
      <itemsControl.ItemContainerTransitions>
        <TransitionCollection>
          oneOrMoreTransitions
        </TransitionCollection>
      </itemsControl.ItemContainerTransitions>
    </itemsControl>
    

    Property Value

    Remarks

    Important

    The XAML syntax for properties that have a TransitionCollection value is unusual in that you must declare an explicit TransitionCollection object element as the value, and then provide object elements as child elements of TransitionCollection for each of the transition animations you want to use. For most other XAML collection properties you could omit the collection object element because it can be implicit, but TransitionCollection doesn't support the implicit collection usage. For more info on implicit collections and XAML, see XAML syntax guide.

    Items collections can have transition animations associated with add or remove actions, or for drop target scenarios.

    This property is more typically set in a Style setter rather than inline on an object element in UI definition. For more info, see Styling controls.

    The default template for GridView includes existing transition animations. Specifically, the default ItemContainerTransitions value already contains values for AddDeleteThemeTransition, ContentThemeTransition, ReorderThemeTransition and EntranceThemeTransition (with IsStaggeringEnabled="False"). If you are setting a new value for ItemContainerTransitions on GridView, consider reproducing these same theme animations as a starting point.

    To remove all default content transitions from a GridView, you might have to re-template the ContainerStyle. The transition behavior for items and their containers are interrelated.

  • ItemContainerTransitionsProperty
    ItemContainerTransitionsProperty
    ItemContainerTransitionsProperty
    ItemContainerTransitionsProperty

    Identifies the ItemContainerTransitions dependency property.

    public static DependencyProperty ItemContainerTransitionsProperty { get; }public static DependencyProperty ItemContainerTransitionsProperty { get; }Public Static ReadOnly Property ItemContainerTransitionsProperty As DependencyProperty

    Property Value

  • Items
    Items
    Items
    Items

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

    public ItemCollection Items { get; }public ItemCollection Items { get; }Public ReadOnly Property Items As ItemCollection
    <itemsControl>
      oneOrMoreItems
    </itemsControl>
    

    Property Value

  • ItemsPanel
    ItemsPanel
    ItemsPanel
    ItemsPanel

    Gets or sets the template that defines the panel that controls the layout of items.

    public ItemsPanelTemplate ItemsPanel { get; set; }public ItemsPanelTemplate ItemsPanel { get; set; }Public ReadWrite Property ItemsPanel As ItemsPanelTemplate
    <itemsControl>
      <itemsControl.ItemsPanel>
        singlePanelTemplate
      </itemsControl.ItemsPanel>
    </itemsControl>
    

    Property Value

    Remarks

    Note

    ComboBox uses a CarouselPanel as its ItemsPanel. Using a different panel as the ItemsPanel of ComboBox is not supported and might result in undesired behavior.

  • ItemsPanelProperty
    ItemsPanelProperty
    ItemsPanelProperty
    ItemsPanelProperty

    Identifies the ItemsPanel dependency property.

    public static DependencyProperty ItemsPanelProperty { get; }public static DependencyProperty ItemsPanelProperty { get; }Public Static ReadOnly Property ItemsPanelProperty As DependencyProperty

    Property Value

  • ItemsPanelRoot
    ItemsPanelRoot
    ItemsPanelRoot
    ItemsPanelRoot

    Gets the Panel specified by ItemsPanel.

    public Panel ItemsPanelRoot { get; }public Panel ItemsPanelRoot { get; }Public ReadOnly Property ItemsPanelRoot As Panel

    Property Value

  • ItemsSource
    ItemsSource
    ItemsSource
    ItemsSource

    Gets or sets an object source used to generate the content of the ItemsControl.

    public object ItemsSource { get; set; }public object ItemsSource { get; set; }Public ReadWrite Property ItemsSource As object
    <itemsControl ItemsSource="bindingDeclaration"/>
    -or-
    <itemsControl ItemsSource="resourceReferenceToSource"/>
    

    Property Value

    • object
      object
      object

      The object that is used to generate the content of the ItemsControl. The default is null.

  • ItemsSourceProperty
    ItemsSourceProperty
    ItemsSourceProperty
    ItemsSourceProperty

    Identifies the ItemsSource dependency property.

    public static DependencyProperty ItemsSourceProperty { get; }public static DependencyProperty ItemsSourceProperty { get; }Public Static ReadOnly Property ItemsSourceProperty As DependencyProperty

    Property Value

  • ItemTemplate
    ItemTemplate
    ItemTemplate
    ItemTemplate

    Gets or sets the DataTemplate used to display each item.

    public DataTemplate ItemTemplate { get; set; }public DataTemplate ItemTemplate { get; set; }Public ReadWrite Property ItemTemplate As DataTemplate
    <itemsControl>
      <itemsControl.ItemTemplate>
        singleDataTemplate
      </itemsControl.ItemTemplate>
    </itemsControl>
    

    Property Value

  • ItemTemplateProperty
    ItemTemplateProperty
    ItemTemplateProperty
    ItemTemplateProperty

    Identifies the ItemTemplate dependency property.

    public static DependencyProperty ItemTemplateProperty { get; }public static DependencyProperty ItemTemplateProperty { get; }Public Static ReadOnly Property ItemTemplateProperty As DependencyProperty

    Property Value

  • ItemTemplateSelector
    ItemTemplateSelector
    ItemTemplateSelector
    ItemTemplateSelector

    Gets or sets a reference to a custom DataTemplateSelector logic class. The DataTemplateSelector referenced by this property returns a template to apply to items.

    public DataTemplateSelector ItemTemplateSelector { get; set; }public DataTemplateSelector ItemTemplateSelector { get; set; }Public ReadWrite Property ItemTemplateSelector As DataTemplateSelector
    <itemsControl ItemTemplateSelector="dataTemplateSelectorReference" />
    

    Property Value

  • ItemTemplateSelectorProperty
    ItemTemplateSelectorProperty
    ItemTemplateSelectorProperty
    ItemTemplateSelectorProperty

    Identifies the ItemTemplateSelector dependency property.

    public static DependencyProperty ItemTemplateSelectorProperty { get; }public static DependencyProperty ItemTemplateSelectorProperty { get; }Public Static ReadOnly Property ItemTemplateSelectorProperty As DependencyProperty

    Property Value

Methods

  • ContainerFromIndex(System.Int32)
    ContainerFromIndex(System.Int32)
    ContainerFromIndex(System.Int32)
    ContainerFromIndex(System.Int32)

    Returns the container for the item at the specified index within the ItemCollection.

    public DependencyObject ContainerFromIndex(System.Int32 index)public DependencyObject ContainerFromIndex(System.Int32 index)Public Function ContainerFromIndex(index As System.Int32) As DependencyObject

    Parameters

    • index
      System.Int32
      System.Int32
      System.Int32

      The index of the item to retrieve.

    Returns

  • ContainerFromItem(System.Object)
    ContainerFromItem(System.Object)
    ContainerFromItem(System.Object)
    ContainerFromItem(System.Object)

    Returns the container corresponding to the specified item.

    public DependencyObject ContainerFromItem(System.Object item)public DependencyObject ContainerFromItem(System.Object item)Public Function ContainerFromItem(item As System.Object) As DependencyObject

    Parameters

    • item
      System.Object
      System.Object
      System.Object

      The item to retrieve the container for.

    Returns

  • GetItemsOwner(Windows.UI.Xaml.DependencyObject)
    GetItemsOwner(Windows.UI.Xaml.DependencyObject)
    GetItemsOwner(Windows.UI.Xaml.DependencyObject)
    GetItemsOwner(Windows.UI.Xaml.DependencyObject)

    Returns the ItemsControl that the specified element hosts items for.

    public static ItemsControl GetItemsOwner(Windows.UI.Xaml.DependencyObject element)public static ItemsControl GetItemsOwner(Windows.UI.Xaml.DependencyObject element)Public Static Function GetItemsOwner(element As Windows.UI.Xaml.DependencyObject) As ItemsControl

    Parameters

    Returns

  • GroupHeaderContainerFromItemContainer(Windows.UI.Xaml.DependencyObject)
    GroupHeaderContainerFromItemContainer(Windows.UI.Xaml.DependencyObject)
    GroupHeaderContainerFromItemContainer(Windows.UI.Xaml.DependencyObject)
    GroupHeaderContainerFromItemContainer(Windows.UI.Xaml.DependencyObject)

    Returns the group header container that corresponds to the specified container element.

    public DependencyObject GroupHeaderContainerFromItemContainer(Windows.UI.Xaml.DependencyObject itemContainer)public DependencyObject GroupHeaderContainerFromItemContainer(Windows.UI.Xaml.DependencyObject itemContainer)Public Function GroupHeaderContainerFromItemContainer(itemContainer As Windows.UI.Xaml.DependencyObject) As DependencyObject

    Parameters

    Returns

  • IndexFromContainer(Windows.UI.Xaml.DependencyObject)
    IndexFromContainer(Windows.UI.Xaml.DependencyObject)
    IndexFromContainer(Windows.UI.Xaml.DependencyObject)
    IndexFromContainer(Windows.UI.Xaml.DependencyObject)

    Returns the index to the item that has the specified, generated container.

    public int IndexFromContainer(Windows.UI.Xaml.DependencyObject container)public int IndexFromContainer(Windows.UI.Xaml.DependencyObject container)Public Function IndexFromContainer(container As Windows.UI.Xaml.DependencyObject) As int

    Parameters

    Returns

    • int
      int
      int

      The index to the item that corresponds to the specified generated container.

  • ItemFromContainer(Windows.UI.Xaml.DependencyObject)
    ItemFromContainer(Windows.UI.Xaml.DependencyObject)
    ItemFromContainer(Windows.UI.Xaml.DependencyObject)
    ItemFromContainer(Windows.UI.Xaml.DependencyObject)

    Returns the item that corresponds to the specified, generated container.

    public object ItemFromContainer(Windows.UI.Xaml.DependencyObject container)public object ItemFromContainer(Windows.UI.Xaml.DependencyObject container)Public Function ItemFromContainer(container As Windows.UI.Xaml.DependencyObject) As object

    Parameters

    Returns

    • object
      object
      object

      The contained item, or the container if it does not contain an item.

  • ItemsControlFromItemContainer(Windows.UI.Xaml.DependencyObject)
    ItemsControlFromItemContainer(Windows.UI.Xaml.DependencyObject)
    ItemsControlFromItemContainer(Windows.UI.Xaml.DependencyObject)
    ItemsControlFromItemContainer(Windows.UI.Xaml.DependencyObject)

    Returns the ItemsControl that owns the specified container element.

    public static ItemsControl ItemsControlFromItemContainer(Windows.UI.Xaml.DependencyObject container)public static ItemsControl ItemsControlFromItemContainer(Windows.UI.Xaml.DependencyObject container)Public Static Function ItemsControlFromItemContainer(container As Windows.UI.Xaml.DependencyObject) As ItemsControl

    Parameters

    Returns

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ThreadingAttribute
Windows.UI.Xaml.Markup.ContentPropertyAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.ComposableAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll