Controls Reference

SharpConsoleUI provides 25+ built-in UI controls for building rich console applications.

Table of Contents

Overview

All controls implement the IWindowControl interface and can be added to windows. Interactive controls implement additional interfaces like IInteractiveControl, IFocusableControl, and IMouseAwareControl.

Common Control Properties

All controls support:

  • Name - Unique identifier for FindControl<T>(name) lookups
  • Visible - Show/hide control
  • Container - Reference to parent container
  • Tag - Store custom data
  • Layout properties (Width, Margin, Alignment, StickyPosition)

Basic Input Controls

Controls for user input and interaction.

Control Description Details
ButtonControl Clickable button with text Click events, keyboard/mouse support
CheckboxControl Toggle checkbox with label Checked/unchecked state, change events
PromptControl Single-line text input Enter key events, input validation, max length
MultilineEditControl Multi-line text editor Scrolling, word wrap, text selection

Selection Controls

Controls for selecting items from lists or hierarchies.

Control Description Details
ListControl Scrollable list with selection Single selection, item activation, keyboard navigation
TreeControl Hierarchical tree view Expand/collapse nodes, selection, keyboard navigation
DropdownControl Dropdown selection list Click to expand, keyboard navigation, portal rendering
MenuControl Menu bar with dropdowns Horizontal/vertical menus, submenus, separators, keyboard shortcuts

Display Controls

Controls for displaying formatted content.

Control Description Details
MarkupControl Rich text with Spectre markup Colors, bold, italic, links using [markup] syntax
FigleControl ASCII art text (Figlet) Large stylized text, multiple fonts
LogViewerControl Log message viewer Auto-scroll, filtering, severity colors
SpectreRenderableControl Wrapper for Spectre widgets Display Tables, Trees, Panels, Charts, etc.
PanelControl Bordered content panel Headers, multiple border styles, padding, mouse support
RuleControl Horizontal rule/separator Optional title, colors, horizontal line
SparklineControl Time-series sparkline graph Block, braille, or bidirectional modes; borders; titles
BarGraphControl Horizontal bar graph Gradient color thresholds, labels, value display

Layout Controls

Controls for organizing other controls.

Control Description Details
ColumnContainer Vertical stack container Stack controls vertically, padding, alignment
ScrollablePanelControl Scrollable content area Vertical scrolling, contains multiple controls
HorizontalGridControl Multi-column layout Variable-width columns, alignment, splitters
SplitterControl Resizable divider Drag to resize adjacent columns
ToolbarControl Horizontal button toolbar Quick access buttons, separators
SeparatorControl Visual separator Simple horizontal line

Utility Controls

Special-purpose controls.

Control Description Details
RuleControl Titled horizontal rule Section dividers with optional title
SeparatorControl Plain horizontal line Visual spacing

Interfaces

Controls implement these interfaces based on their capabilities:

IWindowControl (Base Interface)

All controls implement this interface:

public interface IWindowControl : IDisposable
{
    IContainer? Container { get; set; }
    string? Name { get; set; }
    object? Tag { get; set; }
    bool Visible { get; set; }

    void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutRect clipRect);
    Size MeasureDOM(int availableWidth);
    void Invalidate(bool recursive = false);
}

IInteractiveControl

Controls that handle keyboard input:

public interface IInteractiveControl : IWindowControl
{
    bool IsEnabled { get; set; }
    bool ProcessKey(KeyEventArgs e);
}

Implemented by: Button, Checkbox, Prompt, MultilineEdit, List, Tree, Dropdown, Menu

IFocusableControl

Controls that can receive keyboard focus:

public interface IFocusableControl : IInteractiveControl
{
    bool HasFocus { get; }
    bool CanReceiveFocus { get; }
    event EventHandler? GotFocus;
    event EventHandler? LostFocus;
    void SetFocus();
}

Implemented by: Button, Checkbox, Prompt, MultilineEdit, List, Tree, Dropdown

IMouseAwareControl

Controls that handle mouse events:

public interface IMouseAwareControl : IWindowControl
{
    bool WantsMouseEvents { get; }
    bool CanFocusWithMouse { get; }
    event EventHandler<MouseEventArgs>? MouseClick;
    event EventHandler<MouseEventArgs>? MouseEnter;
    event EventHandler<MouseEventArgs>? MouseLeave;
    event EventHandler<MouseEventArgs>? MouseMove;
    void ProcessMouseEvent(MouseEventArgs e);
}

Implemented by: Button, List, Tree, Dropdown, Menu, Toolbar, ScrollablePanel

IContainer

Controls that can contain other controls:

public interface IContainer : IWindowControl
{
    void AddControl(IWindowControl control);
    void RemoveControl(IWindowControl control);
    IReadOnlyList<IWindowControl> GetControls();
    T? FindControl<T>(string name) where T : IWindowControl;
}

Implemented by: ColumnContainer, ScrollablePanelControl, HorizontalGridControl

Quick Reference

Creating Controls

// Using builders (recommended)
var button = Controls.Button("Click Me")
    .WithWidth(20)
    .OnClick((s, e, w) => { })
    .Build();

// Using constructors
var button = new ButtonControl
{
    Text = "Click Me",
    Width = 20
};
button.OnClick += (s, e) => { };

// Using static helpers
var label = Controls.Label("Simple text");
var header = Controls.Header("Title");

Adding to Windows

window.AddControl(control);

Finding Controls by Name

// Name a control
window.AddControl(
    Controls.Prompt("Name:")
        .WithName("nameInput")
        .Build()
);

// Find it later
var input = window.FindControl<PromptControl>("nameInput");
if (input != null)
{
    string text = input.Text;
}

Common Patterns

Input Form

window.AddControl(Controls.Header("Contact Form"));
window.AddControl(Controls.Prompt("Name:").WithName("name").Build());
window.AddControl(Controls.Prompt("Email:").WithName("email").Build());
window.AddControl(Controls.Button("Submit")
    .OnClick((s, e, w) =>
    {
        var name = w.FindControl<PromptControl>("name")?.Text;
        var email = w.FindControl<PromptControl>("email")?.Text;
        // Process form...
    })
    .Build());

Data Display

var list = Controls.List()
    .AddItem("Item 1")
    .AddItem("Item 2")
    .AddItem("Item 3")
    .OnItemActivated((s, item, w) =>
    {
        windowSystem.NotificationStateService.ShowNotification(
            "Selected", item.Text, NotificationSeverity.Info);
    })
    .Build();

window.AddControl(list);

Layout

var grid = Controls.HorizontalGrid()
    .WithAlignment(HorizontalAlignment.Stretch)
    .Column(col => col.Add(Controls.Label("Left")))
    .Column(col => col.Add(Controls.Label("Center")))
    .Column(col => col.Add(Controls.Label("Right")))
    .Build();

window.AddControl(grid);

Next Steps

Browse detailed documentation for specific controls:

Essential Controls

Advanced Controls

Back to Main Documentation

Edit this page