Skip to content

Latest commit

 

History

History
135 lines (92 loc) · 12.3 KB

listview.md

File metadata and controls

135 lines (92 loc) · 12.3 KB
Raw
-api-id -api-type
T:Windows.UI.Xaml.Controls.ListView
winrt class

Windows.UI.Xaml.Controls.ListView

-description

Represents a control that displays data items in a vertical stack.

-xaml-syntax

<ListView .../>
-or-
<ListView ...>
  oneOrMoreItems
</ListView>

-remarks

Tip

For more info, design guidance, and code examples, see List view and grid view.

Use a ListView to display a collection of items stacked vertically or horizontally. To display a collection in rows and columns, use a GridView.

List view control

ListView is an ItemsControl, so it can contain a collection of items of any type. To populate the view, add items to the Items collection, or set the ItemsSource property to a data source.

By default, a data item is displayed in the ListView as the string representation of the data object it's bound to. To specify exactly how items in the ListView are displayed, you create a DataTemplate to define the layout of controls used to display an individual item. The controls in the layout can be bound to properties of a data object, or have content defined inline. You assign the DataTemplate to the ItemTemplate property of the ListView. For common templates you can use in your app, see Item templates for ListView.

Note

If you populate the ListView by setting the ItemsSource property, the ItemTemplate is applied to every item. If you populate the Items collection directly, the ItemTemplate is applied only if the item is not a ListViewItem. See Examples for more info.

If you use the ListView to display large sets of data, see Optimize ListView and GridView for tips to maintain a smooth and responsive user experience.

Windows 10, version 1709 (SDK 16299) - Behavior change
By default, instead of performing selection, an active pen now scrolls/pans a list in UWP apps (like touch, touchpad, and passive pen). If your app depends on the previous behavior, you can override pen scrolling and revert to the previous behavior. See [ScrollViewer](scrollviewer.md) for details.

By default, a user can select a single item in a ListView. You can set the SelectionMode property to a ListViewSelectionMode enumeration value to allow multi-selection or to disable selection. You can also change the ListView interaction mode to make items respond to a user click like a button instead of being selected.

This table shows the ways a user can interact with a ListView, and how you can respond to the interaction.

To enable this interaction: Use these settings: Handle this event: Use this property to get the selected item:
No interaction SelectionMode = None, IsItemClickEnabled = False N/A N/A
Single selection SelectionMode = Single, IsItemClickEnabled = False SelectionChanged SelectedItem, SelectedIndex
Contiguous multi-selection SelectionMode = Multiple, IsItemClickEnabled = False SelectionChanged SelectedItems
Non-contiguous multi-selection SelectionMode = Extended, IsItemClickEnabled = False SelectionChanged SelectedItems
Click SelectionMode = None, IsItemClickEnabled = True ItemClick N/A

Note

The PointerWheelChanged event does not bubble up from a ListView. This means that a control that has a ListView inside of it does not receive mouse wheel change messages if the pointer is over the ListView. For example, if you put a ListView inside of a ScrollViewer, you can't scroll the ScrollViewer with the mouse wheel when the pointer is over the ListView.

ListView supports data virtualization to improve performance with large data sets. Random access virtualization is supported when the data source implements the appropriate interfaces, which vary depending on the programming language:

Windows 8 In Windows 8, when the data item in a selected ListViewItem is replaced, the SelectedIndex value is not cleared. In Windows 8.1 or later, the SelectedIndex value is cleared.

ListView implements the ISemanticZoomInformation interface, so it can be used as a view in a SemanticZoom control. When it's used in a SemanticZoom control, always set the ScrollViewer.IsVerticalScrollChainingEnabled attached property to false on the ScrollViewer that's in the ListView's control template, like this: <ListView ScrollViewer.IsVerticalScrollChainingEnabled="False">. These members have an effect only when the ListView is hosted in a SemanticZoom control: IsActiveView, IsZoomedInView, SemanticZoomOwner, CompleteViewChange, CompleteViewChangeFrom, CompleteViewChangeTo, InitializeViewChange, MakeVisible, StartViewChangeFrom, StartViewChangeTo.

If you need to handle pointer events for a UIElement in a scrollable view (such as a ScrollViewer), you must explicitly disable support for manipulation events on the element in the view by calling UIElement.CancelDirectmanipulation(). To re-enable manipulation events in the view, call UIElement.TryStartDirectManipulation().

Selection behavior and CollectionViewSource

List controls that derive from Selector have a default selection behavior that depends on what the items source is (the type that's used for ItemsSource). If the items source is a CollectionViewSource instance, then the behavior in the selection control is that the selection will default to the current item. When the list is first displayed, the selection defaults to the first item as current item. If you don't want the first item to be selected in this case, set IsSynchronizedWithCurrentItem to false in the ListView.

Visual updates in WinUI 2.6

In WinUI 2.6, new APIs and styles were added to update the visuals and design of ListView. These updated visuals include rounded corners, a selection indicator, and more.

If you'd like to use these new styles, first ensure that you're using WinUI 2.6 in your app. To get set up with WinUI 2, see Getting started with the Windows UI 2.x Library.

You can always modify the look of a ListView by specifying Xaml resources in your app. A new resource that is available in WinUI 2.6 is ListViewItemCornerRadius, which controls the level of rounding on ListViewItem corners. By default, this theme resource is set to 4px.

-examples

Tip

For more info, design guidance, and code examples, see List View.

[!div class="nextstepaction"] Open the WinUI 2 Gallery app and see ListView in action

The WinUI 2 Gallery app includes interactive examples of most WinUI 2 controls, features, and functionality. Get the app from the Microsoft Store or get the source code on GitHub.

In this example, the ItemTemplate of a ListView is defined inline. Because the ItemsSource is set, the ItemTemplate is applied to every item.

[!code-xamlListViewItemTemplate]

<ListView>
    <ListView.ItemTemplate>
        <DataTemplate>
            <Grid>
                <Border Background="LightGray" Height="200" Width="200">
                    <TextBlock Text="{Binding}" 
                               FontSize="48" Foreground="Green"/>
                </Border>
            </Grid>
        </DataTemplate>
    </ListView.ItemTemplate>
    <ListView.Items>
        <x:String>One</x:String>
        <ListViewItem>Two</ListViewItem>
    </ListView.Items>
</ListView>

In the following example, the corners of items in every ListView throughout the app are rounded to 5px.

<Application.Resources>
    <CornerRadius x:Key="ListViewItemCornerRadius">5</CornerRadius>
</Application.Resources>

-see-also

Lists overview, ListViewBase, Item templates for ListView, Data binding overview, ListView and GridView sample (Windows 10), Navigation menu (XAML) sample (Windows 10)