Luna UI Documentation

GridViewBase<TItem> is the abstract base for paginated, filterable grid views. It owns the grid layout, slot lifecycle, filter application, and selection state. Subclass it to bind your item data to slot UXML; or pick one of the two ready-made subclasses below: GridViewPagination<TItem> for paginated grids with a button strip, GridViewList<TItem> for virtualized scrolling backed by a Unity ListView.

Examples

InventoryView

Inventory Ingredients

Heroes

GridView Hero

GridView is a large class with lots of properties so it can be complex, but each property is simple on its own.

API

Constructor

csharp

public GridViewBase(
    List<TItem> itemList,
    VisualTreeAsset itemSlotTemplate,
    GameObject parent,
    VisualElement parentElement,
    VisualElement slotContainer,
    TooltipController tooltipController = null,
    bool startVisible = true,
    VisualElement focusElement = null,
    float fadeDuration = 0.5f,
    EasingMode easingMode = EasingMode.EaseOutCirc,
    bool disableOtherViewsOnFadeIn = false,
    bool debug = false
)

Parameter	Type	Default	Description
itemList	List<TItem>	—	Data source, list of items to display
itemSlotTemplate	VisualTreeAsset	—	Template for each grid item slot
parent	GameObject	—	Host GameObject — the view registers itself on its `UIViewReference`
parentElement	VisualElement	—	Root VisualElement the view shows/fades
slotContainer	VisualElement	—	Container the grid lines/slots are built into
tooltipController	TooltipController	`null`	Optional tooltip controller, closed on page/filter changes
startVisible	bool	`true`	Initial visibility applied in the constructor
focusElement	VisualElement	`null`	Element given keyboard/gamepad focus on fade-in
fadeDuration	float	`0.5f`	Fade in/out duration in seconds
easingMode	EasingMode	`EaseOutCirc`	Easing applied to the fade
disableOtherViewsOnFadeIn	bool	`false`	Blocks input on all other registered pages while this view is visible
debug	bool	`false`	Verbose lifecycle logging

The last seven parameters are shared verbatim by GridViewPagination and GridViewList (see below), so one mental model covers all three. The final five (focusElement through debug) are the standard UIView constructor tail; tooltipController and startVisible are grid-level extras (startVisible is applied via ApplyStartVisibility — UIView's constructor no longer takes it).

Properties

Property	Type	Description
SlotContainer	VisualElement	The container holding item slots
SlotPerLine	int	Current number of slots per grid line
ItemSlots	List<VisualElement>	List of all created item slot elements
SelectedItems	HashSet<TItem>	Currently selected items

Methods

CreateSlots

Creates the grid slot elements. Must be implemented by derived classes.

csharp

public abstract void CreateSlots();

Refresh

Refilters and refreshes all items in the grid.

csharp

public void Refresh()

SetItemList

Updates the data source and refreshes the grid.

csharp

public void SetItemList(List<TItem> itemList)

Selection Methods

csharp

public abstract void Select(int slotIndex);
public abstract void Deselect(int slotIndex);
public void DeselectAll();

Filter Methods

SetFilters

Sets the filter functions for the grid.

csharp

public void SetFilters(List<Func<List<TItem>, int, List<TItem>>> filters)

SetFilter

Applies a filter value at the specified filter index.

csharp

public void SetFilter(int filterIndex, int filter)

ClearFilter

Clears the filter at the specified index.

csharp

public void ClearFilter(int filterIndex)

GetFilter

Gets the current filter value at the specified index.

csharp

public int GetFilter(int index)

GetFilteredList

Returns the filtered list based on current filters.

csharp

public virtual List<TItem> GetFilteredList(List<int> filters)

Filter Button Methods

SetFilterButtons

Sets up filter toggle buttons.

csharp

public void SetFilterButtons(List<List<Button>> filterButtons)

SetFilterClearButtons

Sets up filter clear buttons.

csharp

public void SetFilterClearButtons(List<List<Button>> filterClearButtons)

SetEnabledFilterButtons

Enables or disables filter buttons at an index.

csharp

public void SetEnabledFilterButtons(int filterIndex, bool enabled)

UpdateFilterButtons

Updates filter button visual states.

csharp

public void UpdateFilterButtons(int filterIndex)

Configuration Methods

SetHideEmpty

When true, empty slots are hidden instead of shown.

csharp

public void SetHideEmpty(bool hideEmpty)

SetSelectedFilterColor

Sets the color class applied to selected filter buttons (a Luna color-class name like "sky").

csharp

public void SetSelectedFilterColor(string color)

SetSelectedFilterClass

Sets the USS class applied to selected filter buttons.

csharp

public void SetSelectedFilterClass(string selectedFilterClass)

SetFilterClass

Sets the USS class applied to all filter buttons.

csharp

public void SetFilterClass(string filterClass)

Input Methods

SetInputPrompt

Sets up input prompts for tab navigation (prev/next filters).

csharp

public void SetInputPrompt(InputPrompt filterItemPrevious, InputPrompt filterItemNext)

PreviousTab / NextTab

Navigate between filter tabs.

csharp

public void PreviousTab()
public void PreviousTab(int filterIndex)
public void NextTab()
public void NextTab(int filterIndex)

RegisterInput / UnregisterInput

Manually register or unregister input handlers.

csharp

public void RegisterInput()
public void UnregisterInput()

Dynamic Layout

RegisterDynamicItemPerLineUpdate

Registers a callback to update items per line when container size changes.

csharp

public void RegisterDynamicItemPerLineUpdate()
public void UnregisterDynamicItemPerLineUpdate()

Abstract Methods to Implement

When extending GridViewBase, implement these methods:

csharp

// Create slot visual elements
public abstract void CreateSlots();

// Refresh items in slots
protected abstract void RefreshItems();

// Filter list based on current filters
protected abstract void FilterList();

// Handle filter changes
protected abstract void OnFilterChange(int filterIndex);

// Handle dynamic layout changes
protected abstract void DynamicItemPerLineUpdate(GeometryChangedEvent evt);

// Called when creating each slot
protected abstract void OnItemCreate(VisualElement slot);

// Unbind item from slot
protected abstract void UnbindItem(VisualElement slot);

// Bind item to slot
protected abstract void BindItem(VisualElement slot, TItem item, int slotIndex, bool selected);

// Selection handling
public abstract void Select(int slotIndex);
public abstract void Deselect(int slotIndex);

Example Implementation

csharp

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UIElements;
using CupkekGames.Luna;

public class InventoryGridView : GridViewBase<InventoryItem>
{
    private List<InventoryItem> _filteredList;
    
    public InventoryGridView(
        List<InventoryItem> items,
        VisualTreeAsset template,
        GameObject parent,
        VisualElement parentElement,
        VisualElement container
    ) : base(items, template, parent, parentElement, container)
    {
        _slotPerLine = 4;
        _itemWidth = 80;
    }
    
    public override void CreateSlots()
    {
        _slotContainer.Clear();
        ItemSlots.Clear();
        
        int lineCount = Mathf.CeilToInt((float)_itemList.Count / _slotPerLine);
        for (int i = 0; i < lineCount; i++)
        {
            VisualElement line = MakeLine();
            _slotContainer.Add(line);
        }
        
        RefreshItems();
    }
    
    protected override void FilterList()
    {
        _filteredList = GetFilteredList(_currentFilters);
    }
    
    protected override void RefreshItems()
    {
        for (int i = 0; i < ItemSlots.Count; i++)
        {
            VisualElement slot = ItemSlots[i];
            
            if (i < _filteredList.Count)
            {
                InventoryItem item = _filteredList[i];
                bool selected = _selectedItems.Contains(item);
                BindItem(slot, item, i, selected);
                slot.style.visibility = Visibility.Visible;
            }
            else
            {
                UnbindItem(slot);
                slot.style.visibility = _hideEmpty ? Visibility.Hidden : Visibility.Visible;
            }
        }
    }
    
    protected override void OnItemCreate(VisualElement slot)
    {
        // Initial slot setup
        slot.AddToClassList("inventory-slot");
    }
    
    protected override void BindItem(VisualElement slot, InventoryItem item, int index, bool selected)
    {
        var icon = slot.Q<VisualElement>("Icon");
        icon.style.backgroundImage = new StyleBackground(item.Icon);
        
        var label = slot.Q<Label>("Name");
        label.text = item.Name;
        
        if (selected)
        {
            slot.AddToClassList("selected");
        }
        else
        {
            slot.RemoveFromClassList("selected");
        }
    }
    
    protected override void UnbindItem(VisualElement slot)
    {
        var icon = slot.Q<VisualElement>("Icon");
        icon.style.backgroundImage = null;
        
        var label = slot.Q<Label>("Name");
        label.text = "";
        
        slot.RemoveFromClassList("selected");
    }
    
    protected override void OnFilterChange(int filterIndex)
    {
        // Handle filter change - e.g., update category header
    }
    
    protected override void DynamicItemPerLineUpdate(GeometryChangedEvent evt)
    {
        float width = _slotContainer.resolvedStyle.width;
        int newSlotPerLine = Mathf.Max(1, Mathf.FloorToInt(width / _itemWidth));
        
        if (newSlotPerLine != _slotPerLine)
        {
            _slotPerLine = newSlotPerLine;
            CreateSlots();
        }
    }
    
    public override void Select(int slotIndex)
    {
        if (slotIndex < _filteredList.Count)
        {
            _selectedItems.Add(_filteredList[slotIndex]);
            RefreshItems();
        }
    }
    
    public override void Deselect(int slotIndex)
    {
        if (slotIndex < _filteredList.Count)
        {
            _selectedItems.Remove(_filteredList[slotIndex]);
            RefreshItems();
        }
    }
}

GridViewPagination

GridViewPagination<TItem> extends GridViewBase<TItem> and adds pagination support. Items are split across pages and rendered into a fixed number of grid lines.

Constructor

csharp

public GridViewPagination(
    List<TItem> itemList,
    VisualTreeAsset itemSlotTemplate,
    GameObject parent,
    VisualElement parentElement,
    VisualElement slotContainer,
    TooltipController tooltipController = null,
    bool startVisible = true,
    VisualElement focusElement = null,
    float fadeDuration = 0.5f,
    EasingMode easingMode = EasingMode.EaseOutCirc,
    bool disableOtherViewsOnFadeIn = false,
    bool debug = false
)

Properties

Property	Type	Description
Pagination	PaginationController<TItem>	The pagination controller managing page state and UI

Public Methods

SetPagination

Sets the number of lines and items per line, updating items per page.

csharp

public void SetPagination(int lineCount, int perLine)

Parameter	Type	Description
lineCount	int	Number of grid lines (rows) to display
perLine	int	Number of items per line

SetDynamicItemPerLine

Calculates items per line based on container width and item width.

csharp

public void SetDynamicItemPerLine(int lineCount, int itemWidth)

Parameter	Type	Description
lineCount	int	Number of grid lines (rows) to display
itemWidth	int	Width of each item in pixels

SetPaginationUI

Configures the pagination button UI.

csharp

public void SetPaginationUI(VisualElement parent, string normal, string active, int maxButtonAmount)

Parameter	Type	Description
parent	VisualElement	Container element for pagination buttons
normal	string	Color-class name for non-active page buttons
active	string	Color-class name for the active page button
maxButtonAmount	int	Maximum number of page buttons to display

GridViewList

GridViewList<TItem> extends GridViewBase<TItem> and uses Unity's ListView for virtualized scrolling. Only visible items are rendered, making it efficient for large data sets.

Constructor

csharp

public GridViewList(
    List<TItem> itemList,
    VisualTreeAsset itemSlotTemplate,
    GameObject parent,
    VisualElement parentElement,
    ListView slotContainer,
    TooltipController tooltipController = null,
    bool startVisible = true,
    VisualElement focusElement = null,
    float fadeDuration = 0.5f,
    EasingMode easingMode = EasingMode.EaseOutCirc,
    bool disableOtherViewsOnFadeIn = false,
    bool debug = false
)

Note: slotContainer is a ListView instead of a plain VisualElement.

Properties

Property	Type	Description
ListView	ListView	The underlying ListView element

Public Methods

SetSlotPerLine

Manually sets the number of items per line.

csharp

public void SetSlotPerLine(int perLine)

SetDynamicItemPerLine

Calculates items per line based on container width and item width.

csharp

public void SetDynamicItemPerLine(int itemWidth)

Parameter	Type	Description
itemWidth	int	Width of each item in pixels

Pagination - For paginated grids
Tooltip - Item tooltips

GridView

Examples

API

Constructor

Properties

Methods

CreateSlots

Refresh

SetItemList

Selection Methods

Filter Methods

SetFilters

SetFilter

ClearFilter

GetFilter

GetFilteredList

Filter Button Methods

SetFilterButtons

SetFilterClearButtons

SetEnabledFilterButtons

UpdateFilterButtons

Configuration Methods

SetHideEmpty

SetSelectedFilterColor

SetSelectedFilterClass

SetFilterClass

Input Methods

SetInputPrompt

PreviousTab / NextTab

RegisterInput / UnregisterInput

Dynamic Layout

RegisterDynamicItemPerLineUpdate

Abstract Methods to Implement

Example Implementation

GridViewPagination

Constructor

Properties

Public Methods

SetPagination

SetDynamicItemPerLine

SetPaginationUI

GridViewList

Constructor

Properties

Public Methods

SetSlotPerLine

SetDynamicItemPerLine

Related