Class ConsoleWindowSystem

Namespace

SharpConsoleUI

Assembly

SharpConsoleUI.dll

The main window system that manages console windows, input processing, and rendering. Provides window management, focus handling, theming, and event processing for console applications.

public class ConsoleWindowSystem

Inheritance

object

ConsoleWindowSystem

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

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<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

ConsoleWindowSystem(IConsoleDriver, ConsoleWindowSystemOptions?, RegistryConfiguration?)

Initializes a new instance of the ConsoleWindowSystem class with the default theme.

public ConsoleWindowSystem(IConsoleDriver driver, ConsoleWindowSystemOptions? options = null, RegistryConfiguration? registryConfiguration = null)

Parameters

driver IConsoleDriver

Pre-configured console driver.

options ConsoleWindowSystemOptions

Optional configuration options for system behavior.

registryConfiguration RegistryConfiguration

Optional registry configuration for persistent key-value storage.

ConsoleWindowSystem(IConsoleDriver, ITheme, ConsoleWindowSystemOptions?, RegistryConfiguration?)

Initializes a new instance of the ConsoleWindowSystem class with a specific theme instance.

public ConsoleWindowSystem(IConsoleDriver driver, ITheme theme, ConsoleWindowSystemOptions? options = null, RegistryConfiguration? registryConfiguration = null)

Parameters

driver IConsoleDriver

Pre-configured console driver.

theme ITheme

The theme instance to use.

options ConsoleWindowSystemOptions

Optional configuration options for system behavior.

registryConfiguration RegistryConfiguration

Optional registry configuration for persistent key-value storage.

ConsoleWindowSystem(IConsoleDriver, string, ConsoleWindowSystemOptions?, RegistryConfiguration?)

Initializes a new instance of the ConsoleWindowSystem class with a theme specified by name.

public ConsoleWindowSystem(IConsoleDriver driver, string themeName, ConsoleWindowSystemOptions? options = null, RegistryConfiguration? registryConfiguration = null)

Parameters

driver IConsoleDriver

Pre-configured console driver.

themeName string

The name of the theme to use.

options ConsoleWindowSystemOptions

Optional configuration options for system behavior.

registryConfiguration RegistryConfiguration

Optional registry configuration for persistent key-value storage.

ConsoleWindowSystem(RenderMode, ConsoleWindowSystemOptions?, RegistryConfiguration?)

Initializes a new instance with a render mode.

public ConsoleWindowSystem(RenderMode renderMode, ConsoleWindowSystemOptions? options = null, RegistryConfiguration? registryConfiguration = null)

Parameters

renderMode RenderMode

The rendering mode to use.

options ConsoleWindowSystemOptions

Optional configuration options for system behavior.

registryConfiguration RegistryConfiguration

Optional registry configuration for persistent key-value storage.

Fields

Performance

Gets the performance tracker for monitoring frame rates and render times.

public PerformanceTracker Performance

Field Value

PerformanceTracker

Properties

ActiveWindow

Gets the currently active window, or null if no window is active.

public Window? ActiveWindow { get; }

Property Value

Window

Animations

Gets the animation manager for creating and controlling tweened animations.

public AnimationManager Animations { get; }

Property Value

AnimationManager

BottomPanel

Gets the bottom panel (desktop bar) if configured, or null.

public Panel? BottomPanel { get; }

Property Value

Panel

ConsoleDriver

Gets or sets the console driver used for low-level console operations.

public IConsoleDriver ConsoleDriver { get; set; }

Property Value

IConsoleDriver

DesktopBackground

Gets or sets the desktop background configuration.

public DesktopBackgroundConfig? DesktopBackground { get; set; }

Property Value

DesktopBackgroundConfig

DesktopBackgroundColor

Gets or sets the desktop background color directly. This is a convenience property — it creates/updates the DesktopBackgroundConfig. Set to Color.Transparent for terminal-level transparency.

public Color? DesktopBackgroundColor { get; set; }

Property Value

Color?

DesktopBackgroundService

Gets the desktop background service.

public DesktopBackgroundService DesktopBackgroundService { get; }

Property Value

DesktopBackgroundService

DesktopBottomRight

Gets the bottom-right coordinate of the usable desktop area (excluding status bars).

public Point DesktopBottomRight { get; }

Property Value

Point

DesktopDimensions

Gets the dimensions of the usable desktop area (excluding status bars).

public Size DesktopDimensions { get; }

Property Value

Size

DesktopPortalService

Gets the desktop portal service for managing desktop-level overlay portals.

public DesktopPortalService DesktopPortalService { get; }

Property Value

DesktopPortalService

DesktopUpperLeft

Gets the upper-left coordinate of the usable desktop area (excluding status bars).

public Point DesktopUpperLeft { get; }

Property Value

Point

IsIdle

Gets a value indicating whether the input system is currently idle (no input for the configured threshold).

public bool IsIdle { get; }

Property Value

bool

IsOnUIThread

True when the caller is on the main-loop (UI) thread.

public bool IsOnUIThread { get; }

Property Value

bool

IsRunning

Gets a value indicating whether the window system is currently running.

public bool IsRunning { get; }

Property Value

bool

LogService

Gets the library-managed logging service. Subscribe to LogAdded event or call GetRecentLogs() to access internal logs.

public ILogService LogService { get; }

Property Value

ILogService

ModalStateService

Gets the modal state service for managing modal window behavior.

public ModalStateService ModalStateService { get; }

Property Value

ModalStateService

NotificationStateService

Gets the notification state service for managing notifications and toasts.

public NotificationStateService NotificationStateService { get; }

Property Value

NotificationStateService

Options

Gets or sets the current console window system options.

public ConsoleWindowSystemOptions Options { get; set; }

Property Value

ConsoleWindowSystemOptions

PanelStateService

Gets the panel state service for managing panels, Start menu, and panel visibility.

public PanelStateService PanelStateService { get; }

Property Value

PanelStateService

PipedInput

Gets the text that was piped into the application via stdin, or null if stdin is a TTY. Automatically captured at construction time — available throughout the app lifecycle.

public string? PipedInput { get; }

Property Value

string

PipedLines

Gets the piped stdin split into lines, or null if stdin is a TTY.

public string[]? PipedLines { get; }

Property Value

string[]

PluginStateService

Gets the plugin state service for managing plugins and their contributions.

public PluginStateService PluginStateService { get; }

Property Value

PluginStateService

RegistryStateService

Gets the registry state service for persistent key-value storage. Null if no RegistryConfiguration was provided at construction.

public RegistryStateService? RegistryStateService { get; }

Property Value

RegistryStateService

SettingsRegistrationService

Gets the settings registration service for adding custom settings pages.

public SettingsRegistrationService SettingsRegistrationService { get; }

Property Value

SettingsRegistrationService

SynchronizationContextInstalled

True if a UI SynchronizationContext was installed for the current Run() — i.e. awaited continuations in UI handlers resume on the UI (main-loop) thread (WinForms/WPF-style). Reflects the resolved state, not merely the requested option. False before Run() starts and after it returns.

public bool SynchronizationContextInstalled { get; }

Property Value

bool

Theme

Gets the theme used for styling windows and controls. Use ThemeStateService.CurrentTheme or ThemeStateService.SetTheme() for theme management.

public ITheme Theme { get; }

Property Value

ITheme

ThemeRegistryService

Gets the per-instance theme registry (catalog of available themes by name). Themes registered here — including those contributed by loaded plugins — are scoped to this window system and do not leak to other instances.

public ThemeRegistryStateService ThemeRegistryService { get; }

Property Value

ThemeRegistryStateService

ThemeStateService

Gets the theme state service for managing theme application.

public ThemeStateService ThemeStateService { get; }

Property Value

ThemeStateService

ToastService

Gets the toast notification service.

public ToastService ToastService { get; }

Property Value

ToastService

TopPanel

Gets the top panel (desktop bar) if configured, or null.

public Panel? TopPanel { get; }

Property Value

Panel

WindowStateService

Gets the window state service for managing window lifecycle and state.

public WindowStateService WindowStateService { get; }

Property Value

WindowStateService

Windows

Gets a read-only dictionary of all windows in the system, keyed by their GUID.

public IReadOnlyDictionary<string, Window> Windows { get; }

Property Value

IReadOnlyDictionary<string, Window>

Methods

AddWindow(Window, bool)

Adds a window to the window system.

public Window AddWindow(Window window, bool activateWindow = true)

Parameters

window Window

The window to add.

activateWindow bool

Whether to activate the window after adding. Defaults to true.

Returns

Window

The added window.

CloseModalWindow(Window?)

Closes a modal window and optionally activates its parent window.

public void CloseModalWindow(Window? modalWindow)

Parameters

modalWindow Window

The modal window to close. If null or not a modal window, the method returns without action.

CloseWindow(Window?, bool, bool)

Closes a window and removes it from the window system.

public bool CloseWindow(Window? window, bool activateParent = true, bool force = false)

Parameters

window Window

The window to close. If null or not in the system, returns false.

activateParent bool

Whether to activate the parent window after closing. Defaults to true.

force bool

If true, forces the window to close even if IsClosable is false or OnClosing cancels.

Returns

bool

True if the window was closed successfully; false otherwise.

CycleActiveWindow()

Cycles to the next active window (Ctrl+T handler).

public void CycleActiveWindow()

EnqueueOnUIThread(Action)

Enqueues an action to be executed on the UI thread during the next main loop iteration. Safe to call from any thread. Actions run between input processing and rendering.

public void EnqueueOnUIThread(Action action)

Parameters

action Action

The action to execute on the UI thread.

EnqueueOnUIThread(Action, string?)

Enqueues an action to be executed on the UI thread during the next main loop iteration, tagging it with a best-effort label that appears in BlockedIn if the action stalls the loop. Safe to call from any thread.

public void EnqueueOnUIThread(Action action, string? label)

Parameters

action Action

The action to execute on the UI thread.

label string

A diagnostic label for the watchdog breadcrumb, or null.

ForceFullRedraw()

Forces a full screen clear and desktop repaint. Used when desktop bounds change (e.g., panel visibility toggle).

public void ForceFullRedraw()

ForceFullRepaint()

Forces a complete screen repaint that re-emits every cell, including regions the diff renderer would otherwise skip. Resets the driver's front buffer so stray terminal output (manual console writes, the unresponsive banner) is overwritten. Called on recovery.

public void ForceFullRepaint()

ForceRender()

Forces an immediate render cycle, bypassing frame rate limiting. Intended for benchmarking and testing scenarios.

public void ForceRender()

GetWindowAtPoint(Point)

Finds the topmost window at the specified point.

public Window? GetWindowAtPoint(Point point)

Parameters

point Point

The point in absolute screen coordinates.

Returns

Window

The topmost window at the point, or null if none found.

InvokeAsync(Action)

Marshals work onto the UI thread and awaits completion. Runs inline if already on it.

public Task InvokeAsync(Action work)

Parameters

work Action

Returns

Task

InvokeAsync(Action, string?)

Marshals work onto the UI thread and awaits completion, tagging it with a best-effort watchdog label. Runs inline if already on the UI thread.

public Task InvokeAsync(Action work, string? label)

Parameters

work Action

The work to execute on the UI thread.

label string

A diagnostic label for the watchdog breadcrumb, or null.

Returns

Task

InvokeAsync<T>(Func<T>)

Marshals work onto the UI thread, awaits, and returns its result. Runs inline if already on it.

public Task<T> InvokeAsync<T>(Func<T> work)

Parameters

work Func<T>

Returns

Task<T>

Type Parameters

T

InvokeAsync<T>(Func<T>, string?)

Marshals work onto the UI thread, awaits, and returns its result, tagging it with a best-effort watchdog label. Runs inline if already on the UI thread.

public Task<T> InvokeAsync<T>(Func<T> work, string? label)

Parameters

work Func<T>

The work to execute on the UI thread.

label string

A diagnostic label for the watchdog breadcrumb, or null.

Returns

Task<T>

Type Parameters

T

ProcessOnce()

Processes one iteration of the main loop (input, display, cursor). This is useful for modal dialogs that need to block while still processing UI events.

public void ProcessOnce()

RegisterDragAutoScroll(IDragAutoScrollTarget)

Registers the control whose active drag-select should drive continuous autoscroll. The main loop advances it each frame while the cursor is held past the viewport edge. Pass the same target again to refresh; call UnregisterDragAutoScroll(IDragAutoScrollTarget) when the drag ends.

public void RegisterDragAutoScroll(IDragAutoScrollTarget target)

Parameters

target IDragAutoScrollTarget

RegisterGlobalShortcut(ConsoleModifiers, ConsoleKey, Action)

Registers a global keyboard shortcut that is handled before routing to windows. The key is always consumed (it does not continue to the focused window). To let the handler decide whether the key is consumed, use the Func<TResult> overload.

public void RegisterGlobalShortcut(ConsoleModifiers modifiers, ConsoleKey key, Action action)

Parameters

modifiers ConsoleModifiers

The modifier keys (e.g. Control, Alt, Shift).

key ConsoleKey

The key to bind.

action Action

The action to invoke when the shortcut is pressed.

RegisterGlobalShortcut(ConsoleModifiers, ConsoleKey, Func<bool>)

Registers a global keyboard shortcut whose handler decides whether the key is consumed. Return true to consume the key (stop routing); return false to decline, letting the key continue down the normal pipeline (window cycle, exit key, active window). This enables conditional shortcuts — e.g. a global Ctrl+Q that reaches a focused control but acts globally when nothing relevant is focused.

public void RegisterGlobalShortcut(ConsoleModifiers modifiers, ConsoleKey key, Func<bool> action)

Parameters

modifiers ConsoleModifiers

The modifier keys (e.g. Control, Alt, Shift).

key ConsoleKey

The key to bind.

action Func<bool>

The handler to invoke; returns true to consume the key, false to decline.

RegisterSettingsGroup(string, Color, Action<SettingsGroupBuilder>)

Registers a settings group with multiple pages, shown in the Settings dialog.

public void RegisterSettingsGroup(string name, Color accentColor, Action<SettingsGroupBuilder> configure)

Parameters

name string

The display name of the settings group.

accentColor Color

The accent color used for this group in the navigation sidebar.

configure Action<SettingsGroupBuilder>

Action that configures the group's pages via a builder.

RegisterSettingsPage(string, string?, string?, Action<ScrollablePanelControl>?)

Registers a single settings page under the "Extensions" group in the Settings dialog.

public void RegisterSettingsPage(string name, string? icon = null, string? subtitle = null, Action<ScrollablePanelControl>? content = null)

Parameters

name string

The display name of the settings page.

icon string

Optional icon character or string shown beside the page name.

subtitle string

Optional subtitle shown below the page name.

content Action<ScrollablePanelControl>

Factory that populates the page content panel.

RequestExit(int)

Requests the window system to exit with the specified exit code.

public void RequestExit(int exitCode)

Parameters

exitCode int

Run()

Starts the main event loop of the window system. Blocks until Shutdown(int) is called.

public int Run()

Returns

int

The exit code set by Shutdown(int) or 1 if an unhandled exception occurred.

SetActiveWindow(Window)

Sets the specified window as the active window, handling modal window logic and focus.

public void SetActiveWindow(Window window)

Parameters

window Window

The window to activate. If null, the method returns without action.

Shutdown(int)

Gracefully shuts down the console window system with the specified exit code

public void Shutdown(int exitCode = 0)

Parameters

exitCode int

The exit code to return

UnregisterDragAutoScroll(IDragAutoScrollTarget)

Stops drag-select autoscroll. Safe to call when nothing is registered.

public void UnregisterDragAutoScroll(IDragAutoScrollTarget target)

Parameters

target IDragAutoScrollTarget

VerifyAccess()

Throws if the caller is not on the UI thread.

public void VerifyAccess()

Events

IdleStateChanged

Raised when the input idle state changes (idle started or ended).

public event EventHandler<IdleStateEventArgs>? IdleStateChanged

Event Type

EventHandler<IdleStateEventArgs>

Recovered

Raised on the UI thread when the main loop recovers after a stall. Safe to touch the UI.

public event EventHandler<RecoveredEventArgs>? Recovered

Event Type

EventHandler<RecoveredEventArgs>

Unresponsive

Raised on the watchdog timer thread when the main loop blocks past the unresponsive threshold. Handlers MUST be thread-safe and MUST NOT touch the UI. Set ShowBanner = false to own the display.

public event EventHandler<UnresponsiveEventArgs>? Unresponsive

Event Type

EventHandler<UnresponsiveEventArgs>

WindowResized

Raised on the UI thread after the console has been resized AND the framework has repositioned/resized all windows. Handlers perform app-specific layout reflow by mutating controls directly (they are already on the UI thread). The framework re-invalidates all windows after every handler returns, so a handler MUST NOT call Invalidate itself. This is the application-facing console-resize event; prefer it over the low-level ScreenResized.

public event EventHandler<Size>? WindowResized

Event Type

EventHandler<Size>