mirror of
https://github.com/gui-cs/Terminal.Gui.git
synced 2025-12-26 15:57:56 +01:00
c9868e9901
* pre-alpha -> alpha * don't build docs for v2_release * 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. * Updated runnable * Refactor ApplicationStressTests for modularity and robustness Refactored `ApplicationStressTests` to use `IApplication` instances instead of static methods, enabling better testability and alignment with dependency injection. Enhanced timeout handling in `RunTest` with elapsed time tracking and debugger-aware polling intervals. Improved error handling by introducing exceptions for timeouts and ensuring proper resource cleanup with `application.Dispose`. Refactored `Launch` and `InvokeLeakTest` methods for clarity and consistency. Removed redundant code and improved overall readability and maintainability.
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.