Terminal.Gui

https://gui-cs.github.io/Terminal.Gui/docs/
Admin
Terminal.Gui is a .NET framework for building modern terminal user interfaces with cross-platform...
Tokens:122,835
Snippets:1,564
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Enable and Load Configuration Simultaneously

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Use this method to enable the ConfigurationManager and load settings from all configured locations in a single step. This is the simplest way to get started with configuration.

```csharp
ConfigurationManager.Enable(ConfigLocations.All);

```

--------------------------------

### Install Terminal.Gui Templates

Source: https://gui-cs.github.io/Terminal.Gui/docs/getting-started.html

Installs the Terminal.Gui.Templates package from NuGet.

```bash
dotnet new install Terminal.Gui.Templates@2.0.*
```

--------------------------------

### Install Terminal.Gui Templates and Create a New Project

Source: https://gui-cs.github.io/Terminal.Gui/docs/getting-started.html

Installs the Terminal.Gui templates, creates a new simple TUI project, navigates into the project directory, and runs the application.

```bash
dotnet new install Terminal.Gui.Templates@2.0.*
dotnet new tui-simple -n myproj
cd myproj
dotnet run
```

--------------------------------

### Initialize Terminal.Gui in Inline Mode

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Quick start example to initialize Terminal.Gui in inline mode. The RunnableWrapper provides automatic sizing for the view.

```csharp
using IApplication app = Application.Create ();
app.AppModel = AppModel.Inline;
app.Init ();

// RunnableWrapper provides the inline container with Dim.Auto sizing
RunnableWrapper<ColorPicker> wrapper = new () { Width = Dim.Fill () };
app.Run (wrapper);

```

--------------------------------

### Theme Inheritance Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Demonstrates applying a custom theme after setting a default theme, showing how properties are overridden.

```javascript
// Start with default theme
ThemeManager.Theme = "Default";
ConfigurationManager.Apply();

// Apply custom theme (overrides only what's specified)
ThemeManager.Theme = "MyCustomTheme";
ConfigurationManager.Apply();
```

--------------------------------

### Install and Monitor with dotnet-counters

Source: https://gui-cs.github.io/Terminal.Gui/docs/logging.html

Install the dotnet-counters global tool and use it to monitor Terminal.Gui metrics for your process. High Redraws values may indicate performance issues.

```bash
dotnet tool install dotnet-counters --global
dotnet-counters monitor -n YourProcessName --counters Terminal.Gui
```

--------------------------------

### Pos and Dim Examples for Layout

Source: https://gui-cs.github.io/Terminal.Gui/docs/layout.html

Demonstrates combining Pos and Dim values for responsive layout, including offsets and relative positioning/sizing.

```csharp
view.X = Pos.Center () - 10;
view.Y = Pos.Percent (20);

anotherView.X = Pos.AnchorEnd (10);
anotherView.Width = 9;

myView.X = Pos.X (view);
myView.Y = Pos.Bottom (anotherView) + 5;
```

```csharp
view.Width = Dim.Fill () - 10;

view.Height = Dim.Percent (20) - 1;

anotherView.Height = Dim.Height (view) + 1;
```

--------------------------------

### Example Application Settings JSON

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

This JSON object demonstrates system-wide settings from SettingsScope, including default key bindings, color depth, and mouse settings.

```json
{
  "Application.DefaultKeyBindings.Quit": "Esc",
  "Driver.Force16Colors": false,
  "Application.IsMouseDisabled": false,
  "Application.DefaultKeyBindings.Arrange": "Ctrl+F5",
  "Application.DefaultKeyBindings.NextTabStop": "Tab",
  "Application.DefaultKeyBindings.PreviousTabStop": "Shift+Tab",
  "Application.DefaultKeyBindings.NextTabGroup": "F6",
  "Application.DefaultKeyBindings.PreviousTabGroup": "Shift+F6",
  "Key.Separator": "+"
}
```

--------------------------------

### Using the Fluent API to Run a ColorPickerDialog

Source: https://gui-cs.github.io/Terminal.Gui/docs/newinv2.html

Illustrates the concise and readable fluent API for running a runnable view and retrieving its typed result. This example shows how to initialize the application, run a ColorPickerDialog, and get the result as a nullable Color.

```csharp
// Concise and readable
using (IApplication app = Application.Create ().Init ()) 
{
    app.Run<ColorPickerDialog> ();
    Color? result = app.GetResult<Color> ();
}
```

--------------------------------

### Get and Add Schemes

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Demonstrates how to retrieve all schemes for the current theme, get a specific scheme by enum, list scheme names, and add a custom scheme programmatically.

```csharp
Dictionary<string, Scheme?> schemes = SchemeManager.GetSchemesForCurrentTheme();

Scheme dialogScheme = SchemeManager.GetScheme(Schemes.Dialog);

ImmutableList<string> schemeNames = SchemeManager.GetSchemeNames();

SchemeManager.AddScheme("MyScheme", new Scheme
{
    Normal = new Attribute(Color.White, Color.Blue),
    Focus = new Attribute(Color.Black, Color.Cyan)
});
```

--------------------------------

### Tiled Layout Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/arrangement.html

Demonstrates setting up a Tiled layout where SubViews do not overlap. Views use Pos and Dim for relative positioning.

```csharp
var container = new View { Arrangement = ViewArrangement.Fixed };

var view1 = new View { X = 0, Y = 0, Width = 20, Height = 10 };
var view2 = new View { X = 21, Y = 0, Width = 20, Height = 10 };

container.Add(view1, view2);
// Views are side-by-side, non-overlapping
__
```

--------------------------------

### Command Execution Example: Activate

Source: https://gui-cs.github.io/Terminal.Gui/docs/mouse.html

Demonstrates the execution flow for the `Command.Activate` action, which can be triggered by mouse bindings. It includes pre-execution checks and event notifications.

```csharp
InvokeCommand(Command.Activate, context):
    OnActivating(args) || args.Cancel  // Subclass override
    Activating?.Invoke(this, args)     // Event subscribers
    if (!args.Cancel && CanFocus) SetFocus();
__
```

--------------------------------

### Add Serilog Packages

Source: https://gui-cs.github.io/Terminal.Gui/docs/logging.html

Install the necessary Serilog packages using the .NET CLI to enable file logging.

```bash
dotnet add package Serilog
dotnet add package Serilog.Sinks.File
dotnet add package Serilog.Extensions.Logging 

```

--------------------------------

### Example Key Binding Settings JSON

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

This JSON illustrates configurable key bindings using the PlatformKeyBinding format, supporting platform-aware defaults for application and view commands.

```json
{
  "Application.DefaultKeyBindings": {
    "Quit": { "All": ["Esc"] },
    "Suspend": { "Linux": ["Ctrl+Z"], "Macos": ["Ctrl+Z"] },
    "Arrange": { "All": ["Ctrl+F5"] }
  },
  "View.DefaultKeyBindings": {
    "Copy": { "All": ["Ctrl+C"] },
    "Undo": { "All": ["Ctrl+Z"], "Linux": ["Ctrl+/"], "Macos": ["Ctrl+/ "] }
  },
  "View.ViewKeyBindings": {
    "TextField": {
      "CutToEndOfLine": { "All": ["Ctrl+K"] }
    }
  }
}
```

--------------------------------

### Enable ConfigurationManager at Application Start

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Shows how to enable the ConfigurationManager early in the Main method before application initialization. This ensures configuration is loaded before the UI is created.

```csharp
static void Main()
{
    ConfigurationManager.Enable(ConfigLocations.All);
    using IApplication app = Application.Create();
    app.Init();
    // ...
}
```

--------------------------------

### Container Navigation Setup

Source: https://gui-cs.github.io/Terminal.Gui/docs/navigation.html

Create side-by-side panels with titles and tab group behavior. Define their positions and widths using percentage and fill dimensions.

```csharp
var leftPanel = new FrameView() 
{
    Title = "Options",
    TabStop = TabBehavior.TabGroup,
    X = 0, 
    Width = Dim.Percent(50)
};

var rightPanel = new FrameView() 
{
    Title = "Preview",
    TabStop = TabBehavior.TabGroup,
    X = Pos.Right(leftPanel), 
    Width = Dim.Fill()
};

// F6 navigates between panels, Tab navigates within panels
__
```

--------------------------------

### Dialog Navigation Setup

Source: https://gui-cs.github.io/Terminal.Gui/docs/navigation.html

Configure a dialog with a title, focusability, and tab behavior. Add buttons and define their behavior for navigation and activation.

```csharp
var dialog = new Dialog()
{
    Title = "Settings",
    CanFocus = true,
    TabStop = TabBehavior.TabGroup
};

var okButton = new Button() { Text = "OK", IsDefault = true };
var cancelButton = new Button() { Text = "Cancel" };

// Tab navigates between buttons, Enter activates default
dialog.Add(okButton, cancelButton);
__
```

--------------------------------

### Movable and Resizable Window Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/arrangement.html

Creates a movable and resizable window with a title and centered label. This snippet requires initializing the application and running it with the window.

```csharp
using Terminal.Gui;

using IApplication app = Application.Create();
app.Init();

Window window = new ()
{
    Title = "Drag and Resize Me! (Ctrl+F5 for keyboard mode)",
    X = Pos.Center(),
    Y = Pos.Center(),
    Width = 50,
    Height = 15,
    Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable,
    BorderStyle = LineStyle.Double
};

Label label = new ()
{
    Text = "Try dragging the border with mouse\nor press Ctrl+F5!",
    X = Pos.Center(),
    Y = Pos.Center()
};
window.Add(label);

app.Run(window);
window.Dispose();
```

--------------------------------

### Custom Input Source for File Replay

Source: https://gui-cs.github.io/Terminal.Gui/docs/input-injection.html

Implement a custom input source by inheriting from IInputSource. This example replays recorded input from a file.

```csharp
// Custom input source for file replay
public class FileInputSource : IInputSource
{
    private readonly Queue<InputRecord> _recordedInput;
    
    public FileInputSource(string recordingFile, ITimeProvider timeProvider)
    {
        TimeProvider = timeProvider;
        _recordedInput = LoadRecording(recordingFile);
    }
    
    public IEnumerable<InputRecord> ReadAvailable()
    {
        while (_recordedInput.Count > 0)
        {
            yield return _recordedInput.Dequeue();
        }
    }
}
```

--------------------------------

### Two-Phase Command Pattern Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/command.html

Illustrates the two-phase command pattern: a pre-event (Activating) that is cancellable, followed by a post-event (Activated) after the action is completed.

```text
User presses Space on CheckBox
  → Activating fires (cancellable)
  → CheckBox toggles its state
  → Activated fires (state already changed, ctx.Value available)

```

--------------------------------

### Accessing Driver Registry Information

Source: https://gui-cs.github.io/Terminal.Gui/docs/drivers.html

Demonstrates how to access well-known driver name constants, retrieve driver descriptors, and get supported or default drivers.

```csharp
// Access well-known driver name constants
string windowsDriver = DriverRegistry.Names.WINDOWS;  // "windows"
string dotnetDriver = DriverRegistry.Names.DOTNET;    // "dotnet"
string ansiDriver = DriverRegistry.Names.ANSI;        // "ansi"

// Get detailed driver information
if (DriverRegistry.TryGetDriver(DriverRegistry.Names.WINDOWS, out DriverRegistry.DriverDescriptor descriptor))
{
    Logging.Information($"Found: {descriptor.DisplayName}");
    Logging.Information($"Description: {descriptor.Description}");
    
    // Check if supported on current platform
    bool isSupported = descriptor.SupportedPlatforms.Contains(Environment.OSVersion.Platform);
}

// Get drivers supported on current platform
foreach (DriverRegistry.DriverDescriptor driver in DriverRegistry.GetSupportedDrivers())
{
    Logging.Information($"{driver.Name} - {driver.DisplayName}");
}

// Get the default driver for current platform
DriverRegistry.DriverDescriptor defaultDriver = DriverRegistry.GetDefaultDriver();
Logging.Information($"Default driver: {defaultDriver.Name}");

```

--------------------------------

### Create and Run Application Instance

Source: https://gui-cs.github.io/Terminal.Gui/docs/newinv2.html

Demonstrates the recommended way to create, initialize, and run an application instance, followed by manual disposal. Also shows usage with a 'using' statement for automatic disposal.

```csharp
IApplication app = Application.Create ().Init ();
Window window = new () { Title = "My App" };
app.Run (window);
window.Dispose ();
app.Dispose ();

// With using statement for automatic disposal
using (IApplication app = Application.Create ().Init ())
{
    Window window = new () { Title = "My App" };
    app.Run (window);
    window.Dispose ();
} // app.Dispose() called automatically
```

--------------------------------

### Instance-Based Application Initialization and Running

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Demonstrates recommended instance-based application patterns using `using` statements for automatic disposal and the fluent API for initialization and running views. Also shows an alternative with manual disposal and the older, obsolete static pattern.

```csharp
// RECOMMENDED (v2 - instance-based with using statement):
using (IApplication app = Application.Create ().Init ()) {
    Window top = new ();
    top.Add (myView);
    app.Run (top);
    top.Dispose ();
} // app.Dispose() called automatically

// WITH IRunnable (fluent API with automatic disposal):
using (IApplication app = Application.Create ().Init ()) {
    app.Run<ColorPickerDialog> ();
    Color? result = app.GetResult<Color> ();
}

// ALTERNATIVE (manual disposal):
IApplication app = Application.Create ().Init ();
app.Run<ColorPickerDialog> ();
Color? result = app.GetResult<Color> ();
app.Dispose ();

// OLD (v1 / early v2 - obsolete, avoid in new code):
Application.Init ();
Window top = new ();
top.Add (myView);
Application.Run (top);
top.Dispose ();
Application.Shutdown (); // Obsolete - use Dispose() instead
```

--------------------------------

### Driver Creation Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/drivers.html

Illustrates the internal driver creation process using the Driver Registry. It shows how a driver descriptor is retrieved and used to create a component factory, which then instantiates driver components.

```csharp
DriverRegistry.DriverDescriptor descriptor;

if (DriverRegistry.TryGetDriver(driverName, out descriptor))
{
    // Create factory using descriptor's factory function
    IComponentFactory factory = descriptor.CreateFactory();
    
    // Factory creates all driver components
    MainLoopCoordinator<TInputRecord> coordinator = new (
        timedEvents,
        inputQueue,
        mainLoop,
        factory  // Factory knows its driver name via GetDriverName()
    );
}
```

--------------------------------

### Dim.Fill inside Dim.Auto SuperView (Incorrect)

Source: https://gui-cs.github.io/Terminal.Gui/docs/dimauto.html

A SubView using Dim.Fill() inside a DimAuto-sized SuperView will default to 0 width due to circular dependency. This example shows the incorrect setup.

```csharp
// WRONG — SubView will be 0 wide because SuperView has no content-based size to fill against
View superView = new () { Width = Dim.Auto (DimAutoStyle.Content) };
View subView = new () { Width = Dim.Fill () }; // Gets 0!
superView.Add (subView);

```

--------------------------------

### Create and Run a Wizard

Source: https://gui-cs.github.io/Terminal.Gui/docs/View.html

Construct a multi-step wizard by creating `WizardStep` instances, adding content to each step, and then running the wizard. The `Application.Run` method will block until the wizard is completed.

```csharp
Wizard wizard = new () { Title = "Setup Wizard" };

WizardStep step1 = new () { Title = "Welcome" };
step1.Add (new Label { Text = "Welcome to the wizard!", X = 1, Y = 1 });

WizardStep step2 = new () { Title = "Configuration" };
step2.Add (new TextField { X = 1, Y = 1, Width = 30 });

wizard.AddStep (step1);
wizard.AddStep (step2);

Application.Run (wizard);
```

--------------------------------

### AnsiMouseParser Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/ansihandling.html

Example of SGR (1006) extended mouse format for button presses and releases.

```text
ESC[<button;x;y{M|m}
```

--------------------------------

### Escape-as-Alt Pattern Examples

Source: https://gui-cs.github.io/Terminal.Gui/docs/ansihandling.html

Examples demonstrating the Escape-as-Alt pattern, where ESC followed by a character is interpreted as Alt+character.

```text
ESC a
```

```text
ESC G
```

```text
ESC ^A
```

--------------------------------

### CSI Cursor Pattern Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/ansihandling.html

Example of a CSI cursor pattern for arrow keys and navigation with modifiers.

```text
ESC[1;5A
```

--------------------------------

### Basic MenuBar Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/menus.html

Illustrates the creation of a simple MenuBar with File and Edit menus, including basic menu items and separators. Requires Terminal.Gui namespace and application initialization/shutdown.

```csharp
using Terminal.Gui;

Application.Init ();

Window mainWindow = new () { Title = "Menu Demo" };

MenuBar menuBar = new ([ 
    new MenuBarItem ("_File", [
        new MenuItem ("_New", "", () => MessageBox.Query ("New", "Create new file?", "OK", "Cancel")),
        new MenuItem ("_Open...", "", () => MessageBox.Query ("Open", "Open file dialog", "OK")),
        new Line (),
        new MenuItem ("E_xit", Application.GetDefaultKey (Command.Quit), () => Application.RequestStop ())
    ]),
    new MenuBarItem ("_Edit", [
        new MenuItem ("_Undo", Key.Z.WithCtrl, () => { }),
        new Line (),
        new MenuItem ("Cu_t", Key.X.WithCtrl, () => { }),
        new MenuItem ("_Copy", Key.C.WithCtrl, () => { }),
        new MenuItem ("_Paste", Key.V.WithCtrl, () => { })
    ])
]);

mainWindow.Add (menuBar);

Application.Run (mainWindow);
Application.Shutdown ();
```

--------------------------------

### Quick Test Example for Keyboard Events

Source: https://gui-cs.github.io/Terminal.Gui/docs/keyboard.html

Demonstrates subscribing to key down events and injecting simple keys like 'A', 'Enter', and 'Esc'. Uses virtual time for deterministic testing.

```csharp
// Create application with virtual time for deterministic testing
VirtualTimeProvider time = new();
using IApplication app = Application.Create(time);
app.Init(DriverRegistry.Names.ANSI);

// Subscribe to key events
app.Keyboard.KeyDown += (s, e) => Console.WriteLine($"Key: {e}");

// Inject keys
app.InjectKey(Key.A);
app.InjectKey(Key.Enter);
app.InjectKey(Key.Esc);
__
```

--------------------------------

### CSI Key Pattern Examples

Source: https://gui-cs.github.io/Terminal.Gui/docs/ansihandling.html

Examples of CSI key patterns for function and editing keys with optional modifiers.

```text
ESC[1~
```

```text
ESC[2~
```

```text
ESC[3~
```

```text
ESC[4~
```

```text
ESC[5~
```

```text
ESC[6~
```

```text
ESC[15~
```

```text
ESC[17~
```

```text
ESC[23~
```

```text
ESC[3;5~
```

--------------------------------

### Serilog File Logger Output Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/logging.html

Example output from a Serilog file logger configured for Terminal.Gui, showing timestamp, log level, and message.

```text
2025-02-15 13:36:48.635 +00:00 [INF] Main Loop Coordinator booting...
2025-02-15 13:36:48.663 +00:00 [INF] Creating NetOutput
2025-02-15 13:36:48.668 +00:00 [INF] Creating NetInput
2025-02-15 13:36:49.145 +00:00 [INF] Run 'MainWindow(){X=0,Y=0,Width=0,Height=0}'
2025-02-15 13:36:49.167 +00:00 [INF] Console size changes to {Width=120, Height=30}
2025-02-15 13:36:54.151 +00:00 [INF] RequestStop ''
2025-02-15 13:36:54.225 +00:00 [INF] Input loop exited cleanly

```

--------------------------------

### Get Registered Driver Metadata

Source: https://gui-cs.github.io/Terminal.Gui/docs/drivers.html

Iterate through all registered drivers to get detailed metadata for each, including display name, internal name, description, and supported platforms.

```csharp
// Get driver metadata
foreach (DriverRegistry.DriverDescriptor descriptor in Application.GetRegisteredDrivers())
{
    Logging.Information($"{descriptor.DisplayName}");
    Logging.Information($"  Name: {descriptor.Name}");
    Logging.Information($"  Description: {descriptor.Description}");
    Logging.Information($"  Platforms: {string.Join(", ", descriptor.SupportedPlatforms)}");
    Logging.Information("");
}

// Output:
// Windows Console Driver
//   Name: windows
//   Description: Optimized Windows Console API driver with native input handling
//   Platforms: Win32NT, Win32S, Win32Windows
//
// .NET Cross-Platform Driver
//   Name: dotnet
//   Description: Cross-platform driver using System.Console API
//   Platforms: Win32NT, Unix, MacOSX
// ...
```

--------------------------------

### Usage Pattern 1: Pre-Create View

Source: https://gui-cs.github.io/Terminal.Gui/docs/prompt.html

Demonstrates the most common pattern: creating and configuring a view instance before passing it to the `Prompt` method. This allows for detailed pre-configuration of the view's properties.

```csharp
ColorPicker colorPicker = new ()
{
    SelectedColor = Color.Red,
    Style = new () { ShowColorName = true, ShowTextFields = true }
};

Color? result = mainWindow.Prompt<ColorPicker, Color> (
                                                       view: colorPicker,
                                                       resultExtractor: cp => cp.SelectedColor,
                                                       beginInitHandler: prompt => prompt.Title = "Pick Color");
__
```

--------------------------------

### Define and Use Custom Application Settings

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Shows how to define custom application settings using attributes and how they are automatically loaded and applied by ConfigurationManager. Also demonstrates retrieving the hard-coded config as JSON.

```csharp
public class MyApp
{
    [ConfigurationProperty]
    public static string LastOpenedFile { get; set; } = "";
    
    [ConfigurationProperty]
    public static int WindowWidth { get; set; } = 80;
    
    [ConfigurationProperty]
    public static int WindowHeight { get; set; } = 25;
}

// Enable and use
ConfigurationManager.Enable(ConfigLocations.All);

// Settings are automatically loaded and applied
var window = new Window
{
    Width = MyApp.WindowWidth,
    Height = MyApp.WindowHeight
};

// Later, retrieve the hard-coded config as JSON
string json = ConfigurationManager.GetHardCodedConfig();
// Could save to file here
```

--------------------------------

### Terminal.Gui Inline Mode Startup Sequence

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Illustrates the startup sequence for Terminal.Gui in inline mode, highlighting the roles of AnsiOutput, AnsiSizeMonitor, and AnsiStartupGate.

```text
Init()
  ├─ AnsiOutput: skip CSI ?1049h (stay in primary buffer)
  ├─ AnsiSizeMonitor: send ESC[6n (CPR) to discover cursor row
  ├─ AnsiStartupGate: defer first render until CPR + size queries complete
  └─ OutputBufferImpl: cells start clean (IsDirty = false)

Begin(view)  /  first LayoutAndDraw()
  ├─ Layout pass with full terminal size → measure view's desired height
  ├─ If view doesn't fit below cursor → emit newlines to scroll terminal up
  ├─ Set App.Screen = (0, cursorRow, termWidth, viewHeight)
  └─ Reserve vertical space with newlines + CSI {n}A

```

--------------------------------

### ANSI Mouse Input Format Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/mouse.html

This example shows the raw ANSI escape sequences for a single click at column 10, row 5. Coordinates are 1-based in ANSI format. 'M' indicates a press, and 'm' indicates a release.

```text
Press:   ESC[<0;10;5M    (button=0, x=10, y=5, 'M'=press)
Release: ESC[<0;10;5m    (button=0, x=10, y=5, 'm'=release)

```

--------------------------------

### Positive Tab Offset Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/borders.html

Illustrates a tab with a positive TabOffset, showing how the header is shifted to the right.

```text
  ╭───╮
  │Tab│
╭─┴───┴──╮
│content │
╰────────╯
__
```

--------------------------------

### AnsiEscapeSequenceRequest Setup

Source: https://gui-cs.github.io/Terminal.Gui/docs/ansihandling.html

Demonstrates setting up an AnsiEscapeSequenceRequest to wait for a specific terminal response, like cursor position.

```csharp
var request = new AnsiEscapeSequenceRequest
{
    Request = "\x1B[6t",           // Request cursor position
    Terminator = "t",              // Response ends with 't'
    Value = "6",                   // Optional: disambiguate from other 't' responses
    ResponseReceived = response => HandleResponse(response),
    Abandoned = () => HandleTimeout()
};

```

--------------------------------

### Basic Focus Management and Navigation

Source: https://gui-cs.github.io/Terminal.Gui/docs/navigation.html

Demonstrates how to create focusable views and programmatically control focus advancement. Use TabStop.TabStop for elements that should receive focus via Tab key.

```csharp
var button = new Button() { Text = "Click Me", CanFocus = true, TabStop = TabBehavior.TabStop };
var textField = new TextField() { Text = "", CanFocus = true, TabStop = TabBehavior.TabStop };

// Container with group navigation
var frameView = new FrameView() 
{
    Title = "Options",
    CanFocus = true, 
    TabStop = TabBehavior.TabGroup 
};

// Programmatic focus control
button.SetFocus(); // Give focus to specific view
Application.Navigation.AdvanceFocus(NavigationDirection.Forward, TabBehavior.TabStop);
```

--------------------------------

### Overlapped Windows Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/arrangement.html

Demonstrates creating an overlapped desktop arrangement with two movable and resizable windows. The windows overlap each other, and their Z-order is determined by their addition order to the desktop.

```csharp
using IApplication app = Application.Create();
app.Init();

Runnable desktop = new ()
{
    Arrangement = ViewArrangement.Overlapped
};

Window window1 = new ()
{
    Title = "Window 1",
    X = 5,
    Y = 3,
    Width = 40,
    Height = 12,
    Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable | ViewArrangement.Overlapped
};

Window window2 = new ()
{
    Title = "Window 2 (overlaps Window 1)",
    X = 15,
    Y = 8,
    Width = 40,
    Height = 12,
    Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable | ViewArrangement.Overlapped
};

desktop.Add(window1, window2);

app.Run(desktop);
desktop.Dispose();
```

--------------------------------

### Example Platform-Specific Binding

Source: https://gui-cs.github.io/Terminal.Gui/docs/keyboard.html

Illustrates how to bind 'Undo' to Ctrl+Z universally, with an additional binding of Ctrl+/ on Linux and macOS.

```csharp
["Undo"] = Bind.AllPlus ("Ctrl+Z", nonWindows: ["Ctrl+/"]),
```

--------------------------------

### Manage Multiple Applications with Different Drivers

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

This example demonstrates how to run multiple independent Terminal.Gui applications within the same process, each potentially using a different driver. It utilizes the `Application.Create()` method and `using` statements for proper resource management.

```csharp
using Terminal.Gui.Drivers;

// Application 1
using (IApplication app1 = Application.Create ()) 
{
    app1.Init (DriverRegistry.Names.ANSI);
    Window top1 = new () { Title = "App 1" };
    // ... configure and run top1
}

// Application 2 (different driver!)
using (IApplication app2 = Application.Create ()) 
{
    app2.Init (DriverRegistry.Names.ANSI);
    Window top2 = new () { Title = "App 2" };
    // ... configure and run top2
}

// Views in top1 use app1
// Views in top2 use app2

```

--------------------------------

### Get Registered Driver Names

Source: https://gui-cs.github.io/Terminal.Gui/docs/drivers.html

Retrieve a list of all registered driver names. This method is AOT-friendly and does not use reflection.

```csharp
// Get driver names (AOT-friendly, no reflection)
IEnumerable<string> driverNames = Application.GetRegisteredDriverNames();

Logging.Information("Available drivers:");
foreach (string name in driverNames)
{
    Logging.Information($"  - {name}");
}

// Output:
// Available drivers:
//   - dotnet
//   - windows
//   - ansi
```

--------------------------------

### DataTable Example for TableView

Source: https://gui-cs.github.io/Terminal.Gui/docs/tableview.html

Demonstrates how to wrap a System.Data.DataTable in a DataTableSource for use with TableView. Ensure the DataTable is populated before creating the source.

```csharp
DataTable dt = new ();
dt.Columns.Add ("Name");
dt.Columns.Add ("Age", typeof (int));
dt.Rows.Add ("Alice", 30);
dt.Rows.Add ("Bob", 25);

TableView tv = new () { Table = new DataTableSource (dt) };
```

--------------------------------

### Usage Pattern 2: Auto-Create View

Source: https://gui-cs.github.io/Terminal.Gui/docs/prompt.html

Illustrates how the `Prompt` method can automatically create the view instance. Customization is then applied via the `beginInitHandler`, which receives the prompt object to configure its view and properties.

```csharp
DateTime? date = mainWindow.Prompt<DatePicker, DateTime> (
                                                          resultExtractor: dp => dp.Date,
                                                          beginInitHandler: prompt =>
                                                                            {
                                                                                prompt.Title = "Select Date";
                                                                                prompt.GetWrappedView ().Date = DateTime.Now;
                                                                                prompt.GetWrappedView ().Format = "yyyy-MM-dd";
                                                                            });
__
```

--------------------------------

### Application Initialization and Lifecycle

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Methods for initializing and disposing of the application.

```APIDOC
## Application Initialization and Lifecycle

### Description
Methods for initializing and disposing of the application.

### Methods

#### `Init(string? driverName = null)`
Initializes the application, optionally with a specific driver.

- **`driverName`** (string?, Optional) - The name of the driver to use for initialization.
- **Returns**: `IApplication` - The initialized application instance.

#### `Dispose()`
Disposes of the application and releases resources. Implements `IDisposable`.

### Properties

#### `Driver`
Gets the application's driver.

- **Type**: `IDriver?`

#### `Coordinator`
Gets the main loop coordinator.

- **Type**: `IMainLoopCoordinator?`
```

--------------------------------

### Negative Tab Offset Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/borders.html

Illustrates a tab with a negative TabOffset, showing how the header is shifted to the left and partially off-screen.

```text
───╮
Tab│
╭──┴────╮
│content│
╰───────╯
__
```

--------------------------------

### Testing Views with a Real Application Instance

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Shows how to test a view by integrating it with a real `IApplication` instance. This involves initializing the application, adding the view to a window, and asserting that the view's `App` property is correctly set.

```csharp
using Terminal.Gui.Drivers;

[Fact]
public void MyView_WorksWithRealApplication ()
{
    using (IApplication app = Application.Create ()) 
    {
        app.Init (DriverRegistry.Names.ANSI);
        
        MyView view = new ();
        Window top = new ();
        top.Add (view);
        
        SessionToken? token = app.Begin (top);
        
        // View.App automatically set
        Assert.NotNull (view.App);
        Assert.Same (app, view.App);
        
        // Test view behavior
        view.DoSomething ();
        
        if (token is { })
        {
            app.End (token);
        }
    }
}
```

--------------------------------

### AnsiKeyboardEncoder Encoding Examples

Source: https://gui-cs.github.io/Terminal.Gui/docs/ansihandling.html

Illustrates converting Key objects into ANSI escape sequences using AnsiKeyboardEncoder for input injection.

```csharp
AnsiKeyboardEncoder.Encode(Key.CursorUp);
AnsiKeyboardEncoder.Encode(Key.CursorUp.WithCtrl);
AnsiKeyboardEncoder.Encode(Key.A.WithAlt);

```

--------------------------------

### Custom Theme Definition

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Example of defining a custom theme with specific border styles and a new color scheme for the base element.

```json
{
  "Themes": [
    {
      "MyCustomTheme": {
        "Window.DefaultBorderStyle": "Double",
        "Dialog.DefaultShadow": "Opaque",
        "Schemes": [
          {
            "Base": {
              "Normal": {
                "Foreground": "Cyan",
                "Background": "Black",
                "Style": "Bold"
              }
            }
          }
        ]
      }
    }
  ]
}
```

--------------------------------

### Initialize Application with Virtual Time

Source: https://gui-cs.github.io/Terminal.Gui/docs/input-injection.html

Sets up a VirtualTimeProvider to control time advancement in tests, allowing for deterministic and fast execution without relying on real-time delays.

```csharp
// Create virtual time provider
VirtualTimeProvider time = new();

// Set initial time
time.SetTime(new DateTime(2025, 1, 1, 12, 0, 0));

// Advance time by 100ms (instant - no real delay)
time.Advance(TimeSpan.FromMilliseconds(100));

// Current virtual time is now 12:00:00.100
DateTime now = time.Now;  // 2025-01-01 12:00:00.100
__
```

--------------------------------

### Manual Disposal of Caller-Owned Runnable

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Example showing manual disposal required for a runnable instance created and managed by the caller, not the framework.

```csharp
using (IApplication app = Application.Create ().Init ())
{
    MyDialog dialog = new ();
    app.Run (dialog);
    MyResultType? result = dialog.Result;
    dialog.Dispose ();  // Caller must dispose
}
```

--------------------------------

### Set TUI_CONFIG Environment Variable (Linux/macOS)

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Example of setting the TUI_CONFIG environment variable on Linux or macOS to provide configuration settings.

```shell
# Linux/macOS
export TUI_CONFIG='{"Application.DefaultKeyBindings": {"Quit": {"All": ["Ctrl+Q"]}}}'
```

--------------------------------

### Create and Show a PopoverMenu

Source: https://gui-cs.github.io/Terminal.Gui/docs/menus.html

Instantiates a PopoverMenu with menu items, registers it with the application, and then displays it. Ensure Application.Popover is not null before registering.

```csharp
// Create a context menu
PopoverMenu contextMenu = new ([ 
    new MenuItem (targetView, Command.Cut),
    new MenuItem (targetView, Command.Copy),
    new MenuItem (targetView, Command.Paste),
    new Line (),
    new MenuItem (targetView, Command.SelectAll)
]);

// Register with application (required!)
Application.Popover?.Register (contextMenu);

// Show at mouse position
contextMenu.MakeVisible ();

// Or show at specific position
contextMenu.MakeVisible (new Point (10, 5));
```

--------------------------------

### Fully Clipped Tab Example

Source: https://gui-cs.github.io/Terminal.Gui/docs/borders.html

Illustrates a tab that is fully clipped due to a large negative TabOffset, where only the content area is visible.

```text
╭───────╮
│content│
╰───────╯
__
```

--------------------------------

### Global Command Palette Setup

Source: https://gui-cs.github.io/Terminal.Gui/docs/Popovers.html

Configures and registers a global command palette that can be triggered by a keyboard shortcut. This allows users to access commands from anywhere in the application. Ensure `GetAllCommands()` is implemented to provide the list of available commands.

```csharp
PopoverMenu commandPalette = new (GetAllCommands ());
commandPalette.Key = Key.P.WithCtrl; // Ctrl+P to show

Application.Popover?.Register (commandPalette);

// Now Ctrl+P anywhere in the app shows the command palette
```

--------------------------------

### Get Most Focused SubView

Source: https://gui-cs.github.io/Terminal.Gui/docs/navigation.html

Use Application.Navigation.GetFocused() to find the most focused view in the hierarchy. This replaces the v1 pattern of using the MostFocused property.

```csharp
// v2 way to get the most focused view
var focused = Application.Navigation.GetFocused();

// This replaces the v1 pattern:
// var focused = Application.TopRunnable.MostFocused;
```

--------------------------------

### Accessing Keyboard Functionality

Source: https://gui-cs.github.io/Terminal.Gui/docs/keyboard.html

Demonstrates how to add key bindings and raise key down events using the App.Keyboard property. Also shows how to configure default key bindings for commands.

```csharp
App.Keyboard.KeyBindings.Add(Key.F1, Command.HotKey);
App.Keyboard.RaiseKeyDownEvent(Key.Enter);
Application.DefaultKeyBindings[Command.Quit] = Bind.All (Key.Q.WithCtrl);
```

--------------------------------

### Absolute vs. Responsive Layout in Terminal.Gui

Source: https://gui-cs.github.io/Terminal.Gui/docs/layout.html

Illustrates the difference between absolute positioning/sizing and responsive layout using Pos and Dim. `Pos.Right()` and `Dim.Fill()` create responsive elements that adapt to changes.

```csharp
Label absoluteLabel = new () { X = 1, Y = 2, Width = 12, Height = 1, Text = "Absolute" };

Label responsiveLabel = new ()
{
    Text = "Responsive",
    X = Pos.Right (otherView),
    Y = Pos.Center (),
    Width = Dim.Fill (),
    Height = Dim.Percent (50)
};

```

--------------------------------

### Result Extraction in OnIsRunningChanging

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Example of extracting a result (selected color) and optionally preventing a stop action within the OnIsRunningChanging event handler.

```csharp
protected override bool OnIsRunningChanging (bool oldValue, bool newValue)
{
    if (!newValue)  // Stopping
    {
        // Extract result before views are disposed
        Result = _colorPicker.SelectedColor;
        
        // Optionally cancel stop (e.g., unsaved changes)
        if (HasUnsavedChanges ())
        {
            int? response = MessageBox.Query ("Save?", "Save changes?", Strings.btnNo, Strings.btnYes);
            
            if (response is null or 0)
            {
                return true;  // Cancel stop
            }

            if (response == 1)
            {
                Save ();
            }
        }
    }
    
    return base.OnIsRunningChanging (oldValue, newValue);
}
```

--------------------------------

### Singleton Re-initialization (Legacy)

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Demonstrates how the legacy static `Application` singleton can be re-initialized after `Shutdown()` for backward compatibility in older tests. Instance-based applications cannot be reused.

```csharp
// Test 1
Application.Init ();
Application.Shutdown (); // Obsolete but still works for legacy singleton

// Test 2 - singleton resets and can be re-initialized
Application.Init (); // ✅ Works!
Application.Shutdown (); // Obsolete but still works for legacy singleton
```

```csharp
IApplication app = Application.Create ();
app.Init ();
app.Dispose ();

app.Init (); // ❌ Throws ObjectDisposedException
```

--------------------------------

### Inject Key in Direct Mode with Virtual Time

Source: https://gui-cs.github.io/Terminal.Gui/docs/input-injection.html

Illustrates initializing an application with a VirtualTimeProvider and injecting a key press using Direct Mode, bypassing ANSI encoding for faster testing.

```csharp
// Direct mode (default)
VirtualTimeProvider time = new();
using IApplication app = Application.Create(time);
app.Init(DriverRegistry.Names.ANSI);

// Injection goes directly to events
app.InjectKey(Key.Enter);  // Fast, bypasses ANSI encoding
__
```

--------------------------------

### Set TUI_CONFIG Environment Variable (Windows PowerShell)

Source: https://gui-cs.github.io/Terminal.Gui/docs/config.html

Example of setting the TUI_CONFIG environment variable on Windows PowerShell to provide configuration settings.

```powershell
# Windows PowerShell
$env:TUI_CONFIG='{"Application.DefaultKeyBindings": {"Quit": {"All": ["Ctrl+Q"]}}}'
```

--------------------------------

### Manage Application Lifecycle with Using Statement

Source: https://gui-cs.github.io/Terminal.Gui/docs/newinv2.html

Illustrates the recommended approach for managing application resources using a 'using' statement, ensuring proper cleanup of input threads and driver resources.

```csharp
// Recommended: using statement
using (IApplication app = Application.Create ().Init ()) 
{
    app.Run<MyDialog> ();
    MyResult? result = app.GetResult<MyResult> ();
}

// Ensures:
// - Input thread stopped cleanly
// - Driver resources released
// - No thread leaks in tests
```

--------------------------------

### Get a Specific Scheme

Source: https://gui-cs.github.io/Terminal.Gui/docs/drawing.html

Retrieves a predefined scheme by its name. Use this to access and potentially modify scheme attributes for specific UI elements.

```csharp
Scheme dialogScheme = SchemeManager.GetScheme (Schemes.Dialog);

```

--------------------------------

### Inject Key in Pipeline Mode with Virtual Time

Source: https://gui-cs.github.io/Terminal.Gui/docs/input-injection.html

Shows how to use Pipeline Mode with a VirtualTimeProvider to test ANSI encoding and parsing. This example injects the F1 key, verifying the round-trip of encoding and decoding escape sequences.

```csharp
// Pipeline mode for ANSI testing
VirtualTimeProvider time = new();
using IApplication app = Application.Create(time);
app.Init(DriverRegistry.Names.ANSI);

InputInjectionOptions options = new() 
{
    Mode = InputInjectionMode.Pipeline 
};

// This encodes Key.F1 → "\x1b[OP", injects chars, parses back
app.GetInputInjector().InjectKey(Key.F1, options);

// Verify ANSI encoding worked correctly
// (parser should decode "\x1b[OP" back to Key.F1)
__
```

--------------------------------

### Automatic Disposal of Framework-Owned Runnable

Source: https://gui-cs.github.io/Terminal.Gui/docs/application.html

Example demonstrating automatic disposal of a dialog when the 'Run' method returns, as the framework owns the runnable's lifecycle.

```csharp
using (IApplication app = Application.Create ().Init ())
{
    app.Run<MyDialog> (); // Dialog disposed automatically when Run returns
    MyResultType? result = app.GetResult<MyResultType> ();
}
```
Tokens:
Raw