Listview

Namespace: Box.Entities.Container

Description

A scrollable list control that displays up to a fixed number of items (ListviewItem), handles selection and scrolling logic, and optionally defers selection notifications. The control sizes itself based on average item dimensions and maximum visible count, and emits EngineSignals.ListviewSelected when the selection changes.

Constructor

public Listview(int maxItems, params ListviewItem[] children);

Sets the maximum number of visible items, initializes the internal item list, and configures the control’s size based on average item width and height.

Properties

Property	Description
bool UseDiffered	When true, selection notifications (ListviewSelected) are emitted immediately; when false, they are deferred via EmitDelayed.
int SelectedIndex	Index of the currently selected item, combining the visible index and scroll offset.
ListviewItem SelectedItem	Currently selected item instance, or null if no items exist.
bool AtTop	True if the view is scrolled to the very top.
bool AtBottom	True if the view is scrolled to the very bottom given total items and max visible count.
int ScrollIndex	Current scroll offset in item indices (private setter).
float InputTimeoutDelay	Delay in seconds between navigation inputs to prevent rapid changes.

Methods

Method Signature	Description	Returns
T SelectedItemAs<T>() where T : ListviewItem	Returns the currently selected item cast to type T, or default if none selected.	T
void PreviousItem()	Moves selection up one slot or scrolls up when at the top; emits navigation sound FX if applicable.	void
void NextItem()	Moves selection down one slot or scrolls down when at the bottom; emits navigation sound FX if applicable.	void
protected override void OnEnter()	Populates initial items into the view, connects EntityAdded/EntityRemoved signals, and marks the view dirty.	void
protected override void Update()	Decrements input timeout, refreshes selection and scrolling when dirty, invokes base.Update() to render items.	void
new void AddChild(Entity entity)	Adds a single item entity to the list view and marks it dirty for layout and selection updates.	void
new void AddChild(params Entity[] entities)	Adds multiple item entities, resets selection state, and marks dirty.	void
new T AddChild<T>(params Entity[] entities) where T : Listview	Adds items and returns this instance for fluent chaining.	T
new bool RemoveChild(Entity entity)	Removes an item, starts a deletion routine to wait for removal, and returns true if removed.	bool
new bool RemoveChild(params Entity[] entities)	Removes multiple items, schedules deletion routines, and returns true if all were removed.	bool
new void ClearChildren()	Clears all items from the view, resets selection indices, and marks dirty.	void

Examples

// Initialize a list view with up to 5 items and some initial listview items
var list = new Listview(5, item1, item2, item3);

// Navigate with input
if (input.IsKeyPressed(Keys.Down))
    list.NextItem();
if (input.IsKeyPressed(Keys.Up))
    list.PreviousItem();

// Handle selection changes
list.Connect(EngineSignals.ListviewSelected, handle =>
{
    var selected = handle.Get<ListviewItem>(1);
    Console.WriteLine($"Selected: {selected?.Text}");
});

// Add to the main screen
mainScreen.AddEntity(list);