# Terminal.Gui — Cross-Platform TUI Toolkit for .NET

> A .NET library for building full terminal user interfaces with windows, dialogs, menus, and interactive widgets that run on any OS.

## Install

Save as a script file and run:

# Terminal.Gui — Cross-Platform TUI Toolkit for .NET

## Quick Use
```bash
dotnet add package Terminal.Gui
```
```csharp
using Terminal.Gui;
Application.Init();
var win = new Window("Hello") {
    X = 0, Y = 0, Width = Dim.Fill(), Height = Dim.Fill()
};
win.Add(new Label("Welcome to Terminal.Gui!"));
Application.Top.Add(win);
Application.Run();
Application.Shutdown();
```

## Introduction
Terminal.Gui is a cross-platform toolkit for building rich terminal user interfaces in .NET. It provides a window manager, layout engine, and a library of widgets (buttons, text fields, list views, tree views) that let you build desktop-style applications entirely in the terminal.

## What Terminal.Gui Does
- Provides a full windowing system with overlapping and tiled windows in the terminal
- Ships with 40+ built-in widgets including buttons, text editors, list views, and tree views
- Offers a layout engine with absolute, computed, and auto-sizing positioning
- Handles keyboard navigation, mouse input, and clipboard operations cross-platform
- Supports 24-bit true color, Unicode, and bidirectional text rendering

## Architecture Overview
Terminal.Gui uses a main loop pattern where Application.Run drives the event loop, dispatching keyboard, mouse, and timer events to the view hierarchy. Views are arranged in a tree rooted at Application.Top. The layout engine computes positions using a constraint-based system (Pos and Dim classes). Rendering is abstracted behind a ConsoleDriver interface with implementations for curses (Linux/macOS), Windows Console, and a headless driver for testing.

## Self-Hosting & Configuration
- Install via NuGet: `dotnet add package Terminal.Gui`
- Targets .NET 8+ and also supports .NET Standard 2.0
- Works out of the box on Windows Terminal, iTerm2, xterm, and most Linux terminals
- Configure the color scheme globally or per-view using the ColorScheme class
- Use the built-in UI Catalog sample app to explore all widgets and layouts interactively

## Key Features
- Desktop-style overlapping windows, modal dialogs, and menu bars in the terminal
- Comprehensive text editor widget with selection, undo/redo, and word wrap
- Built-in file and color picker dialogs
- Event-driven architecture with .NET events and async support
- Automated UI testing via the headless console driver

## Comparison with Similar Tools
- **Spectre.Console** — focused on output rendering and prompts; Terminal.Gui provides full interactive TUI with windowing
- **Textual (Python)** — similar concept for Python; Terminal.Gui is the .NET counterpart
- **Ratatui (Rust)** — immediate-mode TUI; Terminal.Gui uses a retained-mode widget tree
- **Bubble Tea (Go)** — Elm-architecture TUI for Go; Terminal.Gui offers a more traditional event-driven model

## FAQ
**Q: Can I use Terminal.Gui in a web context?**
A: It is designed for terminal environments. For web, consider pairing it with a web-based terminal emulator.

**Q: Does it support mouse input?**
A: Yes. Click, drag, scroll, and hover events are supported on terminals that report mouse events.

**Q: How do I handle responsive layouts?**
A: Use computed Pos and Dim values (e.g., Dim.Fill(), Pos.Center()) which adjust to terminal size changes.

**Q: Is there a visual designer?**
A: The community maintains a TUI designer prototype, and the UI Catalog app serves as an interactive reference.

## Sources
- https://github.com/gui-cs/Terminal.Gui
- https://gui-cs.github.io/Terminal.GuiV2Docs/

---
Source: https://tokrepo.com/en/workflows/asset-263347f5
Author: Script Depot