Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

ListView

A ListView is a vertically scrollable area that links to, and displays, a list of items.
Read time 17 minutesLast updated 2 days ago

Definition

[Icon("UIToolkit/Icons/ListView.png")][UxmlElement(libraryPath = "Containers")]public class ListView : BaseListView, IEventHandler, IResolvedStyle, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, ICustomStyle, IBindable, ISerializationCallbackReceiver

Remarks

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:
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 _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 _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 the_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 _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 _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 _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 _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.

Examples

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);    }}

Constructors

Constructor

Description

ListView()Creates a ListView with all default properties. The _itemsSource must all be set for the ListView to function properly.
ListView(System.Collections.IList,System.Single,System.Func{UnityEngine.UIElements.VisualElement},System.Action{UnityEngine.UIElements.VisualElement,System.Int32})Constructs a ListView, with all important properties provided.

Properties

Property

Description

bindItemCallback for binding a data item to the visual element.
destroyItemCallback invoked when a VisualElement created via _makeItem is no longer needed and will be destroyed.
itemTemplateA UXML template that constructs each recycled and rebound element within the list. This template is designed to replace the _makeItem definition.
makeItemCallback for constructing the VisualElement that is the template for each recycled and re-bound element in the list.
unbindItemCallback for unbinding a data item from the VisualElement.

Inheritance

Inherited Members