Add Non-Color Attributes (Bold, Italic, Underline, etc.) to `Attributes`

[tig]

As part of the ColorSchemes redesign discussed in

• Master Issue for Updating Color/Attribute System #457

Terminal.Gui’s Attributes (within ColorScheme, proposed to be renamed Scheme) currently only support colors but will soon need to include non-color styles to align with modern terminal capabilities and user expectations. These styles, inspired by PowerShell’s $PSStyle ANSI styles and common terminal features, include Bold, Italic, Underline, Blink, Reverse, Hidden, and Strikethrough. Adding these to Attributes will enable richer visual styling for Terminal.Gui views, support PowerShell-like TUI applications, and align with efforts to honor user terminal settings (#2381).

This issue focuses on extending Attributes to support these non-color styles, keeping #457 as the master issue for the broader ColorSchemes redesign, including naming changes (#4057).

Current State:

• Attributes (within ColorScheme) defines foreground and background colors for states like Normal, HotNormal, Focus, HotFocus, and Disabled.
• No support exists for non-color styles (e.g., Bold, Italic), limiting Terminal.Gui’s ability to render advanced terminal effects.
• PowerShell’s $PSStyle (PowerShell 7.2+) supports ANSI styles (Bold, Italic, Underline, Blink, Reverse, Hidden, Strikethrough), which Terminal.Gui should emulate for consistency with user terminal settings.

Proposed Changes:

1. Extend Attributes struct:

   • Define an enum for flags for non-color styles: Bold, Italic, Underline, Blink, Reverse, Hidden, Strikethrough.
   • Add a property for this enum to Attribute

2. Update Rendering:

• Modify Terminal.Gui’s rendering engine to apply these styles using ANSI escape sequences or terminal-specific APIs, leveraging truecolor support (Truecolors (direct RGB colors) support #48).
• Ensure compatibility with terminals supporting 16, 256, or 24-bit RGB colors.

3. Integrate with Scheme:

   • Update Scheme (or ColorScheme, pending Rename ColorScheme to Scheme and Migrate Colors to ConfigurationManager.Themes #4057) to use the enhanced Attributes for all attributes (Normal, HotNormal, Focus, HotFocus, Disabled, Active, HotActive, ReadOnly).

   • Example:

     var scheme = new Scheme
     {
         Normal = new Attribute { Foreground = Color.White, Bold = true },
         HotNormal = new Attribute { Foreground = Color.Yellow, Underline = true }
     };

4. Support User Terminal Settings:

   • Allow Attributes to adopt styles from $PSStyle (e.g., $PSStyle.PSReadLine.Selection’s Reverse style) when querying terminal settings (Attribute System Should honor terminal settings #2381).
   • Fallback to terminal capabilities ($TERM) for non-PowerShell environments.

5. Accessibility:

   • Ensure non-color styles maintain readability (e.g., avoid Blink or Hidden for critical UI elements).
   • Enforce contrast for color-based attributes (WCAG 2.1’s 4.5:1 ratio).

Benefits:

• Enables rich styling for Terminal.Gui views, matching modern terminal capabilities.
• Aligns with PowerShell’s $PSStyle for PowerShell TUI applications.
• Supports Attribute System Should honor terminal settings #2381 by allowing Terminal.Gui to reflect user-defined ANSI styles.
• Enhances Master Issue for Updating Color/Attribute System #457’s goal of a flexible, future-proof styling system.

Tasks:

• Define Attributes API for non-color styles (e.g., boolean flags, enum, or bitmask).
• Update rendering engine to support Bold, Italic, Underline, Blink, Reverse, Hidden, Strikethrough.
• Integrate enhanced Attributes with Scheme attributes (Normal, Active, etc.).
• Add support for querying $PSStyle ANSI styles or $TERM capabilities (Attribute System Should honor terminal settings #2381).
• Ensure accessibility with contrast checks and style restrictions.
• Update documentation and samples (e.g., add a styled TextView demo).
• Add unit tests for non-color style rendering.

Related Issues:

• Master Issue for Updating Color/Attribute System #457
• Attribute System Should honor terminal settings #2381
• Rename ColorScheme to Scheme and Migrate Colors to ConfigurationManager.Themes #4057
• Truecolors (direct RGB colors) support #48

Open Questions:

• Which non-color styles are most critical (e.g., prioritize Bold, Italic over Blink)?
• Should Attributes use boolean flags, an enum, or a bitmask for styles?
• How do we handle terminals with limited style support (e.g., no Italic)?

Community feedback on the proposed styles, API design, and prioritization is welcome!

[YourRobotOverlord]

This makes me so happy!

Which non-color styles are most critical (e.g., prioritize Bold, Italic over Blink)?

Underline, Bold, and Italic would be most important to me, in that order.

Xtimato uses a .md subset parser that tries to represent different header levels using characters only, and its surprisingly difficult to represent hierarchical importance that way.
I think these attributes would make things like this so much easier.

Header Levels

Should Attributes use boolean flags, an enum, or a bitmask for styles?

I personally prefer boolean flags, it just seems like its easier to bind them to things like checkboxes etc.

[BDisp]

A boolean will force to create different properties for each setting, Underline, Bold, Italic and Blink. An enum will allow to have one property which can use many flags as needed.

[tig]

Proposal:

using System;

namespace Terminal.Gui;

/// <summary>
/// Defines non-color text style flags for an <see cref="Attribute"/>.
/// </summary>
/// <remarks>
/// <para>
/// Only a subset of ANSI SGR (Select Graphic Rendition) styles are represented.
/// Styles that are poorly supported, non-visual, or redundant with other APIs are omitted.
/// </para>
/// <para>
/// Multiple styles can be combined using bitwise operations. Use <see cref="Attribute.TextStyle"/>
/// to get or set these styles on an <see cref="Attribute"/>.
/// </para>
/// </remarks>
[Flags]
public enum TextStyle {
	/// <summary>
	/// No text style.
	/// </summary>
	/// <remarks>Corresponds to no active SGR styles.</remarks>
	None = 0b_0000_0000,

	/// <summary>
	/// Bold text.
	/// </summary>
	/// <remarks>SGR code: 1 (Bold).</remarks>
	Bold = 0b_0000_0001,

	/// <summary>
	/// Faint (dim) text.
	/// </summary>
	/// <remarks>SGR code: 2 (Faint). Not widely supported on all terminals.</remarks>
	Faint = 0b_0000_0010,

	/// <summary>
	/// Italic text.
	/// </summary>
	/// <remarks>SGR code: 3 (Italic). Some terminals may not support italic rendering.</remarks>
	Italic = 0b_0000_0100,

	/// <summary>
	/// Underlined text.
	/// </summary>
	/// <remarks>SGR code: 4 (Underline).</remarks>
	Underline = 0b_0000_1000,

	/// <summary>
	/// Slow blinking text.
	/// </summary>
	/// <remarks>SGR code: 5 (Slow Blink). Support varies; blinking is often disabled in modern terminals.</remarks>
	Blink = 0b_0001_0000,

	/// <summary>
	/// Reverse video (swaps foreground and background colors).
	/// </summary>
	/// <remarks>SGR code: 7 (Reverse Video).</remarks>
	Reverse = 0b_0010_0000,

	/// <summary>
	/// Strikethrough (crossed-out) text.
	/// </summary>
	/// <remarks>SGR code: 9 (Crossed-out / Strikethrough).</remarks>
	Strikethrough = 0b_0100_0000,
}

New property on Attribute:

/// <summary>
/// Gets or sets the text styles applied to the <see cref="Attribute"/>.
/// </summary>
public TextStyle TextStyle { get; set; }

Thots?

[tig]

We'd add this or similar to EscSeqUtils:

    /// <summary>
    /// Appends an ANSI SGR (Select Graphic Rendition) escape sequence to apply the specified <see cref="TextStyle"/>.
    /// </summary>
    /// <param name="output">The <see cref="StringBuilder"/> to append the escape sequence to.</param>
    /// <param name="textStyle">The <see cref="TextStyle"/> flags to apply.</param>
    internal static void CSI_AppendTextStyle (StringBuilder output, TextStyle textStyle)
    {
        if (textStyle == TextStyle.None) {
            return;
        }

        var sgr = new List<int> ();

        if (textStyle.HasFlag (TextStyle.Bold)) {
            sgr.Add (1);
        }

        if (textStyle.HasFlag (TextStyle.Faint)) {
            sgr.Add (2);
        }

        if (textStyle.HasFlag (TextStyle.Italic)) {
            sgr.Add (3);
        }

        if (textStyle.HasFlag (TextStyle.Underline)) {
            sgr.Add (4);
        }

        if (textStyle.HasFlag (TextStyle.Blink)) {
            sgr.Add (5);
        }

        if (textStyle.HasFlag (TextStyle.Reverse)) {
            sgr.Add (7);
        }

        if (textStyle.HasFlag (TextStyle.Strikethrough)) {
            sgr.Add (9);
        }

        if (sgr.Count == 0) {
            return;
        }

        output.Append ("\x1b[");
        output.Append (string.Join (';', sgr));
        output.Append ('m');

Then, I think this is all that would need to change in NetOutput.cs (v2net) for example:

@@ class NetOutput : IConsoleOutput
 {
     private readonly bool _isWinPlatform;

     private CursorVisibility? _cachedCursorVisibility;
+
+    private TextStyle? _redrawTextStyle;

     /// <summary>
     ///     Creates a new instance of the <see cref="NetOutput"/> class.
     /// </summary>
@@ public void Write (IOutputBuffer buffer)
             int lastCol = -1;

             CursorVisibility? savedVisibility = _cachedCursorVisibility;
             SetCursorVisibility (CursorVisibility.Invisible);

             const int maxCharsPerRune = 2;
             Span<char> runeBuffer = stackalloc char[maxCharsPerRune];

             for (int row = top; row < rows; row++)
             {
@@ public void Write (IOutputBuffer buffer)
                 for (int col = left; col < cols; col++)
                 {
                     lastCol = -1;
                     var outputWidth = 0;

                     for (; col < cols; col++)
                     {
                         if (!buffer.Contents [row, col].IsDirty)
                         {
@@ public void Write (IOutputBuffer buffer)
                         if (lastCol + 1 < cols)
                         {
                             lastCol++;
                         }

                         continue;
                     }

                     if (lastCol == -1)
                     {
                         lastCol = col;
                     }

                     Attribute attr = buffer.Contents [row, col].Attribute.Value;

-                    // Performance: Only send the escape sequence if the attribute has changed.
-                    if (attr != redrawAttr)
+                    // Performance: Only send escape sequences if the attribute or style has changed.
+                    if (attr != redrawAttr || attr.TextStyle != _redrawTextStyle)
                     {
                         redrawAttr = attr;
+                        _redrawTextStyle = attr.TextStyle;

                         EscSeqUtils.CSI_AppendForegroundColorRGB (
                             output,
                             attr.Foreground.R,
                             attr.Foreground.G,
                             attr.Foreground.B
                         );

                         EscSeqUtils.CSI_AppendBackgroundColorRGB (
                             output,
                             attr.Background.R,
                             attr.Background.G,
                             attr.Background.B
                         );
+
+                        EscSeqUtils.CSI_AppendTextStyle (
+                            output,
+                            attr.TextStyle
+                        );
                     }

                     outputWidth++;
@@ private void WriteToConsole (StringBuilder output, ref int lastCol, int row, ref int outputWidth)
@@ public void Dispose ()

[dandole]

I think under the EscSeqUtils.CSI_AppendTextStyle when you have a TextStyle.None instead of just returning; you'll need to unset any of the styles that may have been turned on. Something like

        if (textStyle == TextStyle.None)
        {
            sgr.Add (22); // Undo Bold / Faint
            sgr.Add (23); // Undo Italic
            sgr.Add (24); // Undo Underline
            sgr.Add (25); // Undo Blink
            sgr.Add (27); // Undo Reverse
            sgr.Add (29); // Undo Strikethrough
        }

[Error-String-Expected-Got-Nil]

Hmm, on the note of disabling text styles, that will also need to be done when the text style changes in any way, since different styles aren't mutually exclusive like colors. I.e., if previously written text was only bold, and the new style is only italic, you have to disable bold and enable italic.

I think it might make sense to add another function, EscSeqUtils.CSI_AppendTextStyleDisable(), which does the same thing as the previously mentioned EscSeqUtils.CSI_AppendTextStyle(), but outputs the disabling codes instead of the enabling ones.

With that, you can do a little bit of bitwise manipulation to set things properly:

internal static void CSI_AppendTextStyleChange(StringBuilder output, TextStyle prev, TextStyle next)
{
    // A ^ B is the difference in flags between A and B. That & B are the flags that were in B that changed,
    // that & A are the flags that were in A that changed, so the enabled and disabled flags respectively.
    var difference = prev ^ next;
    var enabled = difference & next;
    var disabled = difference & prev;

    // Functions both internally check if given TextStyle is TextStyle.None already, can just call both immediately.
    CSI_AppendTextStyle(output, enabled);
    CSI_AppendTextStyleDisable(output, disabled);
}

This should handle all style change cases, while also only writing as many terminal commands as strictly necessary.

[dandole]

Agreed. In my "messin' around" clone of TG (using most of the code that Tig outlined above), I ended up with this code to handle switching things off, because I didn't know at the start, that these settings were "sticky" unless you reset (which also blows away color settings) or unset individually; resulting in the screen being rendered with underlines to the end of the page after applying an underline to a label for example. This code also makes it so that None combined (or'ed |) with other attributes gets you None. Which may not be the expected result or the right way to do it. But for "messin' around" I now have italic, blinking, reverse, faint (bold and normal are render the same on Windows), underline, strikethrough, and combinations of those working (again mostly from Tig's code above).

    internal static void CSI_AppendTextStyle (StringBuilder output, TextStyle textStyle)
    {
        var sgr = new List<int> ();

        if (textStyle.HasFlag (TextStyle.None))
        {
            sgr.Add (22); // Unset Bold / Faint
            sgr.Add (23); // Unset Italic
            sgr.Add (24); // Unset Underline
            sgr.Add (25); // Unset Blink
            sgr.Add (27); // Unset Reverse
            sgr.Add (29); // Unset Strikethrough
        }
        else
        {
            if (textStyle.HasFlag (TextStyle.Bold) || textStyle.HasFlag (TextStyle.Faint))
            {
                if (textStyle.HasFlag (TextStyle.Bold))
                {
                    sgr.Add (1); // set Bold
                }
                else if (textStyle.HasFlag (TextStyle.Faint))
                {
                    sgr.Add (2); // set Faint
                }
            }
            else
            {
                sgr.Add (22);  // unset Bold / Faint
            }

            if (textStyle.HasFlag (TextStyle.Italic))
            {
                sgr.Add (3);    // set Italic
            }
            else
            {
                sgr.Add (23);   // unset Italic
            }

            if (textStyle.HasFlag (TextStyle.Underline))
            {
                sgr.Add (4);    // set Underline
            }
            else
            {
                sgr.Add (24);   // unset Underline
            }

            if (textStyle.HasFlag (TextStyle.Blink))
            {
                sgr.Add (5);    // set Blink
            }
            else
            {
                sgr.Add (25);   // unset Blink
            }

            if (textStyle.HasFlag (TextStyle.Reverse))
            {
                sgr.Add (7);    // set Reverse
            }
            else
            {
                sgr.Add (27);   // unset Reverse
            }

            if (textStyle.HasFlag (TextStyle.Strikethrough))
            {
                sgr.Add (9);    // set Strikethrough
            }
            else
            {
                sgr.Add (29);   // unset Strikethrough
            }
        }
        if (sgr.Count == 0)
        {
            return;
        }

        output.Append ("\x1b[");
        output.Append (string.Join (';', sgr));
        output.Append ('m');
    }

[tig]

Great stuff! My heart would be warmed if y'all took care of this issue by submitting a PR. 😘