Skip to content

Game.UI.Widgets.IListWidget

Assembly:
Game

Namespace:
Game.UI.Widgets

Type:
interface

Base:
IWidget, IJsonWritable

Summary:
Represents a UI list widget used by the game's UI system to manage a dynamic collection of child elements. Provides methods to add, insert, duplicate, move and remove elements, and to clear the list. Implementations are expected to keep the visual representation and any data bindings in sync and to support JSON serialization via IJsonWritable for saving/loading widget state.

Fields

  • None
    This interface does not declare any fields. Implementations may declare private fields to store elements or state.

Properties

  • None
    No properties are declared directly on IListWidget. See IWidget for common widget properties (visibility, enabled state, etc.) and IJsonWritable for serialization-related members.

Constructors

  • None
    Interfaces do not define constructors. Concrete implementations will provide construction behavior.

Methods

  • int AddElement()
    Adds a new element to the end of the list and returns the index of the newly added element. Implementations should initialize any default element data, update bindings, and refresh the UI so the item is visible if appropriate. May throw an exception if the widget is not in a valid state to add elements.

  • void InsertElement(int index)
    Inserts a new element at the specified index. The element previously at that index (and subsequent elements) should be shifted forward. Index is zero-based; valid values are typically 0..Count (inserting at Count appends). Implementations should validate the index and update bindings and UI.

  • int DuplicateElement(int index)
    Creates a duplicate/copy of the element at the specified index, appends or inserts the duplicate according to the implementation (commonly inserted immediately after the original), and returns the index of the duplicated element. Implementations should perform a deep or appropriate copy of the element data and refresh UI/bindings. Will typically throw or ignore if index is invalid.

  • void MoveElement(int fromIndex, int toIndex)
    Moves an element from one index to another, reordering the list. Both indices are zero-based. Implementations must update internal storage, bindings and the visible order. Behavior for out-of-range indices should be defined by the implementation (commonly throws ArgumentOutOfRangeException).

  • void DeleteElement(int index)
    Removes the element at the given index. Implementations should update internal state, release any resources associated with the element if necessary, update bindings, and refresh the UI. Index should be validated.

  • void Clear()
    Removes all elements from the list. Implementations should reset internal collections and update bindings/UI, and ensure that any resources held by elements are released.

Usage Example

// Assume 'list' is obtained from your UI creation code or a widget tree and implements IListWidget.
IListWidget list = GetWidget<IListWidget>("MyList");

// Add a new element and receive its index
int newIndex = list.AddElement();

// Insert an element at the start
list.InsertElement(0);

// Duplicate an element (returns the index of the duplicate)
int dupIndex = list.DuplicateElement(newIndex);

// Move the duplicated element to the top
list.MoveElement(dupIndex, 0);

// Delete the first element
list.DeleteElement(0);

// Clear all elements
list.Clear();

Notes: - Index parameters are zero-based. - Behavior for invalid indices (negative or >= count) depends on the concrete implementation; callers should validate indices or handle exceptions. - Because IListWidget inherits IJsonWritable, implementations typically support writing their state to JSON for saving mod or UI configuration. Ensure that changes to list contents are correctly reflected in serialization.