Namespace Terminal.Gui.Drivers

Cross-platform terminal abstraction, console drivers, and ANSI handling.

The Drivers namespace provides the platform abstraction layer enabling Terminal.Gui to run consistently across Windows, macOS, and Linux/Unix.

Key Types

IDriver - Main driver interface for terminal operations
DriverRegistry - Registry of available drivers with metadata
AnsiResponseParser - ANSI escape sequence parsing for input
AnsiKeyboardParser / AnsiMouseParser - Keyboard and mouse input parsing
EscSeqUtils - ANSI escape sequence constants and utilities
Cursor / CursorStyle - Terminal cursor management
IOutput / IOutputBuffer - Output surfaces, including raster image dispatch

Available Drivers

Driver	Platform	Description
`windows`	Windows	Native Win32 Console API with highest performance
`unix`	Unix/Linux/macOS	Direct syscalls with ANSI sequences
`dotnet`	All	Cross-platform using `System.Console`
`ansi`	All	Pure ANSI implementation, ideal for testing

Driver Selection

// Automatic (recommended)
app.Init ();  // Selects best driver for platform

// Explicit selection
app.Init (DriverRegistry.Names.ANSI);

// Via configuration
app.ForceDriver = DriverRegistry.Names.UNIX;
app.Init ();

Raster Graphics Capabilities

Drivers expose raster protocol detection through IDriver.KittyGraphicsSupport and IDriver.SixelSupport, plus matching change events. Kitty graphics is the preferred raster protocol when supported. Sixel remains the fallback for terminals that do not support Kitty graphics. IOutput.UseKittyGraphics selects the Kitty output path; when it is false and Sixel is supported, raster commands are emitted as Sixel.

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:

<ul><li>
        <xref href="Terminal.Gui.Drivers.AnsiResponseParser" data-throw-if-not-resolved="false"></xref> - Automatically parses ANSI escape sequences
        from the input stream, extracting keyboard events, mouse events, and terminal responses.
    </li><li>
        <xref href="Terminal.Gui.Drivers.AnsiRequestScheduler" data-throw-if-not-resolved="false"></xref> - Manages outgoing ANSI requests (via
        <xref href="Terminal.Gui.Drivers.IDriver.QueueAnsiRequest(Terminal.Gui.Drivers.AnsiEscapeSequenceRequest)" data-throw-if-not-resolved="false"></xref>)
        and matches responses from the parser.
    </li><li>
        <xref href="Terminal.Gui.Drivers.AnsiKeyConverter" data-throw-if-not-resolved="false"></xref> - Converts character input to <xref href="Terminal.Gui.Input.Key" data-throw-if-not-resolved="false"></xref> events,
        shared with UnixDriver for consistent ANSI-based key mapping.
    </li><li>
        <xref href="Terminal.Gui.Drivers.AnsiKeyboardEncoder" data-throw-if-not-resolved="false"></xref> and <xref href="Terminal.Gui.Drivers.AnsiMouseEncoder" data-throw-if-not-resolved="false"></xref> - Convert
        <xref href="Terminal.Gui.Input.Key" data-throw-if-not-resolved="false"></xref> and <xref href="Terminal.Gui.Input.Mouse" data-throw-if-not-resolved="false"></xref> events into ANSI sequences for test injection.
    </li></ul>

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.

AnsiPlatformExtensions: Extension methods for the AnsiPlatform enum type.

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

AnsiResponseParserStateExtensions: Extension methods for the AnsiResponseParserState enum type.

AnsiStartupGate: Default implementation of IAnsiStartupGate.

AnsiStartupQueryExtensions: Extension methods for the AnsiStartupQuery enum type.

ColorCapabilityLevelExtensions: Extension methods for the ColorCapabilityLevel enum type.

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)

Cursor: Represents a cursor with position in screen coordinates and shape.

CursorStyleExtensions: Extension methods for the CursorStyle enum type.

CursorVisibilityExtensions: Extension methods for the CursorVisibility enum type.

Driver: Holds global driver settings and cross-driver utility methods.

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.

KeyCodeExtensions: Extension methods for the KeyCode enum type.

KeyboardEventRecord: Keyboard input event record.

KittyKeyboardCapabilities: Describes the kitty keyboard protocol capabilities discovered from the terminal.

KittyKeyboardFlagsExtensions: Extension methods for the KittyKeyboardFlags enum type.

KittyKeyboardPattern: Parses kitty keyboard protocol CSI u sequences into the Key model. Extracts event type (press/repeat/release) and maps it to KeyEventType.

KittyKeyboardProtocolDetector: Detects whether the active terminal supports the kitty keyboard protocol.

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

PlatformDetection: Helper class for detecting platform-specific features.

ProgressIndicator: Writes terminal progress sequences for hosts that support OSC 9;4 style progress indicators.

RasterImageCommand: Describes a raster image to compose through the output buffer.

SizeDetectionModeExtensions: Extension methods for the SizeDetectionMode enum type.

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

TerminalColorCapabilities: Describes the color capabilities of the terminal as detected from environment variables.

TerminalColorDetector: Uses OSC 10/11 ANSI escape sequences to query the terminal's actual default foreground and background colors. Follows the same async callback pattern as SixelSupportDetector.

TerminalEnvironmentDetector: Detects terminal color capabilities from environment variables such as TERM, COLORTERM, TERM_PROGRAM, and WT_SESSION.

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

TuiPlatformExtensions: Extension methods for the TuiPlatform enum type.

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, cursor, query responses etc.).

IAnsiStartupGate: Tracks ANSI startup queries that must complete before startup rendering is considered ready.

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

AnsiPlatform: Indicates which platform the driver is targeting.

AnsiResponseParserState: Describes the current state of an IAnsiResponseParser

AnsiStartupQuery: Identifies ANSI startup queries tracked by IAnsiStartupGate.

ColorCapabilityLevel: Describes the color capability level of a terminal.

CursorStyle: Defines the style of the terminal cursor, based on ANSI/VT terminal standards.

CursorVisibility: Windows Specific Terminal Cursor Visibility settings.

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

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.

KittyKeyboardFlags: Kitty keyboard progressive enhancement flags. These correspond to the bit flags defined in the kitty keyboard protocol specification.