mirror of
https://github.com/gui-cs/Terminal.Gui.git
synced 2025-12-26 07:47:54 +01:00
4c772bd5f3
* Add Glyphs.ReplacementChar config property
Introduced Glyphs.ReplacementChar to allow overriding the Unicode replacement character, defaulting to a space (' '). Updated both config.json and Glyphs.cs with this property, scoped to ThemeScope and documented as an override for Rune.ReplacementChar.
* Standardize to Glyphs.ReplacementChar for wide char invalidation
Replaced all uses of Rune.ReplacementChar.ToString() with Glyphs.ReplacementChar.ToString() in OutputBufferImpl and related tests. This ensures consistent use of the replacement character when invalidating or overwriting wide characters in the output buffer.
* Add configurable wide glyph replacement chars to OutputBuffer
Allows setting custom replacement characters for wide glyphs that cannot fit in the available space via IOutputBuffer.SetReplacementChars. Updated IDriver to expose GetOutputBuffer. All code paths and tests now use the configurable characters, improving testability and flexibility. Tests now use '①' and '②' for clarity instead of the default replacement character.
* Fixed warnings.
* Update IOutputBuffer.cs
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Add tests for wide char clipping edge cases in OutputBuffer
Added three unit tests to OutputBufferWideCharTests.cs to verify and document OutputBufferImpl's behavior when wide (double-width) characters are written at the edges of a clipping region. Tests cover cases where the first or second column of a wide character is outside the clip, as well as when both columns are inside. The tests assert correct use of replacement characters, dirty flags, and column advancement, and document that certain code paths are currently unreachable due to IsValidLocation checks.
* Clarify dead code path with explanatory comments
Added comments to mark a rarely executed code path as dead code, noting it is apparently never called. Referenced the related test scenario AddStr_WideChar_FirstColumnOutsideClip_SecondColumnInside_CurrentBehavior for context. No functional changes were made.
* Remove dead code for wide char partial clip handling
Removed unreachable code that handled the case where the first column of a wide character is outside the clipping region but the second column is inside. This logic was marked as dead code and never called. Now, only the cases where the second column is outside the clip or both columns are in bounds are handled. This simplifies the code and removes unnecessary checks.
* Replaces Glyphs.ReplacementChar with Glyphs.WideGlyphReplacement to clarify its use for clipped wide glyphs. Updates IOutputBuffer to use SetWideGlyphReplacement (single Rune) instead of SetReplacementChars (two Runes). Refactors OutputBufferImpl and all test code to use the new property and method. Removes second-column replacement logic, simplifying the API and improving consistency. Updates comments and test assertions to match the new naming and behavior.
* Update themes in config.json and add new UI Catalog props
Renamed "UI Catalog Theme" to "UI Catalog" and removed the
"Glyphs.ReplacementChar" property. Added several new properties
to the "UI Catalog" theme, including default shadow, highlight
states, button alignment, and separator line style. Also added
"Glyphs.WideGlyphReplacement" to the "Hot Dog Stand" theme.
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
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.