Rename `ColorScheme` to `Scheme` and Migrate `Colors` to `ConfigurationManager.Themes`

[tig]

As discussed in:

• Master Issue for Updating Color/Attribute System #457
• Add Non-Color Attributes (Bold, Italic, Underline, etc.) to Attributes #4058
• Attribute System Should honor terminal settings #2381

The names ColorScheme and Colors in Terminal.Gui are misleading because they imply color-only functionality, yet Attributes within ColorScheme will soon support non-color styles (e.g., Bold, Italic, per #4058). The static Colors dictionary (Terminal.Gui.Colors.ColorSchemes) causes thread-safety issues and lacks type safety, making it unsuitable for modern theme management. I propose:

• Rename ColorScheme to Scheme to reflect its role in defining both color and non-color visual styles.

• Remove Colors and migrate its functionality to ConfigurationManager.Themes, leveraging Terminal.Gui’s JSON-driven theme management system.

This issue focuses on these naming and structural changes, keeping #457 as the master issue for the broader ColorSchemes redesign, including per-view defaults and terminal settings (#2381). Backward compatibility for Colors is not required, simplifying the migration.

Current State

• ColorScheme is a class defining Attributes (Normal, HotNormal, Focus, HotFocus, Disabled) used by views for styling.

• Colors is a static dictionary with string keys (e.g., "Base", "Dialog", "Menu", "Error"), which is prone to threading issues and not configurable by users.

• ConfigurationManager.Themes manages themes (e.g., “Light”, “Dark”) as a non-static dictionary of ColorScheme instances, loaded from JSON configs (e.g., .tui/config.json, embedded config.json). It supports user-defined themes, runtime overrides (e.g., ConfigurationManager.RuntimeConfig = """{ "Theme": "Light" }"""), and a robust API for theme management (e.g., adding, retrieving, applying themes).

• Current ConfigurationManager.Themes JSON structure:

{
  "Dark": {
    "ColorSchemes": [
      {
        "TopLevel": {
          "Normal": {
            // Color and attribute definitions
          }
...

Proposed Changes

• Rename ColorScheme to Scheme:

  • Update the class name to Scheme for clarity and brevity.

  • Refactor all references in the codebase (e.g., View.ColorScheme, ConfigurationManager.Themes, ThemeManager).

  • Update the tui-config-schema.json to use Schemes instead of ColorSchemes in theme definitions (https://gui-cs.github.io/Terminal.GuiV2Docs/schemas/tui-config-schema.json).

• Remove Colors and Migrate to ConfigurationManager.Themes:

  • Eliminate the static Terminal.Gui.Colors class and its ColorSchemes dictionary.

  • Migrate default schemes (Base, Dialog, Menu, Error) to ConfigurationManager.Themes, storing them as Scheme instances in the embedded config.json or user .tui configs.

  • Update ThemeManager to store and manage Scheme instances, ensuring seamless integration with the existing theme management API.

  • Example updated JSON structure:

{
  "Dark": {
    "Schemes": [
      {
        "TopLevel": {
          "Normal": {
            // Color and attribute definitions
          }
...

• Support Theme Inheritance:

  • Ensure ConfigurationManager.Themes supports theme inheritance, where views default to their SuperView’s theme if unspecified, per Master Issue for Updating Color/Attribute System #457’s hierarchy model.

• Support Future Terminal Settings:

  • Design ConfigurationManager.Themes to integrate with user terminal colors (e.g., $PSStyle or $TERM settings) when implemented in Attribute System Should honor terminal settings #2381, though this is out of scope here.

• Documentation and Testing:

  • Update documentation, samples (e.g., UICatalog, Example.cs), and API docs to reflect Scheme and ConfigurationManager.Themes.

  • Fix unit tests to remove Colors dependencies and validate ThemeManager integration.

Benefits

• Clarifies that Scheme supports both colors and non-color attributes (aligning with Add Non-Color Attributes (Bold, Italic, Underline, etc.) to Attributes #4058).

• Resolves threading issues by replacing static Colors with ConfigurationManager’s non-static, JSON-driven system.

• Enables user-defined themes via .tui configs, enhancing flexibility and customization.

• Supports Master Issue for Updating Color/Attribute System #457’s goal of a consistent, scalable styling system and prepares for Attribute System Should honor terminal settings #2381’s terminal settings integration.

Tasks

• Refactor ColorScheme to Scheme across the codebase and JSON schema.

• Remove Terminal.Gui.Colors and migrate its schemes to ConfigurationManager.Themes.

• Update documentation, samples, and UICatalog to use Scheme and ConfigurationManager.Themes.

• Fix unit tests to eliminate Colors dependencies and validate ThemeManager integration.

Related Issues

• Add Non-Color Attributes (Bold, Italic, Underline, etc.) to Attributes #4058: Add non-color attributes to Attributes (supporting styles like Bold, Italic).

• Master Issue for Updating Color/Attribute System #457: Master issue for ColorSchemes redesign, including per-view defaults and terminal settings.

• Attribute System Should honor terminal settings #2381: Honor user terminal settings (mappings to Scheme attributes).

• Truecolors (direct RGB colors) support #48: Truecolors support (relevant for advanced color handling).

Open Questions

• Are there edge cases in ThemeManager that need addressing for Scheme migration?

• Should ConfigurationManager.Themes include additional validation for user-defined themes?

• Should the JSON structure for Schemes be flattened or simplified (e.g., remove nested array)?

Community feedback on the rename, migration approach, and ThemeManager integration is welcome!

[tig]

Following up on the previous comment about improving the ConfigurationManager.Themes API, I want to explore two new proposals for accessing Scheme instances, leveraging the fact that ConfigurationManager always enforces a "Default" theme. These aim to address the type safety and usability issues with the initial suggestion (Themes["Default"]["Schemes"]["Menu"]) and the proposed GetDefaultScheme("Menu"). Inspiration comes from existing patterns like DefaultBorderStyle in FrameView.cs (https://github.com/gui-cs/Terminal.Gui/blob/v2_develop/Terminal.Gui/Views/FrameView.cs).

Current Context

The goal is to replace:

ColorScheme = Colors.ColorSchemes["Menu"];

with a type-safe, intuitive API using ConfigurationManager.Themes. The initial proposal:

Scheme = Themes["Default"]["Schemes"]["Menu"];

was clunky, not type-safe, and required specifying "Default". A suggested improvement was:

Scheme = Themes.GetDefaultScheme("Menu");

However, two new approaches could further simplify and align with Terminal.Gui’s design patterns.

Proposal 1: Type-Safe SchemeNames with Themes.Default.Schemes

This approach uses a type-safe SchemeNames class and a Default theme accessor:

public class Menu : View {
    public Menu() {
        base.Scheme = Themes.Default.Schemes.Menu;
    }
}

public static class SchemeNames {
    public const string Menu = "Menu";
    public const string Dialog = "Dialog";
    public const string TopLevel = "TopLevel";
    public const string Error = "Error";
}

Analysis

• Benefits:

  • Type Safety: SchemeNames.Menu ensures valid scheme names, reducing runtime errors from mistyped strings (e.g., “Menus”).
  • Intuitive: Themes.Default.Schemes.Menu is concise and clearly indicates the default theme’s scheme for “Menu”.
  • Leverages Default Theme: Since ConfigurationManager guarantees a "Default" theme (set via config.json or RuntimeConfig), Themes.Default aligns with this enforcement.
  • Scalable: SchemeNames can include standard schemes (Menu, Dialog, etc.) while allowing user-defined names via string fallback if needed.

• Challenges:

  • Static SchemeNames Maintenance: Adding new standard schemes requires updating SchemeNames, which may not scale for user-defined themes.
  • JSON Structure Dependency: The current JSON structure ("Dark": { "ColorSchemes": [ { "TopLevel": ... } ] }) uses a nested array, requiring Themes.Default.Schemes to navigate this complexity (e.g., find the scheme by name).
  • Ambiguity for Non-Default Themes: Developers may need schemes from other themes (e.g., Themes["Dark"].Schemes.Menu), which this API doesn’t directly support.

• Implementation:

  • Add a Default property to ConfigurationManager.Themes that returns the active theme (e.g., resolved from ConfigurationManager.RuntimeConfig or "Theme": "Light" in config.json).
  • Implement a Schemes accessor on the Theme class, mapping scheme names to Scheme instances.
  • Example:

public static class ConfigurationManager {
    public static ThemeManager Themes { get; }
}

public class ThemeManager {
    public Theme Default => GetActiveTheme() ?? Themes["Light"];
    public Theme this[string themeName] => Themes[themeName];
}

public class Theme {
    public SchemeDictionary Schemes { get; } // Maps names to Scheme instances
}

public class SchemeDictionary {
    public Scheme Menu => Get(SchemeNames.Menu);
    public Scheme Dialog => Get(SchemeNames.Dialog);
    public Scheme this[string name] => Get(name);
}

• Update tui-config-schema.json to support Schemes (per Rename ColorScheme to Scheme and Migrate Colors to ConfigurationManager.Themes #4057’s rename task).

Proposal 2: Static DefaultScheme Property per View

Inspired by DefaultBorderStyle in FrameView.cs, this approach defines a static DefaultScheme property for each view type:

public class Menu : View {
    public Menu() {
        base.Scheme = DefaultScheme;
    }

    [SerializableConfigurationProperty (Scope = typeof (ThemeScope))]
    public static Scheme DefaultScheme { get; set; }
}

Analysis

• Benefits:

  • View-Specific Defaults: Each view type (e.g., Menu, Dialog, FrameView) can have a tailored default scheme, configurable via ConfigurationManager.
  • Configuration Integration: The [SerializableConfigurationProperty] attribute allows DefaultScheme to be set in JSON configs (e.g., .tui/config.json), similar to FrameView.DefaultBorderStyle.
  • Simplicity: base.Scheme = DefaultScheme is extremely concise and intuitive for developers.
  • Consistency with Existing Patterns: Mirrors DefaultBorderStyle, leveraging Terminal.Gui’s configuration system for theme persistence.

• Challenges:

  • Per-View Overhead: Every view class needs a DefaultScheme property, increasing maintenance and risking inconsistent defaults across views.
  • Configuration Complexity: Developers must configure DefaultScheme for each view type in config.json (e.g., "Menu.DefaultScheme": { ... }), which could be verbose compared to centralized theme management.
  • Limited Flexibility: Hardcoding the default scheme per view doesn’t easily support switching themes (e.g., from “Default” to “Dark”) without additional logic.
  • Type Safety: Still relies on ConfigurationManager mapping scheme names correctly, though less error-prone than string-based access.

• Implementation:

  • Add DefaultScheme properties to view classes (e.g., Menu, Dialog), annotated with [SerializableConfigurationProperty].
  • Map these properties to ConfigurationManager.Themes schemes in the JSON config.
  • Example JSON:

{
  "Themes": {
    "Default": {
      "Schemes": {
        "Menu": { "Normal": { /* Attributes */ } },
        "Dialog": { "Normal": { /* Attributes */ } }
      }
    },
    "Menu.DefaultScheme": "Default.Schemes.Menu",
    "Dialog.DefaultScheme": "Default.Schemes.Dialog"
  }
}

• Ensure ConfigurationManager resolves DefaultScheme to the appropriate Scheme instance from the active theme.

Comparison and Recommendation

• Proposal 1 (Themes.Default.Schemes.Menu):

  • Pros: Type-safe, centralized, leverages ConfigurationManager’s default theme, supports theme switching.
  • Cons: Requires JSON structure updates, less view-specific than DefaultScheme.
  • Best For: General-purpose theme access across all views, with a focus on type safety and scalability.

• Proposal 2 (DefaultScheme):

  • Pros: View-specific, extremely concise, integrates with ConfigurationManager’s serialization.
  • Cons: Higher maintenance, less flexible for theme switching, configuration-heavy.
  • Best For: Views with fixed, well-defined styling needs, where developers prioritize simplicity.

Recommendation: Prefer Proposal 1 (Themes.Default.Schemes.Menu) for its type safety, alignment with ConfigurationManager.Themes, and flexibility for theme switching. It better supports #4057’s goal of a scalable, centralized styling system and prepares for #2381 (terminal settings) by tying schemes to the active theme. However, Proposal 2 (DefaultScheme) could be a complementary feature for specific views (e.g., Menu, Dialog) where default styling is critical, similar to DefaultBorderStyle.

Refined API Proposal

To combine the strengths of both approaches, I propose:

1. Primary API: Themes.Default.Schemes:

public class Menu : View {
    public Menu() {
        base.Scheme = Themes.Default.Schemes.Menu;
    }
}

• Implement Themes.Default to return the active theme (guaranteed by ConfigurationManager).
• Use SchemeNames for type-safe access to standard schemes.

2. Optional API: GetDefaultScheme:

Scheme = Themes.GetDefaultScheme(SchemeNames.Menu);

• Supports string-based access for user-defined schemes or legacy code.

3. View-Specific Defaults (Selective):

public class Menu : View {
    [SerializableConfigurationProperty (Scope = typeof (ThemeScope))]
    public static Scheme DefaultScheme { get; set; } = Themes.Default.Schemes.Menu;
}

• Add DefaultScheme to key views (e.g., Menu, Dialog, FrameView), initialized to Themes.Default.Schemes.<Name>.
• Allow configuration via JSON, but default to centralized theme schemes.

4. Simplified JSON Structure:

{
  "Themes": {
    "Default": {
      "Schemes": {
        "Menu": { "Normal": { /* Attributes */ } },
        "Dialog": { "Normal": { /* Attributes */ } }
      }
    }
  }
}

• Flatten the Schemes array in tui-config-schema.json for direct access.

Updates to #4057 Tasks

To support this API, update #4057 tasks:

• Modify: “Refactor ColorScheme to Scheme across the codebase and JSON schema” to include implementing Themes.Default.Schemes and GetDefaultScheme.

• Add: “Implement SchemeNames class for type-safe scheme access.”

• Add: “Simplify Schemes JSON structure in tui-config-schema.json to support direct access (e.g., "Schemes": { "Menu": ... }).”

• Update: “Update documentation, samples, and UICatalog” to include examples of Themes.Default.Schemes.Menu and DefaultScheme usage.

Open Questions

• Primary API: Should Themes.Default.Schemes.Menu be the default, or is GetDefaultScheme preferred for flexibility?

• View-Specific Defaults: Which views (e.g., Menu, Dialog) need DefaultScheme properties, and how should they be configured in JSON?

• Type Safety vs. Flexibility: Should SchemeNames be mandatory, or allow string-based fallbacks for user-defined schemes?

• JSON Structure: Does flattening Schemes break existing theme configs, or can we migrate seamlessly?

Next Steps

• Prototype Themes.Default.Schemes and GetDefaultScheme in ConfigurationManager.Themes.

• Test DefaultScheme on key views (e.g., Menu, Dialog) with JSON configs.

• Update UICatalog to showcase both APIs (e.g., Themes.Default.Schemes.Menu, Menu.DefaultScheme).

• Validate JSON structure changes with existing themes in config.json.

This refined API balances type safety, usability, and alignment with ConfigurationManager’s default theme enforcement. Community feedback on the proposed APIs, JSON structure, and view-specific defaults is welcome!

[tig]

My latest proposal on lexicon & taxonomy for the things related to all this:

Term	Meaning
Configuration	The system that loads and manages application runtime settings from external sources (e.g., config.json).
Settings	Specific global runtime options managed by ConfigurationManager (e.g., the selected Theme, keybindings, system behavior).
Themes	A collection of named Theme definitions, each of which bundles visual and layout settings.
Theme	A single named instance containing specific appearance settings (e.g., "Default", "Dark").
Scheme	A mapping from VisualRole to Attribute. Defines how visual elements should look based on their semantic purpose.
VisualRole	The semantic role/purpose of a visual element inside a View (e.g., Normal, Focus, HotFocus, Active, Disabled, ReadOnly).
Attribute	Defines the concrete visual styling for a visual element, including Foreground color, Background color, and (soon) TextStyle.
Color	Base terminal color (part of the color palette; supports TrueColor and named values like White, Black, Cyan, etc.).
ForegroundColor	A property of Attribute that describes the color of foreground text.
BackgroundColor	A property of Attribute that describes the color of background text.
Style	(Coming soon) A property of Attribute that captures additional font-like hints such as bold, italic, underline, beyond color.

Thoughts & comments?

Key areas for debate are Scheme and VisualRole, IMO.

[tig]

Here's why VisualRole is important:

Today in View:

protected virtual Attribute GetNormalColor ()
{
    return ColorScheme?.Normal ?? Colors.Base.Normal;
}

protected virtual Attribute GetFocusColor ()
{
    return ColorScheme?.Focus ?? Colors.Base.Focus;
}

// etc...

What I'm proposing instead:

namespace Terminal.Gui;

/// <summary>
/// Represents the semantic visual role of a visual element rendered by a View.
/// </summary>
/// <remarks>
/// A single View may render multiple elements, each associated with a different <see cref="VisualRole"/>.  
/// VisualRoles describe the intended purpose of the element (e.g., Normal text, Focused item, Active selection).
/// </remarks>
public enum VisualRole
{
    /// <summary>
    /// The default visual role for unfocused, unselected, enabled elements.
    /// </summary>
    Normal,

    /// <summary>
    /// The visual role for hot elements (typically those with HotKey indicators) that are unfocused.
    /// </summary>
    HotNormal,

    /// <summary>
    /// The visual role when the element is focused.
    /// </summary>
    Focus,

    /// <summary>
    /// The visual role when the element is focused and has an active HotKey indicator.
    /// </summary>
    HotFocus,

    /// <summary>
    /// The visual role for elements that are active or selected (e.g., selected item in a ListView).
    /// </summary>
    Active,

    /// <summary>
    /// The visual role for elements that are active and have a HotKey indicator.
    /// </summary>
    HotActive,

    /// <summary>
    /// The visual role for elements that are disabled and not interactable.
    /// </summary>
    Disabled,

    /// <summary>
    /// The visual role for elements that are normally editable but currently read-only.
    /// </summary>
    ReadOnly
}

/// <summary>
/// Gets the <see cref="Attribute"/> associated with a specified <see cref="VisualRole"/>.
/// </summary>
/// <param name="role">The semantic <see cref="VisualRole"/> describing the element being rendered.</param>
/// <returns>The corresponding <see cref="Attribute"/> from the <see cref="Scheme"/>.</returns>
protected virtual Attribute GetAttributeForRole (VisualRole role)
{
    Scheme scheme = Scheme ?? Themes.Default.Schemes.Base;

    return role switch
    {
        VisualRole.Normal => scheme.Normal,
        VisualRole.HotNormal => scheme.HotNormal,
        VisualRole.Focus => scheme.Focus,
        VisualRole.HotFocus => scheme.HotFocus,
        VisualRole.Active => scheme.Active,
        VisualRole.HotActive => scheme.HotActive,
        VisualRole.Disabled => scheme.Disabled,
        VisualRole.ReadOnly => scheme.ReadOnly,
        _ => scheme.Normal
    };
}

Fight me on this please!

[tig]

One thing I've remembered is, that for some reason, we currently ALWAYS return Disabled if View.Enabled == false.

    public virtual Attribute GetHotNormalColor ()
    {
        Attribute currAttribute = Scheme?.Normal ?? Attribute.Default;
        var newAttribute = new Attribute ();
        CancelEventArgs<Attribute> args = new (in currAttribute, ref newAttribute);
        GettingHotNormalColor?.Invoke (this, args);

        if (args.Cancel)
        {
            return args.NewValue;
        }

        Scheme? cs = Scheme ?? new ();

        return Enabled ? GetColor (cs.HotNormal) : cs.Disabled;
    }

I think this is cray. I plan on revising this and make it so View.Draw does the right thing instead.

Am I missing something?

[BDisp]

What's the meaning of this?

if (args.Cancel)
        {
            return args.NewValue;
        }

This is really a cancel. If it's then the user canceled and choose to not change at all and preserving the currAttribute.

If it's handled by the user then the newAttribute is returned otherwise will return Enabled ? GetColor (cs.HotNormal) : cs.Disabled;.

I think it's really cray 😃

[tig]

What's the meaning of this?

if (args.Cancel)
{
return args.NewValue;
}
This is really a cancel. If it's then the user canceled and choose to not change at all and preserving the currAttribute.

No. I believe args.Cancel == true means "stop processing". And, since CancelEventArgs<type> defines NewValue as ref, the handler is free to modify it.

return Enabled ? GetColor (cs.HotNormal) : cs.Disabled;

This is the part I'm asking about. We have a VisualRole for Enabled/Disabled. Why are we conflating the HotNormal and Disabled visual roles in this code?

[BDisp]

What's the meaning of this?
if (args.Cancel)
{
return args.NewValue;
}
This is really a cancel. If it's then the user canceled and choose to not change at all and preserving the currAttribute.

No. I believe args.Cancel == true means "stop processing". And, since CancelEventArgs<type> defines NewValue as ref, the handler is free to modify it.

That why I think it's more appropriate to use Handled for the NewValue being accept. It mean that the user has handling the new value and the base class must return it.

return Enabled ? GetColor (cs.HotNormal) : cs.Disabled;

This is the part I'm asking about. We have a VisualRole for Enabled/Disabled. Why are we conflating the HotNormal and Disabled visual roles in this code?

That because a disabled view can't receive key and mouse events and also although it's visible it must be draw with a color scheme that constate it's disabled. If you use a Normal or HotNormal why you want to realce the hot key if the user can't iterate with it?

[tig]

That why I think it's more appropriate to use Handled for the NewValue being accept. It mean that the user has handling the new value and the base class must return it.

Right!

return Enabled ? GetColor (cs.HotNormal) : cs.Disabled;

This is the part I'm asking about. We have a VisualRole for Enabled/Disabled. Why are we conflating the HotNormal and Disabled visual roles in this code?

That because a disabled view can't receive key and mouse events and also although it's visible it must be draw with a color scheme that constate it's disabled. If you use a Normal or HotNormal why you want to realce the hot key if the user can't iterate with it?

But GetNormalColor does this too:

    public virtual Attribute GetNormalColor ()
    {
...
        return Enabled ? GetColor (cs.Normal) : disabled;
    }

I think you're on to something though. Please explain further if you have clarity. Thanks!