# What Is AdaptDispatch in Windows Terminal? Understanding the VT Sequence Adapter

> Discover AdaptDispatch in Windows Terminal, the VT sequence adapter that translates control codes into console rendering actions. Learn how it works!

- Repository: [Microsoft/terminal](https://github.com/microsoft/terminal)
- Tags: internals
- Published: 2026-02-26

---

**AdaptDispatch is the adapter layer that translates Virtual Terminal (VT) control sequences into concrete actions on the Windows Console rendering engine.**

In the `microsoft/terminal` repository, `AdaptDispatch` serves as the critical bridge between the terminal's VT parser and its underlying console implementation. This class implements the `ITermDispatch` interface to convert parsed escape sequences—such as cursor movements, color changes, and screen erasures—into direct manipulations of the terminal state.

## The Architectural Role of AdaptDispatch

`AdaptDispatch` sits at the intersection of parsing and rendering, ensuring that the VT parser remains decoupled from the console's internal mechanics. By implementing the `ITermDispatch` interface defined in [`src/terminal/parser/termDispatch.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/termDispatch.hpp), it provides a concrete execution layer for the abstract commands generated by the parser.

This separation allows the same VT parser to be reused across different contexts, including unit tests, the ConHost backend, and alternative rendering pipelines. The adapter pattern employed here ensures that changes to the console's rendering engine do not require modifications to the parser logic.

## Core Dependencies and Internal State

The `AdaptDispatch` class maintains references to the essential subsystems it controls. As defined in [`src/terminal/adapter/adaptDispatch.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/adaptDispatch.hpp) (lines 108–124), the private members include:

```cpp
ITerminalApi& _api;          // Low-level console API for writing and mode setting
Renderer* _renderer;         // Rendering back-end for visual output
RenderSettings& _renderSettings;
TerminalInput& _terminalInput;
PageManager _pages;          // Manages active page (main/alt buffer)

```

These references enable `AdaptDispatch` to execute VT commands by delegating to the appropriate subsystem. The class also tracks terminal mode flags—such as **INSERT/REPLACE**, **ORIGIN**, and **RECTANGULAR-CHANGE-EXTENT**—through an internal `enum class Mode`, exposing state management via `SetMode`, `ResetMode`, and `RequestMode` methods.

## Translating VT Sequences to Console Actions

### Cursor Movement and Positioning

When the parser receives a Cursor Up (CUU) sequence like `\x1b[5A`, `AdaptDispatch::CursorUp` processes the request. The implementation in [`src/terminal/adapter/adaptDispatch.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/adaptDispatch.cpp) (lines 1008–1010) forwards to `_CursorMovePosition`, which handles margin constraints, origin mode compliance, and coordinate clamping:

```cpp
// Direct call equivalent to receiving CSI "\x1b[5A"
adapter->CursorUp(5);   // Moves cursor 5 rows up, respecting scroll margins

```

### Graphics Rendition (SGR)

The **Select Graphic Rendition** command updates text attributes through `SetGraphicsRendition`. Located in [`src/terminal/adapter/adaptDispatch.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/adaptDispatch.cpp) (lines 722–748), this method parses VT parameters and applies them via `_ApplyGraphicsOptions`:

```cpp
VTParameters sgr = { 1, 34 };   // Bold + blue foreground
adapter->SetGraphicsRendition(sgr);

```

### Display Erasure Operations

For erasing display regions, `EraseInDisplay` handles the ED sequences. The implementation (lines 3030–3078) resets the delayed-wrap flag, determines the erase region based on the `EraseType` parameter, and fills the area with spaces using the current erase attributes:

```cpp
adapter->EraseInDisplay(DispatchTypes::EraseType::ToEnd);

```

## Instantiation and Integration

In production code, `AdaptDispatch` is instantiated during terminal initialization and wired to the VT parser:

```cpp
// Pattern used in terminal startup
auto dispatch = std::make_unique<AdaptDispatch>(
    api,           // ITerminalApi implementation
    renderer,      // Renderer instance
    renderSettings,// Render settings reference
    terminalInput  // Terminal input handler
);

parser.SetDispatch(dispatch.get());   // Parser now routes to AdaptDispatch

```

This wiring allows the parser to remain agnostic of the specific console implementation while `AdaptDispatch` handles the translation to Windows-specific APIs.

## Unit Testing and Isolation

The adapter architecture enables comprehensive unit testing without requiring a full UI context. The test harness in [`src/terminal/adapter/ut_adapter/adapterTest.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/ut_adapter/adapterTest.cpp) (lines 417–447) creates `AdaptDispatch` instances with mock implementations of the dependency interfaces:

```cpp
// From adapterTest.cpp
auto adapter = std::make_unique<AdaptDispatch>(
    *_testGetSet,    // Mock ITerminalApi
    &renderer,       // Test renderer
    renderSettings,  // Test settings
    _terminalInput   // Test input handler
);

```

This approach allows developers to verify individual VT command behaviors—such as verifying that `CursorUp` respects scroll margins or that `SetGraphicsRendition` correctly updates color attributes—in isolation from the rendering pipeline.

## Summary

*   **AdaptDispatch** implements the `ITermDispatch` interface to bridge the VT parser and console implementation in `microsoft/terminal`.
*   The class translates escape sequences into concrete operations on cursor position, text attributes, and screen buffers.
*   It maintains state for terminal modes (INSERT, ORIGIN, etc.) and delegates rendering to the `Renderer` and `ITerminalApi` subsystems.
*   Located in [`src/terminal/adapter/adaptDispatch.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/adaptDispatch.hpp) and [`src/terminal/adapter/adaptDispatch.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/adaptDispatch.cpp), it encapsulates all VT-specific logic separately from the parser.
*   The adapter pattern enables extensive unit testing through mock dependencies in [`src/terminal/adapter/ut_adapter/adapterTest.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/ut_adapter/adapterTest.cpp).

## Frequently Asked Questions

### What interface does AdaptDispatch implement?

`AdaptDispatch` implements the `ITermDispatch` interface defined in [`src/terminal/parser/termDispatch.hpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/parser/termDispatch.hpp). This interface defines the contract that the VT parser uses to report terminal actions, allowing `AdaptDispatch` to provide the concrete Windows Console implementation for each virtual terminal command.

### How does AdaptDispatch handle cursor movement?

The class processes cursor movement through methods like `CursorUp` and `CursorDown`, which internally call `_CursorMovePosition` to apply margin constraints and origin mode settings. According to the source in [`src/terminal/adapter/adaptDispatch.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/adaptDispatch.cpp) (lines 1008–1010), these methods ensure that cursor coordinates remain within valid screen boundaries while respecting the terminal's current mode flags.

### Why is AdaptDispatch essential for testing?

`AdaptDispatch` enables unit testing by accepting mock implementations of its dependencies (`ITerminalApi`, `Renderer`, etc.). As demonstrated in [`src/terminal/adapter/ut_adapter/adapterTest.cpp`](https://github.com/microsoft/terminal/blob/main/src/terminal/adapter/ut_adapter/adapterTest.cpp) (lines 417–447), developers can instantiate the adapter with test doubles to verify VT command behavior without launching the full terminal UI or rendering pipeline.

### Where is AdaptDispatch instantiated in the Windows Terminal codebase?

The class is instantiated during terminal initialization, typically within the terminal creation logic. The standard pattern involves creating a `std::unique_ptr<AdaptDispatch>` with references to the live `ITerminalApi`, `Renderer`, `RenderSettings`, and `TerminalInput` instances, then registering it with the VT parser via `SetDispatch()` to begin processing escape sequences.