mirror of https://github.com/gui-cs/Terminal.Gui.git synced 2025-12-26 15:57:56 +01:00

Files

Tig 8e92327dbe Fixes #4423 - migration docs (#4424 )

* Pulled from v2_release

* Refactor migration guide for Terminal.Gui v2

Restructured and expanded the migration guide to provide a comprehensive resource for transitioning from Terminal.Gui v1 to v2. Key updates include:

- Added a Table of Contents for easier navigation.
- Summarized major architectural changes in v2, including the instance-based application model, IRunnable architecture, and 24-bit TrueColor support.
- Updated examples to reflect new patterns, such as initializers replacing constructors and explicit disposal using `IDisposable`.
- Documented changes to the layout system, including the removal of `Absolute`/`Computed` styles and the introduction of `Viewport`.
- Standardized event patterns to use `object sender, EventArgs args`.
- Detailed updates to the Keyboard, Mouse, and Navigation APIs, including configurable key bindings and viewport-relative mouse coordinates.
- Replaced legacy components like `ScrollView` and `ContextMenu` with built-in scrolling and `PopoverMenu`.
- Clarified disposal rules and introduced best practices for resource management.
- Provided a complete migration example and a summary of breaking changes.

This update aims to simplify the migration process by addressing breaking changes, introducing new features, and aligning with modern .NET conventions.

* Update: Revamp Terminal.Gui v2 What's New document

Comprehensively updated the "What's New" document for Terminal.Gui v2 to improve clarity, structure, and usability. Key changes include:

- Updated the document title to better reflect its purpose.
- Added a detailed table of contents for improved navigation.
- Enhanced the "Overview" section with a concise summary of v2 improvements.
- Expanded the "Architectural Overhaul" section with a "Design Philosophy" subsection.
- Introduced new sections for the instance-based application model and IRunnable architecture.
- Modernized code examples to align with .NET best practices.
- Added detailed explanations for TrueColor, adornments, and user-configurable themes.
- Documented built-in scrolling, advanced layout features, and enhanced navigation.
- Listed new views (e.g., `CharMap`, `ColorPicker`) and improvements to existing views.
- Described enhanced input handling, including the new `Key` class and key binding system.
- Added sections on configuration persistence, debugging tools, and performance metrics.
- Highlighted support for Sixel images, AOT compatibility, and improved Unicode handling.
- Summarized the transformative updates in the conclusion.

These changes aim to provide a structured, developer-friendly guide to the new features and improvements in Terminal.Gui v2.

* Updadted README

2025-12-01 13:33:13 -07:00

5.2 KiB

Raw Blame History

Terminal.Gui v2

Cross-platform UI toolkit for building sophisticated terminal UI (TUI) applications on Windows, macOS, and Linux/Unix.

v2 Alpha (Current): - Recommended for new projects
v1 (Legacy): - Maintenance mode only

Important:

v1 is in maintenance mode - only critical bug fixes accepted

v2 Alpha is recommended for new projects - API is stable with comprehensive features

Breaking changes possible before Beta, but core architecture is solid

Quick Start

Install the Terminal.Gui.Templates, create a new TUI app, and run it:

dotnet new --install Terminal.Gui.templates
dotnet new tui -n myproj
cd myproj
dotnet run

Press Esc to exit (the default QuitKey).

Run the comprehensive UI Catalog demo to explore all controls:

dotnet run --project Examples/UICatalog/UICatalog.csproj

Simple Example

using Terminal.Gui;

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

using Window window = new () { Title = "Hello World (Esc to quit)" };
Label label = new ()
{
    Text = "Hello, Terminal.Gui v2!",
    X = Pos.Center (),
    Y = Pos.Center ()
};
window.Add (label);

app.Run (window);

See the Examples directory for more.

Build Powerful Terminal Applications

Terminal.Gui enables building sophisticated console applications with modern UIs:

Rich Forms and Dialogs - Text fields, buttons, checkboxes, radio buttons, and data validation
Interactive Data Views - Tables, lists, and trees with sorting, filtering, and in-place editing
Visualizations - Charts, graphs, progress indicators, and color pickers with TrueColor support
Text Editors - Full-featured text editing with clipboard, undo/redo, and Unicode support
File Management - File and directory browsers with search and filtering
Wizards and Multi-Step Processes - Guided workflows with navigation and validation
System Monitoring Tools - Real-time dashboards with scrollable, resizable views
Configuration UIs - Settings editors with persistent themes and user preferences
Cross-Platform CLI Tools - Consistent experience on Windows, macOS, and Linux
Server Management Interfaces - SSH-compatible UIs for remote administration

See the Views Overview for available controls and What's New in v2 for architectural improvements.

Documentation

Comprehensive documentation is at gui-cs.github.io/Terminal.Gui.

Getting Started

Getting Started Guide - First Terminal.Gui application
API Reference - Complete API documentation
What's New in v2 - New features and improvements

Migration & Deep Dives

Migrating from v1 to v2 - Complete migration guide
Application Architecture - Instance-based model and IRunnable pattern
Layout System - Positioning, sizing, and adornments
Keyboard Handling - Key bindings and commands
View Documentation - View hierarchy and lifecycle
Configuration - Themes and persistent settings

See the documentation index for all topics.

Installing

v2 Alpha (Recommended)

dotnet add package Terminal.Gui --version "2.0.0-alpha.*"

v2 Develop (Latest)

dotnet add package Terminal.Gui --version "2.0.0-develop.*"

v1 Legacy

dotnet add package Terminal.Gui --version "1.*"

Or use the Terminal.Gui.Templates.

Contributing

Contributions welcome! See CONTRIBUTING.md.

History

See gui-cs for project history and origins.

5.2 KiB Raw Blame History