ListBox Class (System.Windows.Controls)

MSDN Library
Web Development
Silverlight
Silverlight 3
.NET Framework Class Library for Silverlight
System.Windows.Controls Namespace

ListBox Class

ListBox Members
ListBox Constructor
ListBox Fields
ListBox Methods
ListBox Properties
ListBox Events

ListBox Class
This page is specific to:Microsoft Version:3.0 3.5Silverlight 34.0

.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)

Syntax

C++

JScript

Copy to Clipboard Print

'Usage

Dim instance As ListBox

'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

XAML Object Element Usage

<ListBox .../>

Remarks

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

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.

Note:
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.

Examples

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>

C++

JScript

Copy to Clipboard Print

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

Inheritance Hierarchy

System..::.Object
  System.Windows..::.DependencyObject
    System.Windows..::.UIElement
      System.Windows..::.FrameworkElement
        System.Windows.Controls..::.Control
          System.Windows.Controls..::.ItemsControl
            System.Windows.Controls.Primitives..::.Selector
              System.Windows.Controls..::.ListBox

Thread Safety

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

Platforms

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

Reference

ListBox Members

System.Windows.Controls Namespace

Other Resources

How to: Display Data in a ListBox

Controls by Function

Getting Started with Controls

ListBox Styles and Templates