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).
- ComponentFactory<T>
Abstract base class implementation of IComponentFactory<T>
- ConsoleDriver
Base class for Terminal.Gui IConsoleDriver implementations.
- ConsoleInput<T>
Base class for reading console input in perpetual loop
- ConsoleKeyMapping
Helper class to handle the scan code and virtual key from a ConsoleKey.
- 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<T> implementation for fake/mock console I/O used in unit tests. This factory creates instances that simulate console behavior without requiring a real terminal.
- FakeConsoleInput
Fake console input for testing that can return predefined input or wait indefinitely.
- FakeConsoleOutput
Fake console output for testing that captures what would be written to the console.
- FakeDriver
Implements a mock IConsoleDriver for unit testing
- InputProcessor<T>
Processes the queued input buffer contents - which must be of Type
T. Is responsible for ProcessQueue() and translating into common Terminal.Gui events and data models.
- NetComponentFactory
IComponentFactory<T> implementation for native csharp console I/O i.e. dotnet. This factory creates instances of internal classes NetInput, NetOutput etc.
- NetInputProcessor
Input processor for NetInput, deals in ConsoleKeyInfo stream
- NetOutput
Implementation of IConsoleOutput that uses native dotnet methods e.g. Console
- OutputBase
Abstract base class to assist with implementing IConsoleOutput.
- OutputBuffer
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<T> 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<T> 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<T> for methods that are not templated on low level console input type.
- IComponentFactory<T>
Creates driver specific subcomponent classes (IConsoleInput<T>, IInputProcessor etc) for a IMainLoopCoordinator.
- IConsoleDriver
Base interface for Terminal.Gui ConsoleDriver implementations.
- IConsoleDriverFacade
Interface for v2 driver abstraction layer
- IConsoleInput<T>
Interface for reading console input indefinitely - i.e. in an infinite loop. The class is responsible only for reading and storing the input in a thread safe input buffer which is then processed downstream e.g. on main UI thread.
- IConsoleOutput
Interface for writing console output
- IConsoleSizeMonitor
Interface for classes responsible for reporting the current size of the terminal window.
- IInputProcessor
Interface for main loop class that will process the queued input buffer contents. Is responsible for ProcessQueue() and translating into common Terminal.Gui events and data models.
- IKeyConverter<T>
Interface for subcomponent of a InputProcessor<T> which can translate the raw console input type T (which typically varies by driver) to the shared Terminal.Gui Key class.
- IOutputBuffer
Describes the screen state that you want the console to be in. Is designed to be drawn to repeatedly then manifest into the console once at the end of iteration after all drawing is finalized.
- IWindowsInput
Interface for windows only input which uses low level win32 apis
Enums
- AnsiResponseParserState
Describes the current state of an IAnsiResponseParser
- ConsoleKeyMapping.VK
Generated from winuser.h. See https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes
- 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 IConsoleDrivers 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.
- WindowsConsole.ConsoleModes
Windows Console mode flags.