Class ListControl

Namespace

SharpConsoleUI.Controls

Assembly

SharpConsoleUI.dll

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

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

Inheritance

object

ListControl

Implements

IInteractiveControl

IFocusableControl

IMouseAwareControl

IWindowControl

IDisposable

IDOMPaintable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

WindowControlExtensions.NotifyParentWindowOfFocusChange(IFocusableControl, bool)

WindowControlExtensions.GetParentWindow(IWindowControl)

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

ActualHeight

Gets the actual rendered height in lines.

public int? ActualHeight { get; }

Property Value

int?

ActualWidth

Gets the actual rendered width in characters.

public int? ActualWidth { get; }

Property Value

int?

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

Container

Gets or sets the parent container that hosts this control.

public IContainer? Container { get; set; }

Property Value

IContainer

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

Gets or sets whether this control currently has keyboard focus.

public bool HasFocus { get; set; }

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

HighlightedIndex

Gets the index of the currently highlighted item (for arrow key navigation). -1 if no item is highlighted.

public int HighlightedIndex { get; }

Property Value

int

HorizontalAlignment

Gets or sets the horizontal alignment of the control within its container.

public HorizontalAlignment HorizontalAlignment { get; set; }

Property Value

HorizontalAlignment

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>

Margin

Gets or sets the margin (spacing) around the control.

public Margin Margin { get; set; }

Property Value

Margin

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

Name

Gets or sets the unique name identifier for this control, used for lookup.

public string? Name { get; set; }

Property Value

string

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

SelectionMode

Gets or sets the selection mode (Simple or Complex). Simple: Highlight and selection are merged (like TreeControl). Complex: Highlight and selection are separate (like DropdownControl). Default: Complex (backward compatible).

public ListSelectionMode SelectionMode { get; set; }

Property Value

ListSelectionMode

StickyPosition

Gets or sets whether this control should stick to the top or bottom during scrolling.

public StickyPosition StickyPosition { get; set; }

Property Value

StickyPosition

StringItems

Gets or sets the list items as simple strings.

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

Property Value

List<string>

Tag

Gets or sets an arbitrary object value that can be used to store custom data.

public object? Tag { get; set; }

Property Value

object

Title

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

public string Title { get; set; }

Property Value

string

VerticalAlignment

Gets or sets the vertical alignment of the control within its container.

public VerticalAlignment VerticalAlignment { get; set; }

Property Value

VerticalAlignment

Visible

Gets or sets whether this control is visible.

public bool Visible { get; set; }

Property Value

bool

WantsMouseEvents

Whether this control wants to receive mouse events

public bool WantsMouseEvents { get; }

Property Value

bool

Width

Gets or sets the explicit width of the control, or null for automatic sizing.

public int? Width { get; set; }

Property Value

int?

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.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

GetLogicalContentSize()

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

public Size GetLogicalContentSize()

Returns

Size

The size representing the content's natural dimensions.

Invalidate()

Marks this control as needing to be re-rendered.

public void Invalidate()

MeasureDOM(LayoutConstraints)

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

public LayoutSize MeasureDOM(LayoutConstraints constraints)

Parameters

constraints LayoutConstraints

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

Returns

LayoutSize

The desired size of the control.

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

Paints the control's content directly to a CharacterBuffer.

public 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

SetFocus(bool, FocusReason)

Sets focus to this control

public void SetFocus(bool focus, FocusReason reason = FocusReason.Programmatic)

Parameters

focus bool

Whether to give or remove focus

reason FocusReason

The reason for the focus change

Events

GotFocus

Event fired when the control gains focus

public event EventHandler? GotFocus

Event Type

EventHandler

HighlightChanged

Occurs when the highlighted index changes due to arrow key navigation. Fires before the item is selected/activated. Use this for real-time preview updates as the user browses through items.

public event EventHandler<int>? HighlightChanged

Event Type

EventHandler<int>

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>

LostFocus

Event fired when the control loses focus

public event EventHandler? LostFocus

Event Type

EventHandler

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>

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>