List​Box Class

Definition

Contains a list of selectable items.

[System.Windows.Localizability(System.Windows.LocalizationCategory.ListBox)]
[System.Windows.StyleTypedProperty(Property="ItemContainerStyle", StyleTargetType=typeof(System.Windows.Controls.ListBoxItem))]
public class ListBox : System.Windows.Controls.Primitives.Selector
Inheritance
Derived
Attributes

Inherited Members

System.Object

System.Windows.Controls.Control

System.Windows.Controls.ItemsControl

System.Windows.Controls.Primitives.Selector

System.Windows.DependencyObject

System.Windows.FrameworkElement

System.Windows.Media.Visual

System.Windows.Threading.DispatcherObject

System.Windows.UIElement

Examples

The following example creates a ListBox and subscribes to the SelectionChanged event.

<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>
void PrintText(object sender, SelectionChangedEventArgs args)
{
    ListBoxItem lbi = ((sender as ListBox).SelectedItem as ListBoxItem);
    tb.Text = "   You selected " + lbi.Content.ToString() + ".";
}
Private 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

Remarks

ListBox is an ItemsControl, which means it can contain a collection of objects of any type (such as string, image, or panel). For more information, see the ItemsControl class.

More than one item in a ListBox is visible, unlike the ComboBox, which has only the selected item visible unless the IsDropDownOpen property is true. The SelectionMode property determines whether more than one item in the ListBox is selectable at a time.

The SelectionMode property determines how many items a user can select at one time. You can set the property to Single (the default), Multiple, or Extended. The following table described the behavior of these enumeration values.

Value Description
Single The user can select only one item at a time.
Multiple The user can select multiple items without holding down a modifier key.
Extended The user can select multiple consecutive items while holding down the SHIFT key or non-consecutive items by holding down the CTRL key and clicking the items.

ListBox controls are often used with data binding. For more information, see Data Binding Overview.

Displaying a large number of items may cause performance issues. See Optimizing Performance: Controls for more information.

Customizing the ListBox Control

To apply the same property settings to multiple ListBox controls, use the Style property. You can modify the default ControlTemplate to give the control a unique appearance. For more information about creating a ControlTemplate, see Customizing the Appearance of an Existing Control by Creating a ControlTemplate. To see the parts and states that are specific to the ListBox, see ListBox Styles and Templates.

Dependency properties for this control might be set by the control’s default style. If a property is set by a default style, the property might change from its default value when the control appears in the application. The default style is determined by which desktop theme is used when the application is running. For more information, see Default WPF Themes.

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 . You can find a list of visual properties in the "Changing the Visual Structure of a Control" section in Customizing the Appearance of an Existing Control by Creating a ControlTemplate.

Constructors

List​Box()

Initializes a new instance of the ListBox class.

Fields

Selected​Items​Property

Identifies the SelectedItems dependency property.

Selection​Mode​Property

Identifies the SelectionMode dependency property.

Properties

Anchor​Item

Gets or sets the item that is initially selected when SelectionMode is Extended.

Handles​Scrolling

Gets a value that indicates whether the ListBox supports scrolling.

Selected​Items

Gets the currently selected items.

Selection​Mode

Gets or sets the selection behavior for a ListBox.

Methods

Get​Container​For​Item​Override()

Creates or identifies the element used to display a specified item.

Is​Item​Its​Own​Container​Override(​Object)

Determines if the specified item is (or is eligible to be) its own ItemContainer.

On​Create​Automation​Peer()

Provides an appropriate ListBoxAutomationPeer implementation for this control, as part of the WPF automation infrastructure.

On​Is​Mouse​Captured​Changed(​Dependency​Property​Changed​Event​Args)

Called when the IsMouseCaptured property changes.

On​Key​Down(​Key​Event​Args)

Responds to the KeyDown event.

On​Mouse​Move(​Mouse​Event​Args)

Called when a ListBox reports a mouse move.

On​Selection​Changed(​Selection​Changed​Event​Args)

Responds to a list box selection change by raising a SelectionChanged event.

Prepare​Container​For​Item​Override(​Dependency​Object, ​Object)

Prepares the specified element to display the specified item.

Scroll​Into​View(​Object)

Causes the object to scroll into view.

Select​All()

Selects all the items in a ListBox.

Set​Selected​Items(​IEnumerable)

Sets a collection of selected items.

Unselect​All()

Clears all the selection in a ListBox.