ListBox<T> class

Namespace: Arlecchino.Widgets.Lists · Assembly: Arlecchino

A scrolling list of items, one per row. It keeps only the selected index, never a copy of the items, so replacing ListBox.Items between frames is a normal thing to do.

public sealed class ListBox<T> :
    IArlecchinoInteractiveWidget,
    IArlecchinoWidget,
    IArlecchinoFocusable

Implements IArlecchinoInteractiveWidget, IArlecchinoWidget, IArlecchinoFocusable

Constructors

Member	Summary
ListBox(ArlecchinoKeymap)	Creates the list.

Properties

Member	Summary
IsFocused	Whether the list has focus, which decides how strongly the selection is drawn.
ItemStyle	Colors an item. Ignored for the selected row, which has to stand out.
Items	What to show. Replacing this pulls the selection back into range on the next frame.
OnActivate	What confirming an item does. Returning a route navigates; without this the list simply reports the key as handled.
PaintRow	Draws a row itself, for a list whose rows are not one color. It is given one row to fill and told whether the cursor is on it, and ListBox.Render goes unread while it is set.
Render	Turns an item into its row of text. Longer text is truncated by column, not by character.
SelectedIndex	Index of the selected row.
SelectedItem	The selected item, or the type's default when the list is empty.

Methods

Member	Summary
Draw(SurfaceRegion)	Draws the rows around the selection and remembers where they landed, which is what lets clicks and wheel events be resolved afterward. The list fills whatever it is given, so nothing is left underneath it.
Handle(KeyPress)	Moves the selection or confirms it.
HandleMouse(MouseEvent)	Scrolls with the wheel and selects with a click. Clicking the already selected row confirms it, so a double click reads as select-then-activate without the widget timing anything.

Constructors in detail

ListBox(ArlecchinoKeymap)

Obsolete

Constructors of types with required members are not supported in this version of your compiler.

public ListBox(ArlecchinoKeymap keymap);

Creates the list.

Parameters

Name	Type	Description
keymap	ArlecchinoKeymap	Keys to obey, so the list follows the application's bindings.

Properties in detail

IsFocused

public bool IsFocused { get; set; }

Whether the list has focus, which decides how strongly the selection is drawn.

Type bool

ItemStyle

public Func<T, IArlecchinoColor> ItemStyle { get; set; }

Colors an item. Ignored for the selected row, which has to stand out.

Type Func<T, TResult><T, IArlecchinoColor>

Items

public IReadOnlyList<T> Items { get; set; }

What to show. Replacing this pulls the selection back into range on the next frame.

Type IReadOnlyList<T><T>

OnActivate

public Func<T, ViewRoute> OnActivate { get; init; }

What confirming an item does. Returning a route navigates; without this the list simply reports the key as handled.

Type Func<T, TResult><T, ViewRoute>

PaintRow

public Action<SurfaceRegion, T, bool> PaintRow { get; init; }

Draws a row itself, for a list whose rows are not one color. It is given one row to fill and told whether the cursor is on it, and ListBox.Render goes unread while it is set.

Type Action<T1, T2, T3><SurfaceRegion, T, bool>

Render

public Func<T, string> Render { get; init; }

Turns an item into its row of text. Longer text is truncated by column, not by character.

Type Func<T, TResult><T, string>

SelectedIndex

public int SelectedIndex { get; set; }

Index of the selected row.

Type int

SelectedItem

public T SelectedItem { get; }

The selected item, or the type's default when the list is empty.

Type T

Methods in detail

Draw(SurfaceRegion)

public SurfaceRegion Draw(SurfaceRegion region);

Draws the rows around the selection and remembers where they landed, which is what lets clicks and wheel events be resolved afterward. The list fills whatever it is given, so nothing is left underneath it.

Parameters

Name	Type	Description
region	SurfaceRegion	Where to draw.

Returns SurfaceRegion — An empty region: the list uses every row it is handed.

Handle(KeyPress)

public FocusResult Handle(KeyPress key);

Moves the selection or confirms it.

Parameters

Name	Type	Description
key	KeyPress	The key that was pressed.

Returns FocusResult — What became of the key, including a route when confirming navigates.

HandleMouse(MouseEvent)

public FocusResult HandleMouse(MouseEvent mouse);

Scrolls with the wheel and selects with a click. Clicking the already selected row confirms it, so a double click reads as select-then-activate without the widget timing anything.

Parameters

Name	Type	Description
mouse	MouseEvent	The event that arrived.

Returns FocusResult — What became of the event, including a route when a row was activated.