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.

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 = 1; i <= itemCount; 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 explict 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);

         listView.selectionType = SelectionType.Multiple;

         listView.itemsChosen += objects => Debug.Log(objects);
         listView.selectionChanged += objects => Debug.Log(objects);

         listView.style.flexGrow = 1.0f;

         rootVisualElement.Add(listView);
     }
 }

Properties

Constructors

Inherited Members