Git_Mirror/Terminal.Gui
1
0
Fork 0
mirror of https://github.com/gui-cs/Terminal.Gui.git synced 2025-12-26 15:57:56 +01:00
Code Issues Packages Projects Releases Wiki Activity

Fixes #4289 - Simplify Drawing/Color: unify named color handling under StandardColor and remove layered resolvers (#4432)

Browse Source 
* Initial plan

* Delete AnsiColorNameResolver and MultiStandardColorNameResolver, add legacy 16-color names to StandardColor

Co-authored-by: tig <585482+tig@users.noreply.github.com>

* Refactor and enhance tests for Color, Region, and Lines

Refactored `Color` struct by removing unused methods and simplifying logic. Updated namespaces for better organization. Enhanced test coverage for `Color`, `Region`, and `LineCanvas` with new test cases, parameterized tests, and edge case handling.

Added `StraightLineExtensionsTests`, `StraightLineTests`, and `RegionClassTests` to validate behavior under various scenarios. Improved `MergeRectangles` stability and addressed crash patterns. Removed legacy features and unused code. Enhanced documentation and optimized performance in key methods.

* Improve Color struct and StandardColors functionality

Enhanced the Color struct to fully support the alpha channel for rendering intent while maintaining semantic color identity. Updated TryNameColor to ignore alpha when matching colors, ensuring transparency does not affect color resolution. Expanded XML documentation to clarify alpha channel usage and future alpha blending support.

Improved drawing documentation to explain the lifecycle, deferred rendering, and color support, including 24-bit true color and legacy 16-color compatibility. Added a new section on transparency and its role in rendering.

Revised StandardColors implementation to use modern C# features and ensure consistent ARGB mapping. Added comprehensive tests for StandardColors and Color, covering alpha handling, color parsing, thread safety, and aliased color resolution. Removed outdated tests relying on legacy behavior.

Enhanced code readability, maintainability, and test coverage to ensure correctness and backward compatibility.

* Code cleanup

* Code cleanup

* Fix warnings. Code cleanup

* Add comprehensive unit tests for ColorStrings class

Introduced a new test class `ColorStringsTests` under the
`DrawingTests.ColorTests` namespace to validate the functionality
of the `ColorStrings` class.

Key changes include:
- Added tests for `GetColorName` to verify behavior for standard
  and non-standard colors, ignoring alpha channels, and handling
  known colors.
- Added tests for `GetStandardColorNames` to ensure the method
  returns a non-empty, alphabetically sorted collection containing
  all `StandardColor` enum values.
- Implemented tests for `TryParseStandardColorName` to validate
  case-insensitive parsing, hex color support, handling invalid
  input, and `ReadOnlySpan<char>` compatibility.
- Added tests for `TryParseNamedColor` to verify parsing of named
  and hex colors, handling of aliases, and `ReadOnlySpan<char>`
  support.
- Added round-trip tests to ensure consistency between
  `GetColorName`, `TryParseNamedColor`, `GetStandardColorNames`,
  and `TryParseStandardColorName`.

These tests ensure robust validation of color parsing and naming
functionality.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: tig <585482+tig@users.noreply.github.com>
Co-authored-by: Tig <tig@users.noreply.github.com>
This commit is contained in:
Copilot
2025-12-03 11:09:02 -07:00
committed by GitHub
parent c9868e9901
commit 6d53276be2
43 changed files with 951 additions and 835 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
docfx/docs/drawing.md
View File

@@ -10,6 +10,27 @@ Terminal.Gui provides a set of APIs for formatting text, line drawing, and chara
Terminal.Gui apps draw using the @Terminal.Gui.ViewBase.View.Move(System.Int32,System.Int32) and @Terminal.Gui.ViewBase.View.AddRune(System.Text.Rune) APIs. Move selects the column and row of the cell and AddRune places the specified glyph in that cell using the @Terminal.Gui.Drawing.Attribute that was most recently set via @Terminal.Gui.ViewBase.View.SetAttribute(Terminal.Gui.Drawing.Attribute). The driver caches all changed Cells and efficiently outputs them to the terminal each iteration of the Application. In other words, Terminal.Gui uses deferred rendering.
## Drawing Lifecycle
**Drawing occurs during Application MainLoop iterations**, not immediately when draw-related methods are called. This deferred rendering approach provides better performance and ensures visual consistency.
### MainLoop Iteration Process
Each iteration of the @Terminal.Gui.App.Application MainLoop (throttled to a maximum rate) performs these steps in order:
1. **Layout** - Views that need layout are measured and positioned (@Terminal.Gui.ViewBase.View.LayoutSubviews is called)
2. **Draw** - Views that need drawing update the driver's back buffer (@Terminal.Gui.ViewBase.View.Draw is called)
3. **Write** - The driver writes changed portions of the back buffer to the actual terminal
4. **Cursor** - The driver ensures the cursor is positioned correctly with appropriate visibility
### When Drawing Actually Occurs
- **Normal Operation**: Drawing happens automatically during MainLoop iterations when @Terminal.Gui.ViewBase.View.NeedsDraw or @Terminal.Gui.ViewBase.View.SubViewNeedsDraw is set
- **Forced Update**: @Terminal.Gui.App.Application.LayoutAndDraw can be called to immediately trigger layout and drawing outside of the normal iteration cycle
- **Testing**: Tests can call @Terminal.Gui.ViewBase.View.Draw directly to update the back buffer, then call @Terminal.Gui.Drivers.IDriver.Refresh to output to the terminal
**Important**: Calling `View.Draw()` does not immediately update the terminal screen. It only updates the driver's back buffer. The actual terminal output occurs when the driver's `Refresh()` method is called, which happens automatically during MainLoop iterations.
## Coordinate System for Drawing
The @Terminal.Gui.ViewBase.View draw APIs all take coordinates specified in *Viewport-Relative* coordinates. That is, `0, 0` is the top-left cell visible to the user.
@@ -60,6 +81,8 @@ Then, after the above steps have completed, the Mainloop will iterate through al
If a View need to redraw because something changed within it's Content Area it can call @Terminal.Gui.ViewBase.View.SetNeedsDraw. If a View needs to be redrawn because something has changed the size of the Viewport, it can call @Terminal.Gui.ViewBase.View.SetNeedsLayout.
**Note**: Calling `SetNeedsDraw()` does not immediately cause drawing to occur. It marks the view as needing to be redrawn, which will happen in the next MainLoop iteration. To force immediate drawing (typically only needed in tests), call @Terminal.Gui.App.Application.LayoutAndDraw.
## Clipping
Clipping enables better performance and features like transparent margins by ensuring regions of the terminal that need to be drawn actually get drawn by the driver. Terminal.Gui supports non-rectangular clip regions with @Terminal.Gui.Drawing.Region. The driver.Clip is the application managed clip region and is managed by @Terminal.Gui.App.Application. Developers cannot change this directly, but can use @Terminal.Gui.ViewBase.View.SetClipToScreen, @Terminal.Gui.ViewBase.View.SetClip(Terminal.Gui.Drawing.Region), @Terminal.Gui.ViewBase.View.SetClipToFrame, etc...
@@ -98,6 +121,54 @@ SetAttributeForRole (VisualRole.Focus);
AddStr ("Red on Black Underlined.");
```
## Color
Terminal.Gui supports 24-bit true color (16.7 million colors) via the @Terminal.Gui.Drawing.Color struct. The @Terminal.Gui.Drawing.Color struct represents colors in ARGB32 format, with separate bytes for Alpha (transparency), Red, Green, and Blue components.
### Standard Colors (W3C+)
Terminal.Gui provides comprehensive support for W3C standard color names plus additional common terminal colors via the @Terminal.Gui.Drawing.StandardColor enum. This includes all standard W3C colors (like `AliceBlue`, `Red`, `Tomato`, etc.) as well as classic terminal colors (like `AmberPhosphor`, `GreenPhosphor`).
Colors can be created from standard color names:
```cs
var color1 = new Color(StandardColor.CornflowerBlue);
var color2 = new Color(StandardColor.Tomato);
var color3 = new Color("Red"); // Case-insensitive color name parsing
```
Standard colors can also be parsed from strings:
```cs
if (Color.TryParse("CornflowerBlue", out Color color))
{
// Use the color
}
```
### Alpha Channel and Transparency
While @Terminal.Gui.Drawing.Color supports an alpha channel for transparency (values 0-255), **terminal rendering does not currently support alpha blending**. The alpha channel is primarily used to:
- Indicate whether a color should be rendered at all (alpha = 0 means fully transparent/don't render)
- Support future transparency features
- Enable terminal background pass-through (see [#2381](https://github.com/gui-cs/Terminal.Gui/issues/2381) and [#4229](https://github.com/gui-cs/Terminal.Gui/issues/4229))
**Important**: When matching colors to standard color names, the alpha channel is **ignored**. This means `Color(255, 0, 0, 255)` (opaque red) and `Color(255, 0, 0, 128)` (semi-transparent red) will both be recognized as "Red". This design decision supports the vision of enabling transparent backgrounds while still being able to identify colors semantically.
```cs
var opaqueRed = new Color(255, 0, 0, 255);
var transparentRed = new Color(255, 0, 0, 0);
// Both will resolve to "Red"
ColorStrings.GetColorName(opaqueRed); // Returns "Red"
ColorStrings.GetColorName(transparentRed); // Returns "Red"
```
### Legacy 16-Color Support
For backwards compatibility and terminals with limited color support, Terminal.Gui maintains the legacy 16-color system via @Terminal.Gui.Drawing.ColorName16. When true color is not available or when `Application.Force16Colors` is set, Terminal.Gui will map true colors to the nearest 16-color equivalent.
## VisualRole
Represents the semantic visual role of a visual element rendered by a View (e.g., Normal text, Focused item, Active selection).