| -api-id | -api-type |
|---|---|
T:Microsoft.UI.Xaml.Controls.ItemsControl |
winrt class |
Represents a control that can be used to present a collection of items.
<ItemsControl ...>
oneOrMoreItems
</ItemsControl>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) 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 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.
Control, ListView, GridView, Selector, Controls list, Adding ListView and GridView controls, Data binding in depth