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

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 ();

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

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

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

PlatformDetection: Helper class for detecting platform-specific features.

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

AnsiPlatform: Indicates which platform the driver is targeting.

AnsiResponseParserState: Describes the current state of an IAnsiResponseParser

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.

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