Class ListControl

Namespace

SharpConsoleUI.Controls

Assembly

SharpConsoleUI.dll

A scrollable list control that supports selection, highlighting, and keyboard navigation.

public class ListControl : BaseControl, IDOMPaintable, INotifyPropertyChanged, IInteractiveControl, IFocusableControl, IMouseAwareControl, IWindowControl, IDisposable

Inheritance

object

BaseControl

ListControl

Implements

IDOMPaintable

INotifyPropertyChanged

IInteractiveControl

IFocusableControl

IMouseAwareControl

IWindowControl

IDisposable

Inherited Members

BaseControl.PropertyChanged

BaseControl.GotFocus

BaseControl.LostFocus

BaseControl.Bindings

BaseControl.OnPropertyChanged(string)

BaseControl.SubscribeToFocusManager()

BaseControl.SetProperty<T>(ref T, T, string)

BaseControl.SetProperty<T>(ref T, T, Func<T, T>, string)

BaseControl.ActualX

BaseControl.ActualY

BaseControl.ActualWidth

BaseControl.ActualHeight

BaseControl.HorizontalAlignment

BaseControl.VerticalAlignment

BaseControl.Container

BaseControl.Margin

BaseControl.StickyPosition

BaseControl.Name

BaseControl.Tag

BaseControl.Visible

BaseControl.Width

BaseControl.Height

BaseControl.Invalidate()

BaseControl.SetActualBounds(LayoutRect)

BaseControl.Dispose()

BaseControl.ComputeHasFocus()

BaseControl.ComputeIsInFocusPath()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

WindowControlExtensions.RequestFocus(IFocusableControl, FocusReason)

WindowControlExtensions.GetParentWindow(IWindowControl)

WindowControlExtensions.GetPortalAncestor(IWindowControl)

BindingExtensions.BindTwoWay<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.BindTwoWay<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>, Func<TTgt, TSrc>)

BindingExtensions.Bind<TControl, TSource, TValue>(TControl, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TControl, TSource, TSrc, TTgt>(TControl, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TValue>(TBuilder, TSource, Expression<Func<TSource, TValue>>, Expression<Func<TControl, TValue>>)

BindingExtensions.Bind<TBuilder, TControl, TSource, TSrc, TTgt>(TBuilder, TSource, Expression<Func<TSource, TSrc>>, Expression<Func<TControl, TTgt>>, Func<TSrc, TTgt>)

Constructors

ListControl()

Initializes a new empty ListControl with no title.

public ListControl()

ListControl(IEnumerable<ListItem>?)

Initializes a new ListControl with ListItem objects and no title.

public ListControl(IEnumerable<ListItem>? items)

Parameters

items IEnumerable<ListItem>

The initial ListItem objects to populate the list.

ListControl(IEnumerable<string>?)

Initializes a new ListControl with string items and no title.

public ListControl(IEnumerable<string>? items)

Parameters

items IEnumerable<string>

The initial items to populate the list.

ListControl(string)

Initializes a new empty ListControl with a title.

public ListControl(string title)

Parameters

title string

The title displayed at the top of the list.

ListControl(string?, IEnumerable<ListItem>?)

Initializes a new ListControl with a title and ListItem objects.

public ListControl(string? title, IEnumerable<ListItem>? items)

Parameters

title string

The title displayed at the top of the list.

items IEnumerable<ListItem>

The initial ListItem objects to populate the list.

ListControl(string?, IEnumerable<string>?)

Initializes a new ListControl with a title and string items.

public ListControl(string? title, IEnumerable<string>? items)

Parameters

title string

The title displayed at the top of the list.

items IEnumerable<string>

The initial items to populate the list.

Properties

AutoAdjustWidth

Gets or sets whether the control automatically adjusts its width to fit content.

public bool AutoAdjustWidth { get; set; }

Property Value

bool

AutoHighlightOnFocus

Gets or sets whether to auto-highlight on focus gain. When true, the control will highlight the selected item (or first item) when focused. Default: true (fixes UX issue where focus had no visual feedback).

public bool AutoHighlightOnFocus { get; set; }

Property Value

bool

BackgroundColor

Gets or sets the background color of the list control.

public Color? BackgroundColor { get; set; }

Property Value

Color?

CanFocusWithMouse

Whether this control can receive focus via mouse clicks

public bool CanFocusWithMouse { get; }

Property Value

bool

CanReceiveFocus

Whether this control can receive focus

public bool CanReceiveFocus { get; }

Property Value

bool

CheckboxMode

Gets or sets whether items display checkboxes ([x]/[ ]) and Space toggles checked state.

public bool CheckboxMode { get; set; }

Property Value

bool

ContentHeight

Gets the actual rendered height in lines.

public int? ContentHeight { get; }

Property Value

int?

ContentWidth

Gets the actual rendered width in characters.

public override int? ContentWidth { get; }

Property Value

int?

DoubleClickActivates

Gets or sets whether double-click activates items. Default: true.

public bool DoubleClickActivates { get; set; }

Property Value

bool

DoubleClickThresholdMs

Gets or sets the double-click threshold in milliseconds. Default: 500.

public int DoubleClickThresholdMs { get; set; }

Property Value

int

FocusedBackgroundColor

Gets or sets the background color when the list has focus.

public Color? FocusedBackgroundColor { get; set; }

Property Value

Color?

FocusedForegroundColor

Gets or sets the foreground color when the list has focus.

public Color FocusedForegroundColor { get; set; }

Property Value

Color

ForegroundColor

Gets or sets the foreground color of the list control.

public Color ForegroundColor { get; set; }

Property Value

Color

HasFocus

public bool HasFocus { get; }

Property Value

bool

HighlightBackgroundColor

Gets or sets the background color for highlighted items.

public Color HighlightBackgroundColor { get; set; }

Property Value

Color

HighlightForegroundColor

Gets or sets the foreground color for highlighted items.

public Color HighlightForegroundColor { get; set; }

Property Value

Color

HoverHighlightsItems

Gets or sets whether mouse hover highlights items visually. Default: true.

public bool HoverHighlightsItems { get; set; }

Property Value

bool

HoveredIndex

Gets the index of the currently hovered item (mouse cursor). -1 if no item is hovered.

public int HoveredIndex { get; }

Property Value

int

IsEnabled

Gets or sets whether the list control is enabled and can be interacted with.

public bool IsEnabled { get; set; }

Property Value

bool

IsSelectable

Gets or sets whether items can be selected in the list.

public bool IsSelectable { get; set; }

Property Value

bool

ItemFormatter

Gets or sets a custom formatter for rendering list items.

public ListControl.ItemFormatterEvent? ItemFormatter { get; set; }

Property Value

ListControl.ItemFormatterEvent

Items

Gets or sets the collection of items displayed in the list.

public List<ListItem> Items { get; set; }

Property Value

List<ListItem>

MaxVisibleItems

Gets or sets the maximum number of items visible at once. If null, calculated from available height.

public int? MaxVisibleItems { get; set; }

Property Value

int?

MouseWheelScrollSpeed

Gets or sets the number of lines to scroll with mouse wheel. Default: 3.

public int MouseWheelScrollSpeed { get; set; }

Property Value

int

ScrollbarVisibility

Gets or sets when the vertical scrollbar should be displayed. Default: Auto (shows only when content exceeds viewport).

public ScrollbarVisibility ScrollbarVisibility { get; set; }

Property Value

ScrollbarVisibility

SelectOnRightClick

Gets or sets whether a right-click selects the item under the mouse cursor before firing the MouseRightClick event. Default: false (preserves backward compatibility).

public bool SelectOnRightClick { get; set; }

Property Value

bool

SelectedIndex

Gets or sets the index of the currently selected item. -1 if no item is selected.

public int SelectedIndex { get; set; }

Property Value

int

SelectedItem

Gets or sets the currently selected item.

public ListItem? SelectedItem { get; set; }

Property Value

ListItem

SelectedValue

Gets or sets the text of the currently selected item.

public string? SelectedValue { get; set; }

Property Value

string

StringItems

Gets or sets the list items as simple strings.

public List<string> StringItems { get; set; }

Property Value

List<string>

Title

Gets or sets the title displayed at the top of the list.

public string Title { get; set; }

Property Value

string

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; }

Property Value

bool

Methods

AddItem(ListItem)

Adds a ListItem to the list.

public void AddItem(ListItem item)

Parameters

item ListItem

The item to add.

AddItem(string)

Adds a new item with the specified text.

public void AddItem(string text)

Parameters

text string

The text of the item.

AddItem(string, string?, Color?)

Adds a new item with text, optional icon, and icon color.

public void AddItem(string text, string? icon = null, Color? iconColor = null)

Parameters

text string

The text of the item.

icon string

Optional icon to display.

iconColor Color?

Optional color for the icon.

ClearItems()

Removes all items from the list.

public void ClearItems()

Create()

Creates a fluent builder for constructing a ListControl.

public static ListBuilder Create()

Returns

ListBuilder

A new ListBuilder instance.

GetCheckedItems()

Returns all items where IsChecked is true.

public List<ListItem> GetCheckedItems()

Returns

List<ListItem>

GetLogicalContentSize()

Gets the logical size of the control's content without rendering.

public override Size GetLogicalContentSize()

Returns

Size

The size representing the content's natural dimensions.

MeasureDOM(LayoutConstraints)

Measures the control's desired size given the available constraints.

public override LayoutSize MeasureDOM(LayoutConstraints constraints)

Parameters

constraints LayoutConstraints

The layout constraints (min/max width/height).

Returns

LayoutSize

The desired size of the control.

OnDisposing()

Called during Dispose() before Container is set to null. Override to perform control-specific cleanup (null events, close portals, clear data, etc.).

protected override void OnDisposing()

PaintDOM(CharacterBuffer, LayoutRect, LayoutRect, Color, Color)

Paints the control's content directly to a CharacterBuffer.

public override void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutRect clipRect, Color defaultFg, Color defaultBg)

Parameters

buffer CharacterBuffer

The buffer to paint to.

bounds LayoutRect

The absolute bounds where the control should paint.

clipRect LayoutRect

The clipping rectangle (visible area).

defaultFg Color

defaultBg Color

ProcessKey(ConsoleKeyInfo)

Processes a keyboard input event.

public bool ProcessKey(ConsoleKeyInfo key)

Parameters

key ConsoleKeyInfo

The key information for the pressed key.

Returns

bool

True if the key was handled by this control; otherwise, false.

ProcessMouseEvent(MouseEventArgs)

Processes a mouse event for this control

public bool ProcessMouseEvent(MouseEventArgs args)

Parameters

args MouseEventArgs

Mouse event arguments with control-relative coordinates

Returns

bool

True if the event was handled and should not propagate further

SetAllChecked(bool)

Sets all items' IsChecked state and fires CheckedItemsChanged once.

public void SetAllChecked(bool value)

Parameters

value bool

Events

CheckedItemsChanged

Occurs when the checked state of any item changes.

public event EventHandler<EventArgs>? CheckedItemsChanged

Event Type

EventHandler<EventArgs>

ItemActivated

Occurs when an item is activated (Enter or double-click).

public event EventHandler<ListItem>? ItemActivated

Event Type

EventHandler<ListItem>

ItemHovered

Occurs when an item is hovered by the mouse. The index is the hovered item index, or -1 if mouse left all items.

public event EventHandler<int>? ItemHovered

Event Type

EventHandler<int>

MouseClick

Occurs when the control is clicked with the mouse.

public event EventHandler<MouseEventArgs>? MouseClick

Event Type

EventHandler<MouseEventArgs>

MouseDoubleClick

Occurs when an item is double-clicked with the mouse.

public event EventHandler<MouseEventArgs>? MouseDoubleClick

Event Type

EventHandler<MouseEventArgs>

MouseEnter

Occurs when the mouse enters the control area.

public event EventHandler<MouseEventArgs>? MouseEnter

Event Type

EventHandler<MouseEventArgs>

MouseLeave

Occurs when the mouse leaves the control area.

public event EventHandler<MouseEventArgs>? MouseLeave

Event Type

EventHandler<MouseEventArgs>

MouseMove

Occurs when the mouse moves over the control.

public event EventHandler<MouseEventArgs>? MouseMove

Event Type

EventHandler<MouseEventArgs>

MouseRightClick

Occurs when the control is right-clicked with the mouse.

public event EventHandler<MouseEventArgs>? MouseRightClick

Event Type

EventHandler<MouseEventArgs>

SelectedIndexChanged

Occurs when the selected index changes.

public event EventHandler<int>? SelectedIndexChanged

Event Type

EventHandler<int>

SelectedItemChanged

Occurs when the selected item changes.

public event EventHandler<ListItem?>? SelectedItemChanged

Event Type

EventHandler<ListItem>

SelectedValueChanged

Occurs when the selected value (text) changes.

public event EventHandler<string?>? SelectedValueChanged

Event Type

EventHandler<string>