ListBox ListBox ListBox Class

Presents a list of items the user can select from.

Syntax

Declaration

public class ListBoxpublic class ListBoxPublic Class ListBox
<ListBox .../>
-or-
<ListBox ...>
  oneOrMoreItems
</ListBox>

Inheritance Hierarchy

Inherited Members

Inherited properties

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,
Tag
Tag
Tag
, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited events

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Inherited methods

, , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , ,

Remarks

ListBox lets users select from a pre-defined list of options presented like a text control. Use a ListBox when you want the options to be visible all the time or when users can select more than one option at a time. ListBox controls are always open, so several items can be displayed without user interaction.

List box control

Note

ListBox is useful when you are upgrading a Universal Windows 8 app that uses ListBox, and need to minimize changes. For new apps in Windows 10, we recommend using the ListView control instead.

Using a ListBox

Use a ListBox control to present a list of items that a user can select from. More than one item in a ListBox control is visible at a time. You specify whether the ListBox control allows multiple selections by setting the SelectionMode property. You can get or set the selected items for the list box by using the SelectedItems property.

Populating a ListBox

You populate the ListBox control by adding UIElement items directly to the Items collection, or by binding the ItemsSource property to a data source. ItemsSource items from data will initially clear the Items collection when the binding is evaluated, so don't set both properties.

ListBox has a dedicated control for its items, ListBoxItem. But when you populate the Items collection, you can use elements or data, you don't typically use explicit ListBoxItem objects. What happens internally is that when the ListBox composes its visual tree from its templates, specifically when expanding the ItemTemplate, it creates a ListBoxItem wrapper for each of the objects it's including as items. At run time, the Items collection still contains the original items you declared. The created ListBoxItem wrappers are deeper in the visual tree, inside the items panel (see ItemsPanel ) as its children. You don't usually need direct access to a ListBoxItem object. But if you want to access the created ListBoxItem wrappers, you can use Microsoft UI Automation techniques, or use VisualTreeHelper APIs, to walk into the object tree representation and find them.

ListBox vs. ListView and GridView

ListBox has many similarities with ListView or GridView (they share the parent class ItemsControl ), but each control is oriented towards different scenarios. ListBox is best for general UI composition, particularly when the elements are always intended to be selectable, whereas ListView or GridView are best for data binding scenarios, particularly if virtualization or large data sets are involved. For more info on virtualization, see Using virtualization with a list or grid.

Examples

This example demonstrates how to add a collection of FontFamily objects directly to a ListBox control.

<ListBox>
    <TextBlock Text="Arial" FontFamily="Arial"/>
    <TextBlock Text="Courier New" FontFamily="Courier New"/> 
    <TextBlock Text="Times New Roman" FontFamily="Times New Roman"/>
</ListBox>

This example uses data binding to fill a ListBox control with a collection of FontFamily objects.


<ListBox x:Name="FontsList" Height="20" Width="150" 
         ItemsSource="{x:Bind fonts}" DisplayMemberPath="Source"/>

ObservableCollection<FontFamily> fonts = new ObservableCollection<FontFamily>();

public BlankPage()
{
    this.InitializeComponent();
    fonts.Add(new FontFamily("Arial"));
    fonts.Add(new FontFamily("Courier New"));
    fonts.Add(new FontFamily("Times New Roman"));
}

Dim fonts As New ObservableCollection(of FontFamily) 

Public Sub New()
    MyBase.New()
    InitializeComponent()    
    fonts.Add(New FontFamily("Arial"))
    fonts.Add(New FontFamily("Courier New"))
    fonts.Add(New FontFamily("Times New Roman"))
End Sub

Constructors summary

Initializes a new instance of the ListBox class.

Properties summary

Gets the list of currently selected items for the ListBox control.

Gets or sets the selection behavior for the ListBox control.

Identifies the SelectionMode dependency property.

Gets or sets a value that indicates whether item selection changes when keyboard focus changes.

Identifies the SingleSelectionFollowsFocus dependency property.

Methods summary

Causes the object to scroll into view.

Selects all the items in the ListBox control.

Constructors

  • ListBox()
    ListBox()
    ListBox()
    ListBox()

    Initializes a new instance of the ListBox class.

    public ListBox()public New()Public Sub New()public ListBox()

Properties

  • SelectedItems
    SelectedItems
    SelectedItems
    SelectedItems

    Gets the list of currently selected items for the ListBox control.

    public IVector<object> SelectedItems { get; }public IVector<object> SelectedItems { get; }Public ReadOnly Property SelectedItems As IVector<object>public IVector<object> SelectedItems { get; }

    Property Value

    • The list of currently selected items for the ListBox control.

    Remarks

    When SelectionMode is Multiple or Extended, use the SelectedItems property to get the items that are selected. When SelectionMode is Single, use the SelectedItem property to get the item that's selected.

  • SelectionMode
    SelectionMode
    SelectionMode
    SelectionMode

    Gets or sets the selection behavior for the ListBox control.

    public SelectionMode SelectionMode { get; set; }public SelectionMode SelectionMode { get; set; }Public ReadWrite Property SelectionMode As SelectionModepublic SelectionMode SelectionMode { get; set; }
    <ListBox SelectionMode="selectionModeValue"/>
    

    Property Value

    Remarks

    By default, a user can select a single item in a ListBox. You can set the SelectionMode property to a SelectionMode enumeration value to enable multi-selection. Here are the selection mode values.

    SelectionMode A user can select a single item using the space bar, mouse click, or touch tap. A user can deselect an item using a downward swipe gesture.

    While pressing Ctrl: a user can deselect the item by using the space bar, mouse click, or touch tap. Using the arrow keys, a user can move focus independently of selection.

    ListViewSelectionMode A user can select multiple items using the space bar, mouse click, or touch tap to toggle selection on the focused item. Using the arrow keys, a user can move focus independently of selection.
    ListViewSelectionMode With no modifier keys: the behavior is the same as ListViewSelectionMode selection.

    While pressing Ctrl: a user can select multiple items using the space bar, mouse click, or touch tap to toggle selection on the focused item. Using the arrow keys, a user can move focus independently of selection.

    While pressing Shift: a user can select multiple contiguous items by clicking or tapping the first item in the selection and then the last item in the selection. Using the arrow keys, a user can create a contiguous selection starting with the item selected when Shift is pressed.

    When SelectionMode is Single, use the SelectedItem property to get the item that's selected. When SelectionMode is Multiple or Extended, use the SelectedItems property to get the items that are selected.

  • SelectionModeProperty
    SelectionModeProperty
    SelectionModeProperty
    SelectionModeProperty

    Identifies the SelectionMode dependency property.

    public static DependencyProperty SelectionModeProperty { get; }public static DependencyProperty SelectionModeProperty { get; }Public Static ReadOnly Property SelectionModeProperty As DependencyPropertypublic static DependencyProperty SelectionModeProperty { get; }

    Property Value

  • SingleSelectionFollowsFocus
    SingleSelectionFollowsFocus
    SingleSelectionFollowsFocus
    SingleSelectionFollowsFocus

    Gets or sets a value that indicates whether item selection changes when keyboard focus changes.

    public bool SingleSelectionFollowsFocus { get; set; }public bool SingleSelectionFollowsFocus { get; set; }Public ReadWrite Property SingleSelectionFollowsFocus As boolpublic bool SingleSelectionFollowsFocus { get; set; }
    <ListBox SingleSelectionFollowsFocus="bool" />
    

    Property Value

    • bool
      bool
      bool

      true if item selection changes when keyboard focus changes; otherwise, false. The default is true.

    Remarks

    This property is ignored if the list box's SelectionMode property is not set to Single.

    By default, when a list box is configured for single selection, when the user moves keyboard focus to an item, the focused item is also selected. For example, if keyboard focus is moved from the first item to the second item, the SelectedIndex property is updated from 0 to 1.

    Set this property to false to let a user move focus without the item selection following. For example, if each selection change causes significant UI updates, you might prefer to let the user move focus to a non-adjacent item and then press enter to update selection.

    Version compatibility

    The SingleSelectionFollowsFocus property is not available prior to Windows 10, version 1607. If your app’s 'minimum platform version' setting in Microsoft Visual Studio is less than the 'introduced version' shown in the Requirements block later in this page, you must design and test your app to account for this. For more info, see Version adaptive code.

    To avoid exceptions when your app runs on previous versions of Windows 10, do not set this property in XAML or use it without performing a runtime check. This example shows how to use the ApiInformation class to check for the presence of this property before you set it.

    <ListBox x:Name="listBox1" Loaded="ListBox_Loaded"/>
    
    private void ListBox_Loaded(object sender, RoutedEventArgs e)
    {
        if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Controls.ListBox", "SingleSelectionFollowsFocus"))
        {
            listBox1.SingleSelectionFollowsFocus = false;
        }
    }
    
  • SingleSelectionFollowsFocusProperty
    SingleSelectionFollowsFocusProperty
    SingleSelectionFollowsFocusProperty
    SingleSelectionFollowsFocusProperty

    Identifies the SingleSelectionFollowsFocus dependency property.

    public static DependencyProperty SingleSelectionFollowsFocusProperty { get; }public static DependencyProperty SingleSelectionFollowsFocusProperty { get; }Public Static ReadOnly Property SingleSelectionFollowsFocusProperty As DependencyPropertypublic static DependencyProperty SingleSelectionFollowsFocusProperty { get; }

    Property Value

Methods

  • ScrollIntoView(Object)
    ScrollIntoView(Object)
    ScrollIntoView(Object)
    ScrollIntoView(Object)

    Causes the object to scroll into view.

    public void ScrollIntoView(Object item)public void ScrollIntoView(Object item)Public Function ScrollIntoView(item As Object) As voidpublic void ScrollIntoView(Object item)

    Parameters

    • item
      System.Object
      System.Object
      System.Object

      The object to scroll to.

    Remarks

    When the contents of the ItemsSource collection changes, particularly if many items are added to or removed from the collection, you might need to call UpdateLayout() prior to calling ScrollIntoView(Object) for the specified item to scroll into the viewport.

  • SelectAll()
    SelectAll()
    SelectAll()
    SelectAll()

    Selects all the items in the ListBox control.

    public void SelectAll()public void SelectAll()Public Function SelectAll() As voidpublic void SelectAll()

    Remarks

    Warning

    The SelectAll() method should only be called when the SelectionMode property is set to SelectionMode or SelectionMode. If SelectAll() is called when the SelectionMode is Single, an exception is thrown.

    Examples

    if (listBox->SelectionMode != SelectionMode::Single)
    {
        listBox->SelectAll();
    }
    
    if (listBox.SelectionMode != SelectionMode.Single)
    {
        listBox.SelectAll();
    }
    
    If listBox.SelectionMode <> SelectionMode.Single Then
        listBox.SelectAll()
    End If
    

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ComposableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.StaticAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.UI.Xaml.Controls.dll