ListBox
The
ListBox is an ItemsControl which displays items in a multi-line list box and allows individual selection.The items to display in the
ListBox are specified using the Items property. This property will often be bound to a collection on the control's DataContext:<ListBox Items="{Binding MyItems}"/>
You can customize how an item is displayed by specifying an
ItemTemplate. For example to display each item inside a red border with rounded corners:<ListBox Items="{Binding MyItems}">
<ListBox.ItemTemplate>
<DataTemplate>
<Border Background="Red" CornerRadius="4" Padding="4">
<TextBlock Text="{Binding}"/>
</Border>
</DataTemplate>
</ListBox.ItemTemplate>
</ListBox>
Each item displayed in a
ListBox will be wrapped in a ListBoxItem - this is called the container. The container hosts the content specified in the ItemTemplate but it is not part of the ItemTemplate itself. It is the container that contains the logic for displaying selected items.Sometimes you will want to customize the container itself. You can do this by including a style targeting
ListBoxItem in the ListBox:<ListBox Items="{Binding Items}">
<ListBox.Styles>
<!-- Give the ListBoxItems a fixed with of 100 and right-align them -->
<Style Selector="ListBoxItem">
<Setter Property="Width" Value="100"/>
<Setter Property="HorizontalAlignment" Value="Right"/>
</Style>
</ListBox.Styles>
<ListBox>
In WPF and UWP this is done via the
ItemContainerStyle - this property does not exist in Avalonia; you should use the method outlined above.There are several properties related to selection on
ListBox:It is recommended that you only bind one of the
SelectedIndex, SelectedItem, SelectedItems or Selection properties.Controls the type of selection that can be made on the
ListBox:Property | Description |
|---|---|
Single | Only a single item can be selected (default) |
Multiple | Multiple items can be selected |
Toggle | Item selection can be toggled by tapping/spacebar. When not enabled, shift or ctrl must be used to select multiple items |
AlwaysSelected | An item will always be selected as long as there are items to select. |
These values can be combined, e.g.:
<ListBox SelectionMode="Multiple,Toggle">
Exposes the index of the selected item, or in the case of multiple selection the first selected item. You will often want to bind this to a view model if your list
SelectionMode is set to Single.<ListBox SelectedIndex="{Binding SelectedIndex}">
public MyViewModel : ReactiveObject
{
int selectedIndex;
public int SelectedIndex
{
get => selectedIndex;
set => this.RaiseAndSetIfChanged(ref selectedIndex, value);
}
}
By default bindings to this property are two-way.
Exposes the selected item in the
Items collection, or in the case of multiple selection the first selected item. You will often want to bind this to a view model if your list SelectionMode is set to Single.<ListBox SelectedItem="{Binding SelectedItem}">
public MyViewModel : ReactiveObject
{
MyItem selectedItem;
public MyItem SelectedItem
{
get => selectedItem;
set => this.RaiseAndSetIfChanged(ref selectedItem, value);
}
}
By default bindings to this property are two-way.
Do not bind to this property if your
Items collection contains duplicates as it is impossible to distinguish between duplicate values.The
Selection property exposes an ISelectionModel object with various methods to track multiple selected items. You can create a SelectionModel object in your view model and bind it to this property and subsequently control the selection from your view model.ISelectionModel is optimized for large collections. Because of this it is recommended that you use this property in preference to SelectedItems for performance reasons.Once
Selection is bound to a SelectionModel, SelectedItems will no longer function.SelectionModel also exposes batching functionality through its Update() method and a SelectionChanged event which details exactly which items have been selected and deselected.<ListBox Items="{Binding Items}" Selection="{Binding Selection}">
public class MyViewModel
{
public MyViewModel()
{
Items = CreateItems();
// SelectionModel.Source can be set to Items here, or if it is left null it will be set by
// the `ListBox` when bound.
Selection = new SelectionModel();
Selection.SelectionChanged += SelectionChanged;
// Select item 10 in Items.
Selection.Select(10);
}
public ObservableCollection<MyItem> Items { get; }
public SelectionModel Selection { get; }
// A method bound to e.g. a button which will select the first 100 items.
public void SelectFirst100() => Selection.SelectRange(0, 99);
// Switch to single selection via the view model.
public void SwitchToSingleSelect() => Selection.SingleSelect = true;
void SelectionChanged(object sender, SelectionModelSelectionChangedEventArgs e)
{
// ... handle selection changed
}
}
By default bindings to this property are one-way.
This property holds the selected items in an
IList. It can be bound to any list that implements IList but it will usually be bound to a collection which also implements INotifyCollectionChanged such as ObservableCollection<>.For various reasons the performance of
SelectedItems can be very poor, particularly on large collections. It is recommended that you use the Selection property instead.<ListBox SelectedItems="{Binding SelectedItems}">
public MyViewModel : ReactiveObject
{
public ObservableCollection<MyItem> SelectedItems { get; } = new ObservableCollection<MyItem>();
}
By default if an item is too wide to display in the
ListBox, a horizontal scrollbar will be displayed. If instead you want items to be constrained to the width of the ListBox (for example if you want wrapping text in the items) you can disable the horizontal scrollbar by setting ScrollViewer.HorizontalScrollBarVisibility="Disabled".<ListBox Items="{Binding MyItems}" Width="250" ScrollViewer.HorizontalScrollBarVisibility="Disabled">
<ListBox.ItemTemplate>
<DataTemplate>
<Border Background="Red" CornerRadius="4" Padding="4">
<TextBlock Text="{Binding}" TextWrapping="Wrap"/>
</Border>
</DataTemplate>
</ListBox.ItemTemplate>
</ListBox>
Last modified 5mo ago