ListView

Description

A ListView is a vertically scrollable area that links to, and displays, a list of items.

A ListView is a ScrollView with additional logic to display a list of vertically-arranged VisualElements. Each VisualElement in the list is bound to a corresponding element in a data-source list. The data-source list can contain elements of any type.

The logic required to create VisualElements, and to bind them to or unbind them from the data source, varies depending on the intended result. For the ListView to function correctly, you must supply at least a value for itemsSource.

It's also recommended to supply the following properties for more complex items:
- makeItem
- bindItem
- unbindItem
- destroyItem
- fixedItemHeight when using CollectionVirtualizationMethod.FixedHeight


The ListView creates multiple VisualElement objects for the visible items. As the user scrolls, the ListView recycles these objects and re-binds them to new data items.

To set the height of a single item in pixels, set the item-height property in UXML or the ListView.itemHeight property in C# to the desired value.

To display a border around the scrollable area, set the show-border property in UXML or the ListView.showBorder property in C# to true.

By default, the user can select one element in the list at a time. To change the default selection use the selection-type property in UXML or theListView.selectionType property in C#. To allow the user to select more than one element simultaneously, set the property to Selection.Multiple. To prevent the user from selecting items, set the property to Selection.None.

By default, all rows in the ListView have same background color. To make the row background colors alternate, set the show-alternating-row-backgrounds property in UXML or the ListView.showAlternatingRowBackgrounds property in C# to AlternatingRowBackground.ContentOnly or AlternatingRowBackground.All. For details, see AlternatingRowBackground.

By default, the user can't reorder the list's elements. To allow the user to drag the elements to reorder them, set the reorderable property in UXML or the ListView.reorderable property in C# to true.

To make the first item in the ListView display the number of items in the list, set the show-bound-collection-size property in UXML or the ListView.showBoundCollectionSize to true. This is useful for debugging. By default, the ListView's scroller element only scrolls vertically.

To enable horizontal scrolling when the displayed element is wider than the visible area, set the horizontal-scrolling-enabled property in UXML or the ListView.horizontalScrollingEnabled to true.

For more information, refer to ListView.

For the difference between IDs and indices, refer to BaseVerticalCollectionView.

The following example creates an editor window with a list view of a thousand items.

using System;
using System.Collections.Generic;
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;

public class ListViewExampleWindow : EditorWindow
{
    [MenuItem("Window/ListViewExampleWindow")]
    public static void OpenDemoManual()
    {
        GetWindow<ListViewExampleWindow>().Show();
    }

    public void OnEnable()
    {
        // Create a list of data. In this case, numbers from 1 to 1000.
        const int itemCount = 1000;
        var items = new List<string>(itemCount);
        for (int i = 0; i <= itemCount - 1; i++)
            items.Add(i.ToString());

        // The "makeItem" function is called when the
        // ListView needs more items to render.
        Func<VisualElement> makeItem = () => new Label();

        // As the user scrolls through the list, the ListView object
        // recycles elements created by the "makeItem" function,
        // and invoke the "bindItem" callback to associate
        // the element with the matching data item (specified as an index in the list).
        Action<VisualElement, int> bindItem = (e, i) => (e as Label).text = items[i];

        // Provide the list view with an explicit height for every row
        // so it can calculate how many items to actually display
        const int itemHeight = 16;

        var listView = new ListView(items, itemHeight, makeItem, bindItem)
        {
            // Enables multiple selection using shift or ctrl/cmd keys.
            selectionType = SelectionType.Multiple
        };

        // Set up list view so that you can add or remove items dynamically.
        listView.showAddRemoveFooter = true;

        // Implement functionality on the list view to add or remove items.
        // Note: The "onAdd" and "onRemove" callbacks are optional and you should only use them to override the default logic.
        listView.onAdd = view =>
        {
            var itemsSourceCount = view.itemsSource.Count;
            view.itemsSource.Add(itemsSourceCount.ToString());
            view.RefreshItems();
            view.ScrollToItem(itemsSourceCount);
        };
        listView.onRemove = view =>
        {
            var itemsSourceCount = view.itemsSource.Count;
            view.itemsSource.RemoveAt(itemsSourceCount - 1);
            view.RefreshItems();
            view.ScrollToItem(itemsSourceCount - 2);
        };

        // Single click triggers "selectionChanged" with the selected items. (f.k.a. "onSelectionChange")
        // Use "selectedIndicesChanged" to get the indices of the selected items instead. (f.k.a. "onSelectedIndicesChange")
        listView.selectionChanged += objects => Debug.Log($"Selected: {string.Join(", ", objects)}");

        // Double-click triggers "itemsChosen" with the selected items. (f.k.a. "onItemsChosen")
        listView.itemsChosen += objects => Debug.Log($"Double-clicked: {string.Join(", ", objects)}");

        listView.style.flexGrow = 1.0f;

        rootVisualElement.Add(listView);

        // Allow to add items, but only when there is no override, by using a Toggle.
        listView.allowAdd = true;
        var toggle = new Toggle("Override Add functionality")
        {
            value = listView.overridingAddButtonBehavior != null,
            style = {alignSelf = Align.Auto},
        };
        toggle.RegisterValueChangedCallback(evt => listView.overridingAddButtonBehavior = evt.newValue
            ? (view, button) =>
            {
                Debug.Log("You cannot add new items at this time");
            }
            : null
        );
        rootVisualElement.Add(toggle);
    }
}

Properties

Constructors

Inherited Members