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 IConsoleDriverandIConsoleDriverFacade - 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 .NETSystem.ConsoleAPI. 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
- 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.
- AnsiKeyboardParser
Parses ANSI escape sequence strings that describe keyboard activity into Key.
- AnsiKeyboardParserPattern
Base class for ANSI keyboard parsing patterns.
- AnsiMouseParser
Parses mouse ansi escape sequences into MouseEventArgs including support for pressed, released and mouse wheel.
- 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).
- 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)
- 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.
- FakeComponentFactory
IComponentFactory<TInputRecord> implementation for fake/mock console I/O used in unit tests. This factory creates instances that simulate console behavior without requiring a real terminal.
- FakeInput
IInput<TInputRecord> implementation that uses a fake input source for testing. The Peek() and Read() methods are executed on the input thread created by StartInputTaskAsync(IApplication).
- FakeInputProcessor
Input processor for FakeInput, deals in ConsoleKeyInfo stream
- FakeOutput
Fake console output for testing that captures what would be written to the console.
- 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>
Processes the queued input queue contents - which must be of Type
TInputRecord. Is responsible for ProcessQueue() and translating into common Terminal.Gui events and data models. Runs on the main loop thread.
- 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
- 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.
EscOPis F1.
- 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.KeyEventRecord
Key event record structure.
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
Interface for main loop class that will process the queued input. Is responsible for ProcessQueue() and translating into common Terminal.Gui events and data models.
- 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.ConsoleModes
Windows Console mode flags.