ItemsControl

Introduction

ItemsControl provides a way to display a collection of controls. By default all contained controls are stacked and allow scrolling with a ScrollBar.

ItemsControl is similar to ListBox, but it is more general since it does not support selection. When items are added to the Items property the ItemsControl does not create a control which inherits from ListBoxItem. Similarly, its VisualTemplate does not need to be a type which supports a ListBoxItem.

ItemsControl inherits from ScrollViewer, so it supports the same scrolling behavior, including the MouseWheelScrollSpeed property for tuning mouse-wheel scroll speed. For more information about inherited properties, see the ScrollViewer page.

Code Example: Adding to Items Property

If an object is added to the Items property then the ItemsControl creates a view to represent this. By default this is a Label instance, but it can be customized through the VisualTemplate property.

The following code creates ten Labels by adding integers to the Items property.

// Initialize
var itemsControl = new ItemsControl();
itemsControl.AddToRoot();
for(int i = 0; i < 10; i++)
{
    itemsControl.Items.Add(i);
}

Try on XnaFiddle.NET

ItemsControl with ten items

Code Example: Fixed-Size Scrollable List

Setting explicit Width and Height values gives the ItemsControl a fixed size so that its content scrolls when it overflows. This is useful for displaying a non-selectable scrollable list in a fixed area.

// Initialize
var itemsControl = new ItemsControl();
itemsControl.AddToRoot();
itemsControl.Width = 200;
itemsControl.Height = 150;
for(int i = 0; i < 20; i++)
{
    itemsControl.Items.Add("Item " + i);
}

Try on XnaFiddle.NET

Decorations

ItemsControl supports inert decorations — separators, headers, and other chrome that render between rows without becoming items. Add them with AddDecoration, InsertDecorationAfter, and InsertDecorationBefore. Because these methods are defined on ItemsControl, they are also available on ListBox, where the behavior is documented in full — see Decorations and Separators on the ListBox page.