Multi-column Views

LTS 2022.3

Multi-column Views

Creating multi-column views with UITK ->

Multi-column views enable the display of multiple columns in using tree or list view controls.

Implementation references

Scripting API and implementation references.

Create in UI Toolkit ↓

Create in IMGUI ↓

UI Toolkit

IMGUI

Overview

An IMGUI MultiColumn TreeView from the "Windows/Rendering/Light Explorer" window

Multi-column views enable the display of multiple columns in using tree or list view controls. They are instantiated differently in the UI Toolkit and IMGUI frameworks.

When to Use

Examples of a list of planets and toggles that indicate whether the planet is populated with list view and tree view.

Use a multi-column list view when displaying multiple columns in a flat list view.
Use a multi-column tree view when displaying multiple columns in a hierarchical tree view.

Tree view

For more information on tree view go to Components > Tree View ->

List view

For more information on list view go to Components > List View ->

Create in UI Toolkit

Multi-column views are not in the UI Builder library as of 2022.1.

To create these controls;
1. First add multi-column viewcontrols to UXML,
2. define the column data in C# and reference this object,
3. and customize using Column properties.
‍

UI Toolkit implementation references

Not in UI Builder library.

Multi-column views are not yet added to the UI Builder library. However you can add them as custom UXML objects and bind data in C#.

1. Add the control to UXML

To create a list or tree view with multiple columns, first create a MultiColumnListView or MultiColumnTreeView UI control, and define the number of columns and column titles in a UXML file.

Examples below have a column with a list of planets and toggles that indicate whether the planet is populated:

Multi-column list view UXML

An example of a multi-column list view in UXML showing a list of planets and toggles to indicate which planets are populated

Add the following code in a .uxml file:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
    <ui:MultiColumnListView fixed-item-height="20">
        <!-- Columns and Column aren't Visual Elements or controls. They are considered attributes of MultiColumnListView. -->
        <ui:Columns>
            <ui:Column name="name" title="Name" width="80" />
            <ui:Column name="populated" title="Populated?" width="80" />
        </ui:Columns>
    </ui:MultiColumnListView>
</ui:UXML>

Multi-column tree view UXML

An example of a multi-column tree view in UXML listing planets with toggles nested under two collapsable lists, one for inner planets and one for outer planets.

Add the following code in a .uxml file:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
    <ui:MultiColumnTreeView fixed-item-height="20">
        <!-- Columns and Column aren't Visual Elements or controls; they are considered attributes of MultiColumnListView. -->
        <ui:Columns>
            <ui:Column name="name" title="Name" width="120" />
            <ui:Column name="populated" title="Populated?" width="80" />
        </ui:Columns>
    </ui:MultiColumnTreeView>
</ui:UXML>

2. Bind data in C#

Define where to get data for each column in a C# script and reference the UXML file to this script.

Example of creating multi-column views

Visit the example page to see C# examples on populating data and initializing cells ->

3. Customize with properties

Column class properties are used to define how a user interacts with a column in a multi-column view, and how its data and the data of each cell in this column are represented.

Properties

Create in IMGUI

Multi-column views are the standard tree view control configured with MultiColumnHeader and MultiColumnHeaderState classes.
‍

IMGUI implementation references

Multi-column tree view example;

1. Create some columns using MultiColumnHeaderState and set the column properties.

var columnList = new List();

// Create 10 columns where the text of each column is its index (i)
for (var i = 0; i < 10; i++)
{
      columnList.Add(new MultiColumnHeaderState.Column
       {
           headerContent = i,
           headerTextAlignment = TextAlignment.Left,
           sortedAscending = true,
           sortingArrowAlignment = TextAlignment.Left,
           width = 100,
           minWidth = 30,
           autoResize = true
       })
}

2. Create a Column State object with the created columns


MultiColumnHeaderState columnState = new
MultiColumnHeaderState(columnList);

3. Create a MultiColumnHeader object with the state


MultiColumnHeader header = new MultiColumnHeader(columnState);

4. Create a TreeView with the MultiColumnHeader object.


TreeView treeView = new TreeView(..., header);

Multi-column list view example;

To create a list view follow the same steps above for the multi-column tree view but ensure all view items are located under the root to make it a listview (so that there are no hierarchical relationships).