mirror of
https://github.com/gui-cs/Terminal.Gui.git
synced 2025-12-26 15:57:56 +01:00
8e92327dbe
* 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
131 lines
5.2 KiB
Markdown
131 lines
5.2 KiB
Markdown
[](https://www.nuget.org/packages/Terminal.Gui)
|
|
[](https://codecov.io/gh/gui-cs/Terminal.Gui)
|
|
[](https://www.nuget.org/packages/Terminal.Gui)
|
|
[](LICENSE)
|
|
|
|
|
|
# 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)**: [](https://www.nuget.org/packages/Terminal.Gui) - 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](https://github.com/gui-cs/Terminal.Gui.templates), create a new TUI app, and run it:
|
|
|
|
```powershell
|
|
dotnet new --install Terminal.Gui.templates
|
|
dotnet new tui -n myproj
|
|
cd myproj
|
|
dotnet run
|
|
```
|
|
|
|
Press `Esc` to exit (the default [QuitKey](https://gui-cs.github.io/Terminal.Gui/api/Terminal.Gui.App.Application.html#Terminal_Gui_App_Application_QuitKey)).
|
|
|
|
Run the comprehensive [UI Catalog](Examples/UICatalog) demo to explore all controls:
|
|
|
|
```powershell
|
|
dotnet run --project Examples/UICatalog/UICatalog.csproj
|
|
```
|
|
|
|
# Simple Example
|
|
|
|
```csharp
|
|
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](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](https://gui-cs.github.io/Terminal.Gui/docs/views) for available controls and [What's New in v2](https://gui-cs.github.io/Terminal.Gui/docs/newinv2) for architectural improvements.
|
|
|
|
# Documentation
|
|
|
|
Comprehensive documentation is at [gui-cs.github.io/Terminal.Gui](https://gui-cs.github.io/Terminal.Gui).
|
|
|
|
## Getting Started
|
|
|
|
- **[Getting Started Guide](https://gui-cs.github.io/Terminal.Gui/docs/getting-started)** - First Terminal.Gui application
|
|
- **[API Reference](https://gui-cs.github.io/Terminal.Gui/api/Terminal.Gui.App.html)** - Complete API documentation
|
|
- **[What's New in v2](https://gui-cs.github.io/Terminal.Gui/docs/newinv2)** - New features and improvements
|
|
|
|
## Migration & Deep Dives
|
|
|
|
- **[Migrating from v1 to v2](https://gui-cs.github.io/Terminal.Gui/docs/migratingfromv1)** - Complete migration guide
|
|
- **[Application Architecture](https://gui-cs.github.io/Terminal.Gui/docs/application)** - Instance-based model and IRunnable pattern
|
|
- **[Layout System](https://gui-cs.github.io/Terminal.Gui/docs/layout)** - Positioning, sizing, and adornments
|
|
- **[Keyboard Handling](https://gui-cs.github.io/Terminal.Gui/docs/keyboard)** - Key bindings and commands
|
|
- **[View Documentation](https://gui-cs.github.io/Terminal.Gui/docs/View)** - View hierarchy and lifecycle
|
|
- **[Configuration](https://gui-cs.github.io/Terminal.Gui/docs/config)** - Themes and persistent settings
|
|
|
|
See the [documentation index](https://gui-cs.github.io/Terminal.Gui/docs/index) for all topics.
|
|
|
|
# Installing
|
|
|
|
## v2 Alpha (Recommended)
|
|
|
|
```powershell
|
|
dotnet add package Terminal.Gui --version "2.0.0-alpha.*"
|
|
```
|
|
|
|
## v2 Develop (Latest)
|
|
|
|
```powershell
|
|
dotnet add package Terminal.Gui --version "2.0.0-develop.*"
|
|
```
|
|
|
|
## v1 Legacy
|
|
|
|
```powershell
|
|
dotnet add package Terminal.Gui --version "1.*"
|
|
```
|
|
|
|
Or use the [Terminal.Gui.Templates](https://github.com/gui-cs/Terminal.Gui.templates).
|
|
|
|
# Contributing
|
|
|
|
Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
# History
|
|
|
|
See [gui-cs](https://github.com/gui-cs/) for project history and origins.
|