Namespace Terminal.Gui.Drivers

The Drivers namespace provides cross-platform terminal abstraction and console driver implementations.

Terminal.Gui.Drivers contains the platform abstraction layer that enables Terminal.Gui to run consistently across Windows, macOS, and Linux/Unix systems. This namespace includes console drivers, component factories, input/output processors, and platform-specific optimizations.

The driver system handles low-level terminal operations including cursor management, color support detection, input processing, screen buffer management, and terminal size monitoring. It provides a unified API through IConsoleDriver while accommodating the unique characteristics of different terminal environments.

Architecture Overview

Terminal.Gui v2 uses a modular driver architecture based on the Component Factory pattern:

IComponentFactory: Factory interface that creates driver-specific components
ConsoleDriverFacade: Unified facade implementing IConsoleDriver and IConsoleDriverFacade
IConsoleInput: Reads raw console input events on a separate thread
IConsoleOutput: Renders the output buffer to the terminal
IInputProcessor: Translates raw input into Terminal.Gui events (Key, MouseEventArgs)
IOutputBuffer: Manages the screen buffer and drawing operations
IWindowSizeMonitor: Detects and reports terminal size changes

Available Drivers

Terminal.Gui provides three console driver implementations optimized for different platforms:

DotNetDriver (dotnet, NetComponentFactory) - Cross-platform driver using .NET System.Console API. Works on all platforms.
WindowsDriver (windows, WindowsComponentFactory) - Windows-optimized driver using Windows Console APIs for enhanced performance and features.
UnixDriver (unix, UnixComponentFactory) - Unix/Linux/macOS-optimized driver using platform-specific APIs.
FakeDriver (fake, FakeComponentFactory) - Mock driver for unit testing.

The appropriate driver is automatically selected based on the platform. Windows defaults to WindowsDriver, while Unix-based systems default to UnixDriver.

Example Usage

// Driver selection is typically automatic
Application.Init();

// Access current driver
IConsoleDriver driver = Application.Driver;
bool supportsColors = driver.SupportsTrueColor;

// Explicitly specify a driver
Application.ForceDriver = "dotnet";
Application.Init();

// Or pass driver name to Init
Application.Init(driverName: "unix");

Threading Model

The driver architecture uses a multi-threaded design:

Input Thread: Asynchronously reads console input without blocking the UI
Main UI Thread: Processes events, performs layout, and renders output

This separation ensures responsive input handling even during intensive UI operations.

Deep Dive

See the Cross-Platform Driver Model for comprehensive details.

Classes

AnsiComponentFactory: IComponentFactory<TInputRecord> implementation for the pure ANSI Driver.

AnsiEscapeSequence: Describes an Ansi escape sequence. This is a 'blueprint'. If you want to send the sequence you should instead use AnsiEscapeSequenceRequest

AnsiEscapeSequenceRequest: Describes an ongoing ANSI request sent to the console. Use ResponseReceived to handle the response when console answers the request.

AnsiEventRecord: ANSI sequence event record (for ANSI driver testing).

AnsiInput: Pure ANSI Driver with VT Input Mode on Windows and termios raw mode on Unix/Mac.

AnsiInputProcessor

Input processor for AnsiInput, processes a char stream using pure ANSI escape sequence handling.

ANSI Driver Architecture:

This processor integrates with Terminal.Gui's ANSI infrastructure:

Terminal.Gui.Drivers.AnsiResponseParser<TInputRecord> - Automatically parses ANSI escape sequences from the input stream, extracting keyboard events, mouse events, and terminal responses.
AnsiRequestScheduler - Manages outgoing ANSI requests (via QueueAnsiRequest(AnsiEscapeSequenceRequest)) and matches responses from the parser.
Terminal.Gui.Drivers.AnsiKeyConverter - Converts character input to Key events, shared with UnixDriver for consistent ANSI-based key mapping.
AnsiKeyboardEncoder and AnsiMouseEncoder - Convert Key and Mouse events into ANSI sequences for test injection.

The parser is configured in the base class InputProcessorImpl<TInputRecord> with HandleMouse = true and HandleKeyboard = true, enabling automatic event raising.

AnsiKeyboardEncoder: Encodes Key objects into ANSI escape sequences.

AnsiKeyboardParser: Parses ANSI escape sequence strings that describe keyboard activity into Key.

AnsiKeyboardParserPattern: Base class for ANSI keyboard parsing patterns.

AnsiMouseEncoder: Encodes Mouse events into ANSI SGR (1006) extended mouse format escape sequences.

AnsiMouseParser: Parses ANSI mouse escape sequences into Mouse including support for button press/release, mouse wheel, and motion events.

AnsiOutput

Pure ANSI console output.

ANSI Output Architecture:

Pure ANSI - All output operations use ANSI escape sequences via EscSeqUtils, making it portable across ANSI-compatible terminals (Unix, Windows Terminal, ConEmu, etc.).
Buffer Capture - GetLastBuffer() provides access to the last written IOutputBuffer for test verification, independent of actual console output.
Graceful Degradation - Detects if console is unavailable or redirected, silently operating in buffer-only mode for CI/headless environments.
Size Management - Uses SetSize(int, int) for controlling terminal dimensions in tests. In real terminals, size would be queried via ANSI requests (see CSI_ReportWindowSizeInChars) or platform APIs.

Color Support: Supports both 16-color (via Force16Colors) and true-color (24-bit RGB) output through ANSI SGR sequences.

AnsiRequestScheduler: Manages AnsiEscapeSequenceRequest made to an IAnsiResponseParser. Ensures there are not 2+ outstanding requests with the same terminator, throttles request sends to prevent console becoming unresponsive and handles evicting ignored requests (no reply from terminal).

ComponentFactoryImpl<TInputRecord>: Abstract base class implementation of IComponentFactory<TInputRecord> that provides a default implementation of CreateSizeMonitor(IOutput, IOutputBuffer).

ConsoleInputSource: Console input source - reads from actual console (production). Abstract base class for platform-specific implementations.

ConsoleKeyInfoExtensions: Extension methods for ConsoleKeyInfo.

ConsoleKeyMapping: Helper class to handle mapping between KeyCode and ConsoleKeyInfo.

CsiCursorPattern: Detects ansi escape sequences in strings that have been read from the terminal (see IAnsiResponseParser). Handles navigation CSI key parsing such as \x1b[A (Cursor up) and \x1b[1;5A (Cursor/Function with modifier(s))

CsiKeyPattern: Detects ansi escape sequences in strings that have been read from the terminal (see IAnsiResponseParser). Handles CSI key parsing such as \x1b[3;5~ (Delete with Ctrl)

Driver: Holds global driver settings.

DriverRegistry: Central registry of available Terminal.Gui drivers. Provides type-safe driver identification and discovery without reflection.

DriverRegistry.DriverDescriptor: Descriptor for a registered driver containing metadata and factory.

DriverRegistry.Names: Well-known driver names as constants for type safety and avoiding magic strings.

EscSeqReqStatus: Represents the status of an ANSI escape sequence request made to the terminal using EscSeqRequests.

EscSeqRequests: Manages ANSI Escape Sequence requests and responses. The list of EscSeqReqStatus contains the status of the request. Each request is identified by the terminator (e.g. ESC[8t ... t is the terminator).

EscSeqUtils: Provides a platform-independent API for managing ANSI escape sequences.

FakeClipboard: Implements a fake clipboard for testing purposes.

InputEventRecord: Platform-independent input event record base class for the input injection system.

InputImpl<TInputRecord>: Base class for reading console input in perpetual loop. The Peek() and Read() methods are executed on the input thread created by StartInputTaskAsync(IApplication).

InputProcessorImpl<TInputRecord>: Base implementation for processing queued input of type TInputRecord. Translates driver-specific input into Terminal.Gui events and data models on the main loop thread.

KeyboardEventRecord: Keyboard input event record.

MouseEventRecord: Mouse input event record (raw, before click synthesis).

NetComponentFactory: IComponentFactory<TInputRecord> implementation for native csharp console I/O i.e. dotnet. This factory creates instances of internal classes NetInput, NetOutput etc.

NetInput: IInput<TInputRecord> implementation that uses native dotnet methods e.g. Console. The Peek() and Read() methods are executed on the input thread created by StartInputTaskAsync(IApplication).

NetInputProcessor: Input processor for NetInput, deals in ConsoleKeyInfo stream

NetOutput: Implementation of IOutput that uses native dotnet methods e.g. Console

OutputBase: Abstract base class to assist with implementing IOutput.

OutputBufferImpl: Stores the desired output state for the whole application. This is updated during draw operations before being flushed to the console as part of the main loop. operation

Ss3Pattern: Parser for SS3 terminal escape sequences. These describe specific keys e.g. EscOP is F1.

TestInputSource: Test input source - provides pre-programmed input for testing.

UnixComponentFactory: IComponentFactory<TInputRecord> implementation for native unix console I/O. This factory creates instances of internal classes Terminal.Gui.Drivers.UnixInput, Terminal.Gui.Drivers.UnixOutput etc.

WindowsComponentFactory: IComponentFactory<TInputRecord> implementation for win32 only I/O. This factory creates instances of internal classes Terminal.Gui.Drivers.WindowsInput, Terminal.Gui.Drivers.WindowsOutput etc.

WindowsConsole: Definitions for Windows Console API structures and constants.

Structs

WindowsConsole.COLORREF

WindowsConsole.CONSOLE_SCREEN_BUFFER_INFOEX

WindowsConsole.CharInfo

WindowsConsole.CharUnion

WindowsConsole.ConsoleCursorInfo

WindowsConsole.ConsoleKeyInfoEx

WindowsConsole.Coord

WindowsConsole.FocusEventRecord

WindowsConsole.InputRecord

WindowsConsole.KeyEventRecord: Key event record structure.

WindowsConsole.MenuEventRecord

WindowsConsole.MouseEventRecord

WindowsConsole.SmallRect

WindowsConsole.WindowBufferSizeRecord

Interfaces

IAnsiResponseParser: When implemented in a derived class, allows watching an input stream of characters (i.e. console input) for ANSI response sequences (mouse input, cursor, query responses etc.).

IComponentFactory: Base untyped interface for IComponentFactory<TInputRecord> for methods that are not templated on low level console input type.

IComponentFactory<TInputRecord>: Creates driver specific subcomponent classes (IInput<TInputRecord>, IInputProcessor etc) for a IMainLoopCoordinator.

IDriver: Base interface for Terminal.Gui Driver implementations.

IInputProcessor: Processes queued input on the main loop thread, translating driver-specific input into Terminal.Gui events and data models.

IInputSource: Source of input events. Production implementations read from console, test implementations provide pre-programmed input.

IInput<TInputRecord>: Interface for reading console input in a perpetual loop on a dedicated input thread.

IKeyConverter<TInputRecord>: Interface for subcomponent of a InputProcessorImpl<TInputRecord> which can translate the raw console input type T (which typically varies by driver) to the shared Terminal.Gui Key class.

IOutput: The low-level interface drivers implement to provide output capabilities; encapsulates platform-specific output functionality.

IOutputBuffer: Represents the desired screen state for console rendering. This interface provides methods for building up visual content (text, attributes, fills) in a buffer that can be efficiently written to the terminal in a single operation at the end of each iteration. Final output is handled by IOutput.

ISizeMonitor: Interface for classes responsible for reporting the current size of the terminal window.

ITestableInput<TInputRecord>: Marker interface for IInput implementations that support test input injection.

IWindowsInput: Wraps IConsoleInput for Windows console input events (WindowsConsole.InputRecord). Needed to support Mocking in tests.

Enums

AnsiResponseParserState: Describes the current state of an IAnsiResponseParser

CursorVisibility: Terminal Cursor Visibility settings.

EscSeqUtils.ClearScreenOptions: Options for ANSI ESC "[xJ" - Clears part of the screen.

EscSeqUtils.DECSCUSR_Style: Styles for ANSI ESC "[x q" - Set Cursor Style

KeyCode

The KeyCode enumeration encodes key information from IDrivers and provides a consistent way for application code to specify keys and receive key events.

The Key class provides a higher-level abstraction, with helper methods and properties for common operations. For example, IsAlt and IsCtrl provide a convenient way to check whether the Alt or Ctrl modifier keys were pressed when a key was pressed.

VK: Generated from winuser.h. See https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes

WindowsConsole.ButtonState

WindowsConsole.ConsoleModes: Windows Console mode flags.

WindowsConsole.ControlKeyState

WindowsConsole.EventFlags

WindowsConsole.EventType

Table of Contents