ListBox Overview
The ListBox control provides a list of items from which users can select. This topic introduces the ListBox class and illustrates how to use this control in both Extensible Application Markup Language (XAML) and code for C#.
This topic contains the following sections.
- ListBox Control
- Creating ListBoxes
- Populating ListBoxItems by Using Data Binding
- Using ListBox Selection Modes
- Using Rich Content in ListBoxes
- Related Topics
ListBox Control
A ListBox organizes a list of items and enables users to select from those items. In addition, other controls can use and encapsulate a ListBox.
The following figure illustrates a typical ListBox.
Typical ListBox
.gif)
Creating ListBoxes
The ListBox in the following XAML example contains multiple list items. Notice that a ListBoxItem wraps each side of the ListBox child elements.
<TextBox Name="tb" Width="140" Height="30"></TextBox>
<ListBox Name="lb" Width="100" Height="55" SelectionChanged="PrintText" SelectionMode="Single">
<ListBoxItem>Item 1</ListBoxItem>
<ListBoxItem>Item 2</ListBoxItem>
<ListBoxItem>Item 3</ListBoxItem>
<ListBoxItem>Item 4</ListBoxItem>
<ListBoxItem>Item 5</ListBoxItem>
<ListBoxItem>Item 6</ListBoxItem>
<ListBoxItem>Item 7</ListBoxItem>
<ListBoxItem>Item 8</ListBoxItem>
<ListBoxItem>Item 9</ListBoxItem>
<ListBoxItem>Item 10</ListBoxItem>
</ListBox>
After using XAML to create the ListBox, you can add an event handler to handle SelectionChanged events. In this example, the event handler is PrintText. When the user selects an item, the event handler displays the item name.
You must write event handlers in a procedural programming language, such as C# or Visual Basic. The following example shows an event handler in C# code.
void PrintText(object sender, SelectionChangedEventArgs args)
{
ListBoxItem lbi = ((sender as ListBox).SelectedItem as ListBoxItem);
tb.Text = " You selected " + lbi.Content.ToString() + ".";
}
Sub PrintText(ByVal sender As Object, ByVal e As SelectionChangedEventArgs)
Dim lbsender As ListBox
Dim li As ListBoxItem
lbsender = CType(sender, ListBox)
li = CType(lbsender.SelectedItem, ListBoxItem)
tb.Text = " You selected " & li.Content.ToString & "."
End Sub
For the complete sample, see ListBox Sample.
The following example shows how to generate a ListBox in C#. The example creates a ListBox and adds list items; then the ListBox (lb) is added to a panel element (spanel2).
lb = new ListBox();
lb.Width = 80;
lb.HorizontalAlignment = HorizontalAlignment.Left;
li1 = new ListBoxItem();
li1.Content = "Item 1";
lb.Items.Add(li1);
li2 = new ListBoxItem();
li2.Content = "Item 2";
lb.Items.Add(li2);
li3 = new ListBoxItem();
li3.Content = "Item 3";
lb.Items.Add(li3);
spanel2.Children.Add(lb);
For the complete sample, see Creating Controls Sample.
Populating ListBoxItems by Using Data Binding
You can create list boxes without separately specifying the contents of each ListBoxItem. Instead, use data binding to bind data to the individual items.
The following example shows how to create a ListBox that populates each ListBoxItem by binding data to a data source that is called Colors. In this case, you need not use ListBoxItem tags to specify the content of each item.
<ListBox Name="myListBox" HorizontalAlignment="Left" SelectionMode="Extended"
Width="265" Height="55" Background="HoneyDew"
ItemsSource="{Binding Source={StaticResource Colors}}" IsSynchronizedWithCurrentItem="true">
</ListBox>
For the complete sample, see List Box Sample.
Using ListBox Selection Modes
The SelectionMode property for a ListBox determines how many items a user can select at one time. You can set the property to Single (the default value), Multiple, or Extended. When you set this property to one of these enumerations, users can select the following:
One item (Single).
More than one contiguous items (Multiple). Users can select multiple items by clicking items with the mouse or holding down the SHIFT key and pressing the space key..
Groups of items (Extended). Users select groups of items by holding down the CTRL key while using the mouse to select items or holding down the CTRL key and pressing the space key.
The following example shows how to create a ListBox that enables users to select more than one items (Multiple selections).
<ListBox Width="265" Height="55" HorizontalAlignment="Left" SelectionMode="Multiple">
<DockPanel><Image Source="data\cat.png"/><TextBlock>CAT</TextBlock></DockPanel>
<DockPanel><Image Source="data\dog.png"/><TextBlock>DOG</TextBlock></DockPanel>
<DockPanel><Image Source="data\fish.png"/><TextBlock>FISH</TextBlock></DockPanel>
</ListBox>
For the complete sample, see List Box Sample.
Using Rich Content in ListBoxes
ListBoxItem controls can contain rich content such as images. The following example shows how to create a ListBox whose items contain an image and a TextBlock inside a DockPanel.
<ListBox Width="265" Height="55" HorizontalAlignment="Left" SelectionMode="Multiple">
<DockPanel><Image Source="data\cat.png"/><TextBlock>CAT</TextBlock></DockPanel>
<DockPanel><Image Source="data\dog.png"/><TextBlock>DOG</TextBlock></DockPanel>
<DockPanel><Image Source="data\fish.png"/><TextBlock>FISH</TextBlock></DockPanel>
</ListBox>
For the complete sample, see List Box Sample.
See Also
Tasks
How to: Bind a ListBox to Data
How to: Use ListBox Selection Modes
How to: Create a ListBox with an Event Handler