Click to Rate and Give Feedback
MSDN
MSDN Library
Web Development
Silverlight 3
ListBox Class
Collapse All/Expand All Collapse All
This page is specific to
Microsoft Silverlight 3

Other versions are also available for the following:
.NET Framework Class Library for Silverlight
ListBox Class

Contains a list of selectable items.

Namespace:  System.Windows.Controls
Assembly:  System.Windows (in System.Windows.dll)
Visual Basic (Declaration)
<TemplateVisualStateAttribute(Name := "InvalidFocused", GroupName := "ValidationStates")> _
<TemplatePartAttribute(Name := "ScrollViewer", Type := GetType(ScrollViewer))> _
<TemplateVisualStateAttribute(Name := "Valid", GroupName := "ValidationStates")> _
<TemplateVisualStateAttribute(Name := "InvalidUnfocused", GroupName := "ValidationStates")> _
Public Class ListBox _
    Inherits Selector
Visual Basic (Usage)
Dim instance As ListBox
C#
[TemplateVisualStateAttribute(Name = "InvalidFocused", GroupName = "ValidationStates")]
[TemplatePartAttribute(Name = "ScrollViewer", Type = typeof(ScrollViewer))]
[TemplateVisualStateAttribute(Name = "Valid", GroupName = "ValidationStates")]
[TemplateVisualStateAttribute(Name = "InvalidUnfocused", GroupName = "ValidationStates")]
public class ListBox : Selector
XAML Object Element Usage
<ListBox .../>

ListBox is a control that displays a collection of items. More than one item in a ListBox is visible at a time. You specify whether the ListBox allows multiple selections by using the SelectionMode property.

ListBox is an ItemsControl. You set its content by using the Items or ItemsSource properties. For more information about content models, see Control Content Models. You can either populate the ListBox control directly, or bind it to a collection of items. For more information about populating a ListBox, see How to: Display Data in a ListBox.

The following illustration shows a ListBox control that contains some unbound text items.

ListBox Control

ListBox Control

Customizing the ListBox Control

To apply the same property settings to multiple ListBox controls, use the Style property. You can apply a style to each item displayed in the ListBox by setting the ItemContainerStyle property. To change the visual structure and visual behavior of a ListBox, copy and modify its default style and template. For more information, see Control Customization.

If a dependency property for a ListBox is set by its default style, the property might change from its default value when the ListBox appears in the application. For more information, see Dependency Property Value Precedence. You can get the default style and template for ListBox from ListBox Styles and Templates.

NoteNote:

Setting a visual property will only have an effect if that property is both present in ListBox control's default template and is set by using a TemplateBinding. You can find a list of visual properties in the "Changing the Visual Structure of a Control" section of Customizing the Appearance of an Existing Control by Using a ControlTemplate.

The following code example creates a page with several ListBox controls configured in a variety of ways.

Run this sample

XAML
<UserControl x:Class="ListBoxSnippetEx.Page"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" 
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" 
    xmlns:src="clr-namespace:ListBoxSnippetEx"
     >

    <StackPanel x:Name="LayoutRoot" Background="White" Margin="10,10,10,10">
        <StackPanel Orientation="Horizontal" >
            <TextBlock Margin="5" Text="ListBox with unbound data:" />
        <ListBox Width="150" Margin="0,5,0,10">
            <TextBlock Text="TextBlock" />
            <TextBox Text="TextBox" />
            <Button Content="Button"  />
            <Rectangle Fill="LightBlue" Height="20" Width="100"  Margin="2,2,2,2"/>
            <Ellipse Fill="Coral" Height="20" Width="150"  Margin="2,2,2,2"/>
        </ListBox>

        <TextBlock Margin="5" Text="ListBox with bound data:" />
        <Grid>
            <Grid.Resources>
                <src:Customers x:Key="customers"/>
            </Grid.Resources>
            <ListBox ItemsSource="{StaticResource customers}" Width="250" Margin="0,5,0,10" 
               DisplayMemberPath="LastName"/>
        </Grid>
</StackPanel>
        <StackPanel Orientation="Horizontal" >
            <TextBlock Margin="5" Text="ListBox with ItemTemplate:" Width="160" />
            <Grid>
                <Grid.Resources>
                    <src:Customers x:Key="customers"/>
                </Grid.Resources>

                <ListBox ItemsSource="{StaticResource customers}" Width="350" Margin="0,5,0,10">
                    <ListBox.ItemTemplate>
                        <DataTemplate>
                            <StackPanel Orientation="Horizontal">
                                <TextBlock Padding="5,0,5,0"
                      Text="{Binding FirstName}" />
                                <TextBlock Text="{Binding LastName}" />
                                <TextBlock Text=", " />
                                <TextBlock Text="{Binding Address}" />
                            </StackPanel>
                        </DataTemplate>
                    </ListBox.ItemTemplate>
                </ListBox>
            </Grid>
            <Grid>
                <Grid.Resources>
                    <Style x:Key="horizontalListBoxStyle" TargetType="ListBox">
                        <Setter Property="ItemsPanel">
                            <Setter.Value>
                                <ItemsPanelTemplate>
                                    <StackPanel Orientation="Horizontal"
                            VerticalAlignment="Center"
                            HorizontalAlignment="Center"/>
                                </ItemsPanelTemplate>
                            </Setter.Value>
                        </Setter>
                        <Setter Property="ItemTemplate">
                            <Setter.Value>
                                <DataTemplate>
                                    <StackPanel Orientation="Horizontal">
                                        <TextBlock Padding="5,0,5,0"
                          Text="{Binding FirstName}" />
                                        <TextBlock Text="{Binding LastName}" />
                                    </StackPanel>
                                </DataTemplate>
                            </Setter.Value>
                        </Setter>
                    </Style>

                    <src:Customers x:Key="items"/>
                </Grid.Resources>
                <ListBox Height="25" Width="420" ItemsSource="{StaticResource items}" Style="{StaticResource horizontalListBoxStyle}"/>
            </Grid>
        </StackPanel>
        <TextBlock Margin="5" Text="ListBox with SelectionChanged event handler:" Width="270" HorizontalAlignment="Left" />
            <ListBox Width="150" Margin="0,5,0,5" SelectionChanged="PrintText" HorizontalAlignment="Left">
                <ListBoxItem Content="Item 1" />
                <ListBoxItem Content="Item 2" />
                <ListBoxItem Content="Item 3" />
                <ListBoxItem Content="Item 4" />
                <ListBoxItem Content="Item 5" />
            </ListBox>
            <TextBlock Name="textBlock1" />
     </StackPanel>
</UserControl>
Visual Basic
Imports System
Imports System.Windows
Imports System.Windows.Controls
Imports System.Windows.Documents
Imports System.Windows.Ink
Imports System.Windows.Input
Imports System.Windows.Media
Imports System.Windows.Media.Animation
Imports System.Windows.Shapes
Imports System.Collections.ObjectModel

Partial Public Class Page
    Inherits UserControl
    Public Sub New()
        ' Required to initialize variables 
        InitializeComponent()
    End Sub

    Private Sub PrintText(ByVal sender As Object, ByVal args As SelectionChangedEventArgs)
        Dim lbi As ListBoxItem = TryCast(TryCast(sender, ListBox).SelectedItem, ListBoxItem)
        textBlock1.Text = " You selected " + lbi.Content.ToString() + "."
    End Sub

End Class


Public Class Customer
    Private _firstName As String
    Private _lastName As String
    Private _address As String

    Public Property FirstName() As String
        Get
            Return _firstName
        End Get

        Set(ByVal value As String)
            _firstName = value
        End Set
    End Property

    Public Property LastName() As String
        Get
            Return _lastName
        End Get

        Set(ByVal value As String)
            _lastName = value
        End Set
    End Property

    Public Property Address() As String
        Get
            Return _address
        End Get

        Set(ByVal value As String)
            _address = value
        End Set
    End Property

    Public Sub New(ByVal firstName As String, ByVal lastName As String, ByVal address As String)
        Me.FirstName = firstName
        Me.LastName = lastName
        Me.Address = address
    End Sub

End Class

Public Class Customers
    Inherits ObservableCollection(Of Customer)

    Public Sub New()
        Add(New Customer("Michael", "Anderberg", "12 North Third Street, Apartment 45"))
        Add(New Customer("Chris", "Ashton", "34 West Fifth Street, Apartment 67"))
        Add(New Customer("Cassie", "Hicks", "56 East Seventh Street, Apartment 89"))
        Add(New Customer("Guido", "Pica", "78 South Ninth Street, Apartment 10"))
    End Sub

End Class

C#
using System;
using System.Windows;
using System.Windows.Controls;
using System.Windows.Documents;
using System.Windows.Ink;
using System.Windows.Input;
using System.Windows.Media;
using System.Windows.Media.Animation;
using System.Windows.Shapes;
using System.Collections.ObjectModel;

namespace ListBoxSnippetEx
{
    public partial class Page : UserControl
    {
        public Page()
        {
            // Required to initialize variables
            InitializeComponent();
        }

        void PrintText(object sender, SelectionChangedEventArgs args)
        {
            ListBoxItem lbi = ((sender as ListBox).SelectedItem as ListBoxItem);
            textBlock1.Text = "   You selected " + lbi.Content.ToString() + ".";
        }

    }

    public class Customer
    {
        public String FirstName { get; set; }
        public String LastName { get; set; }
        public String Address { get; set; }

        public Customer(String firstName, String lastName, String address)
        {
            this.FirstName = firstName;
            this.LastName = lastName;
            this.Address = address;
        }

    }

    public class Customers : ObservableCollection<Customer>
    {
        public Customers()
        {
            Add(new Customer("Michael", "Anderberg",
                    "12 North Third Street, Apartment 45"));
            Add(new Customer("Chris", "Ashton",
                    "34 West Fifth Street, Apartment 67"));
            Add(new Customer("Cassie", "Hicks",
                    "56 East Seventh Street, Apartment 89"));
            Add(new Customer("Guido", "Pica",
                    "78 South Ninth Street, Apartment 10"));
        }

    }
}
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Processing
© 2009 Microsoft Corporation. All rights reserved. Terms of Use | Trademarks | Privacy Statement | Site Feedback
Page view tracker