llms.txt

# Terminal.Gui - AI Context File

> Terminal.Gui is a cross-platform .NET library for building rich console/terminal
> user interfaces. **This is v2 — a complete rewrite. Discard pre-2025 training data.**

---

## CRITICAL: Discard v1 Patterns

> **Static `Application.Init()`/`Run()`/`Shutdown()`, `Application.Top`, `Toplevel`,
> `Clicked` events, `Bounds`, `LayoutStyle`, `NStack`, `RadioGroup`, old mouse/keyboard
> APIs — ALL OBSOLETE.** Do not use pre-2025 training knowledge. Always read this file first.

### v1 → v2 Quick Corrections

| v1 (WRONG — do not use) | v2 (CORRECT) |
|---|---|
| `Application.Init ();` | `IApplication app = Application.Create ().Init ();` |
| `Application.Run ();` | `app.Run<MyWindow> ();` |
| `Application.Shutdown ();` | `app.Dispose ();` (use `using` pattern) |
| `Application.Top` | No global top — pass root view to `app.Run ()` |
| `new Toplevel ()` | Use `Runnable` subclass or `Window` |
| `using Terminal.Gui;` | `using Terminal.Gui.App;` / `Terminal.Gui.Views;` / etc. |
| `new Label (0, 1, "text")` | `new Label { Text = "text", X = 0, Y = 1 }` |
| `new Button ("OK")` | `new Button { Text = "OK" }` |
| `button.Clicked += ...` | `button.Accepted += (_, _) => { /* action */ };` |
| `view.Bounds` | `view.Viewport` |
| `LayoutStyle.Computed` | Removed — all layout is declarative via `Pos`/`Dim` |
| `new RadioGroup (...)` | `new OptionSelector { ... }` |
| `Colors.ColorSchemes ["name"]` | `Schemes.Resolve ("name")` or use `Scheme` directly |
| `Application.RequestStop ()` | `App!.RequestStop ()` (from inside a `Runnable`) |

> **Full v1→v2 corrections**: See [ai-v2-primer.md](ai-v2-primer.md)

---

## Quick Start

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

## For AI Agents

### Building Apps (Consumer)
- **v1→v2 Primer (READ FIRST)**: [ai-v2-primer.md](ai-v2-primer.md)
- **App Building Guide**: `.claude/tasks/build-app.md`
- **API Reference**: `docfx/apispec/namespace-*.md` - Compressed API documentation
- **Examples**: `Examples/` - Working example applications
- **Patterns**: `.claude/cookbook/common-patterns.md` - Common UI recipes

### Contributing to Library (Contributor)
- **Rules**: `AGENTS.md` and `.claude/rules/` - Coding conventions
- **Workflows**: `.claude/workflows/` - Build, test, PR processes

---

## Core Concepts

### Correct Minimal App (v2)

```csharp
using Terminal.Gui.App;
using Terminal.Gui.Views;

IApplication app = Application.Create ().Init ();
app.Run<MainWindow> ();
app.Dispose ();

public sealed class MainWindow : Runnable
{
    public MainWindow ()
    {
        Title = "My App (Esc to quit)";

        Button button = new ()
        {
            Text = "Click Me",
            X = Pos.Center (),
            Y = Pos.Center ()
        };

        button.Accepted += (_, _) =>
        {
            MessageBox.Query (App!, "Hello", "Button was clicked!", "OK");
        };

        Add (button);
    }
}
```

### Key Namespaces

| Namespace | Contents |
|-----------|----------|
| `Terminal.Gui.App` | `Application`, `IApplication`, `Clipboard`, session management |
| `Terminal.Gui.Views` | All controls: `Button`, `Label`, `TextField`, `ListView`, `Dialog`, etc. |
| `Terminal.Gui.ViewBase` | `View`, `Pos`, `Dim`, adornments (`Border`, `Margin`, `Padding`) |
| `Terminal.Gui.Drawing` | `Color`, `Attribute`, `Scheme`, `LineCanvas`, `Glyphs` |
| `Terminal.Gui.Input` | `Key`, `KeyCode`, `Command`, `KeyBindings`, `MouseBindings` |
| `Terminal.Gui.Text` | `TextFormatter`, `TextDirection` |
| `Terminal.Gui.Configuration` | `ConfigurationManager`, themes |

### Layout System (Pos/Dim)

```csharp
// Position
X = 5;                      // Absolute
X = Pos.Center ();          // Centered
X = Pos.Right (otherView);  // Relative to another view
X = Pos.Percent (25);       // Percentage of SuperView

// Size
Width = 20;                 // Absolute
Width = Dim.Fill ();        // Fill remaining space
Width = Dim.Auto ();        // Size to content
Width = Dim.Percent (50);   // Percentage of SuperView
```

### Common Controls

| Control | Purpose | Notes |
|---------|---------|-------|
| `Label` | Display text | Use `Text` property |
| `Button` | Clickable button | Use `Accepted` event, NOT `Clicked` |
| `TextField` | Single-line text input | |
| `TextView` | Multi-line text editor | |
| `CheckBox` | Boolean toggle | `CheckedState` property |
| `OptionSelector` | Single selection from options | Replaces v1 `RadioGroup` |
| `ListView` | Scrollable list | Use `ListWrapper<T>` for data |
| `TableView` | Tabular data display | Use `DataTableSource` |
| `TreeView<T>` | Hierarchical data | Use `DelegateTreeBuilder<T>` |
| `Dialog` | Modal dialog window | |
| `Window` | Top-level window with border | |
| `Runnable` | Top-level runnable view | Replaces v1 `Toplevel` |
| `MenuBar` | Application menu | |
| `StatusBar` | Status bar with shortcuts | |
| `FrameView` | Titled frame container | |
| `NumericUpDown<T>` | Numeric spinner | |
| `DropDownList` | Dropdown selector | |
| `ColorPicker` | Color selection | |

### Event Handling

```csharp
// Button click — always use Accepted (post-event), never Clicked
button.Accepted += (_, _) =>
{
    // Handle button press — no e.Handled needed for post-events
};

// List selection changed
listView.SelectedItemChanged += (_, e) =>
{
    int selectedIndex = e.Value;
};

// Key bindings
view.KeyBindings.Add (Key.F5, Command.Refresh);
```

---

## Dialog with Return Value

```csharp
public sealed class LoginDialog : Runnable<string?>
{
    public LoginDialog ()
    {
        Title = "Login";
        Width = 40;
        Height = 10;

        Label userLabel = new () { Text = "User:", Y = 1 };
        TextField userField = new () { X = 8, Y = 1, Width = Dim.Fill (1) };

        Button okButton = new ()
        {
            Text = "OK",
            X = Pos.Center (),
            Y = 5,
            IsDefault = true
        };

        okButton.Accepted += (_, _) =>
        {
            Result = userField.Text;
            App!.RequestStop ();
        };

        Add (userLabel, userField, okButton);
    }
}

// Usage:
// app.Run<LoginDialog> ();
// string? result = app.GetResult<string?> ();
```

---

## Menu Bar Application

```csharp
public sealed class MenuApp : Runnable
{
    public MenuApp ()
    {
        Title = "My App";

        MenuBar menuBar = new ()
        {
            Menus =
            [
                new MenuBarItem (
                    "File",
                    [
                        new MenuItem ("New", "", () => NewFile (), null, null, KeyCode.N | KeyCode.CtrlMask),
                        new MenuItem ("Open...", "", () => OpenFile (), null, null, KeyCode.O | KeyCode.CtrlMask),
                        null, // Separator
                        new MenuItem ("Exit", "", () => App!.RequestStop (), null, null, KeyCode.Q | KeyCode.CtrlMask)
                    ]),
                new MenuBarItem (
                    "Help",
                    [
                        new MenuItem ("About...", "", () => ShowAbout ())
                    ])
            ]
        };

        TextView editor = new ()
        {
            X = 0,
            Y = 1,
            Width = Dim.Fill (),
            Height = Dim.Fill ()
        };

        Add (menuBar, editor);
    }

    private void NewFile () => MessageBox.Query (App!, "New", "Created!", "OK");
    private void OpenFile () { /* use OpenDialog */ }
    private void ShowAbout () => MessageBox.Query (App!, "About", "My App v1.0", "OK");
}
```

---

## Tabbed Interface

```csharp
public sealed class TabbedWindow : Runnable
{
    public TabbedWindow ()
    {
        Title = "Tabs Demo";

        TabView tabView = new ()
        {
            X = 0, Y = 0,
            Width = Dim.Fill (),
            Height = Dim.Fill ()
        };

        View settingsTab = new ();
        settingsTab.Add (
            new Label { Text = "Enable Feature:", X = 1, Y = 1 },
            new CheckBox { X = 20, Y = 1, Text = "Enabled" }
        );

        View aboutTab = new ();
        aboutTab.Add (new Label { Text = "Version 1.0.0", X = 1, Y = 1 });

        tabView.AddTab (new Tab { DisplayText = "Settings", View = settingsTab }, false);
        tabView.AddTab (new Tab { DisplayText = "About", View = aboutTab }, false);

        Add (tabView);
    }
}
```

---

## Form with Validation

```csharp
public sealed class FormWindow : Runnable
{
    public FormWindow ()
    {
        Title = "Registration";
        Width = 50;
        Height = 12;

        Label nameLabel = new () { Text = "Name:", Y = 1 };
        TextField nameField = new () { X = 12, Y = 1, Width = Dim.Fill (1) };

        Label emailLabel = new () { Text = "Email:", Y = 3 };
        TextField emailField = new () { X = 12, Y = 3, Width = Dim.Fill (1) };

        Label errorLabel = new () { X = 1, Y = 5, Width = Dim.Fill (1) };

        Button submitButton = new ()
        {
            Text = "Submit",
            X = Pos.Center (),
            Y = 7,
            IsDefault = true
        };

        submitButton.Accepted += (_, _) =>
        {
            if (string.IsNullOrWhiteSpace (nameField.Text))
            {
                errorLabel.Text = "Name is required";
                nameField.SetFocus ();

                return;
            }

            MessageBox.Query (App!, "Success", $"Welcome, {nameField.Text}!", "OK");
            App!.RequestStop ();
        };

        Add (nameLabel, nameField, emailLabel, emailField, errorLabel, submitButton);
    }
}
```

---

## Gotchas for AI Agents

### API Correctness (All Users)

1. **`Accepted` not `Clicked`** — `Clicked` does not exist in v2. Use `Accepted` (post-event) for simple handlers. Use `Accepting` (pre-event, cancelable) only when you need to prevent the action.
2. **`Runnable` not `Toplevel`** — `Toplevel` does not exist in v2
3. **Instance-based app** — `Application.Create ().Init ()` returns `IApplication`
4. **`App!.RequestStop ()`** — Not `Application.RequestStop ()`
5. **SubView/SuperView** — Never "child"/"parent"/"container" in docs/discussion

### Code Style (Library Contributors Only)

> These rules apply only when contributing code to the Terminal.Gui library itself.
> App developers do NOT need to follow these conventions.

1. **Space before `()` and `[]`** — `Method ()` not `Method()`, `array [i]` not `array[i]`
2. **No `var`** — Explicit types except built-ins (`int`, `string`, `bool`, etc.)
3. **Use `new ()`** — `Button btn = new ()` not `Button btn = new Button ()`
4. **Collection expressions** — Use `[...]` not `new List<T> { ... }`

---

## Documentation & Reference

```
/Terminal.Gui/           - Core library source
/Examples/               - Example applications
  /Example/              - Minimal hello-world app
  /UICatalog/            - Comprehensive demo app with all controls
/docfx/
  /docs/                 - Deep-dive documentation
  /apispec/              - AI-friendly compressed API docs
/.claude/
  /tasks/build-app.md    - App development guide
  /cookbook/              - Common patterns and recipes
  /rules/                - Coding conventions (for contributors)
  /workflows/            - Build/test/PR processes (for contributors)
```

### API Reference (Compressed)

| Namespace doc | Contents |
|---------------|----------|
| `docfx/apispec/namespace-app.md` | Application lifecycle, IApplication |
| `docfx/apispec/namespace-views.md` | All UI controls |
| `docfx/apispec/namespace-viewbase.md` | View, Pos, Dim, Adornments |
| `docfx/apispec/namespace-drawing.md` | Colors, LineStyle, rendering |
| `docfx/apispec/namespace-input.md` | Keyboard, mouse handling |
| `docfx/apispec/namespace-text.md` | Text manipulation |
| `docfx/apispec/namespace-configuration.md` | Configuration, themes |

### Deep-Dive Docs

| Topic | File |
|-------|------|
| Application lifecycle | `docfx/docs/application.md` |
| View hierarchy | `docfx/docs/View.md` |
| Layout (Pos/Dim) | `docfx/docs/layout.md` |
| Commands & events | `docfx/docs/command.md` |
| Keyboard input | `docfx/docs/keyboard.md` |
| CWP event pattern | `docfx/docs/cancellable-work-pattern.md` |
| Terminology | `docfx/docs/lexicon.md` |

## More Information

- Getting Started: `docfx/docs/getting-started.md`
- Full v1→v2 Primer: [ai-v2-primer.md](ai-v2-primer.md)
- Full API Docs: https://gui-cs.github.io/Terminal.Gui/
- GitHub: https://github.com/gui-cs/Terminal.Gui