# Terminal.Gui - AI Context File

> Terminal.Gui is a cross-platform .NET library for building rich console/terminal user interfaces.

## Quick Start

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

## For AI Agents

### Building Apps (Consumer)
- **Start here**: `.claude/tasks/build-app.md` - Step-by-step app development guide
- **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**: `CLAUDE.md` and `.claude/rules/` - Coding conventions
- **Workflows**: `.claude/workflows/` - Build, test, PR processes

## Core Concepts

### Minimal App Structure
```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)";
        Add (new Label { Text = "Hello, Terminal.Gui!" });
    }
}
```

### Key Namespaces
- `Terminal.Gui.App` - Application lifecycle (`Application`, `IApplication`)
- `Terminal.Gui.Views` - UI controls (`Button`, `Label`, `TextField`, `ListView`, etc.)
- `Terminal.Gui.ViewBase` - Base classes (`View`, `Pos`, `Dim`)
- `Terminal.Gui.Drawing` - Colors, styles, rendering

### 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 container

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

### Common Controls
| Control | Purpose |
|---------|---------|
| Label | Display text |
| Button | Clickable button |
| TextField | Single-line text input |
| TextView | Multi-line text editor |
| CheckBox | Boolean toggle |
| RadioGroup | Single selection from options |
| ListView | Scrollable list |
| TableView | Tabular data display |
| TreeView | Hierarchical data |
| Dialog | Modal dialog window |
| Window | Top-level window with border |
| MenuBar | Application menu |
| StatusBar | Status bar at bottom |

### Event Handling
```csharp
button.Accepting += (sender, e) =>
{
    // Handle button press
    e.Handled = true;
};
```

## Documentation Structure

```
/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)
```

## More Information

- Getting Started: `docfx/docs/getting-started.md`
- Full API Docs: https://gui-cs.github.io/Terminal.Gui/
- GitHub: https://github.com/gui-cs/Terminal.Gui