Namespace Terminal.Gui.Configuration

Configuration management, themes, and persistent settings.

The Configuration namespace provides comprehensive configuration management for Terminal.Gui applications.

Key Types

ConfigurationManager - Central system for loading and applying configuration
ConfigurationPropertyAttribute - Marks properties as configurable
Scope - Configuration contexts (Settings, Themes, AppSettings)
ThemeManager - Theme loading and application

Configuration Scopes

Scope	Purpose
Settings	Runtime behavior settings
Themes	Visual styling and color schemes
AppSettings	Application-specific settings

Configuration Sources

Configuration is loaded from multiple locations in priority order:

Application directory (appSettings.json)
User directory (~/.tui/)
Environment variables
Code-based defaults

Example

// Enable configuration from all sources
ConfigurationManager.Enable (ConfigLocations.All);

// Access theme
ThemeManager.Theme = "Dark";

// Mark a property as configurable
[ConfigurationProperty (Scope = typeof (SettingsScope))]
public static bool MyFeature { get; set; } = true;

Users can set Terminal.Gui settings on a global or per-application basis by providing JSON formatted configuration files. The configuration files can be placed in at .tui folder in the user's home directory (e.g. C:/Users/username/.tui, or /usr/username/.tui), the folder where the Terminal.Gui application was launched from (e.g. ./.tui ), or as a resource within the Terminal.Gui application's main assembly.

Settings are defined in JSON format, according to this schema: https://tui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json

Settings that will apply to all applications (global settings) reside in files named config.json. Settings that will apply to a specific Terminal.Gui application reside in files named appname.config.json, where appname is the assembly name of the application (e.g. UICatalog.config.json).

Settings are applied using the precedence defined in ConfigLocations.

Configuration Management is based on static properties decorated with the ConfigurationPropertyAttribute. Since these properties are static, changes to configuration settings are applied process-wide.

Configuration Management is disabled by default and can be enabled by setting calling Enable(ConfigLocations).

See the UICatalog example for a complete example of how to use ConfigurationManager.

ConfigurationManagerEventArgs: Event arguments for the ConfigurationManager events.

ConfigurationManagerNotEnabledException: The exception that is thrown when a ConfigurationManager API is called but the configuration manager is not enabled.

ConfigurationPropertyAttribute: An attribute indicating a property is managed by ConfigurationManager.

DeepCloner: Provides deep cloning functionality for Terminal.Gui configuration objects. Creates a deep copy of an object by recursively cloning public properties, handling collections, arrays, dictionaries, and circular references.

DialogSettings: Settings POCO for Dialog visual defaults (ThemeScope).

DriverSettings: Settings POCO for driver-level configuration (SettingsScope).

FileDialogSettings: Settings POCO for FileDialog defaults (SettingsScope).

FileDialogStyleSettings: Settings POCO for FileDialogStyle defaults (SettingsScope).

FrameViewSettings: Settings POCO for FrameView defaults (ThemeScope).

GlyphSettings: Settings POCO for Glyphs defaults (ThemeScope).

HexViewSettings: Settings POCO for HexView defaults (ThemeScope).

KeyArrayJsonConverter: Serializes and deserializes Key arrays as JSON string arrays (e.g. ["Ctrl+A", "Home"]). Each element uses ToString() for writing and TryParse(string, out Key) for reading.

KeyJsonConverter: Support for Key in JSON in the form of "Ctrl-X" or "Alt-Shift-F1".

KeySettings: Settings POCO for Key defaults (SettingsScope).

LinearRangeSettings: Settings POCO for LinearRangeDefaults defaults (ThemeScope).

MecSchemeManager: MEC-backed implementation of ISchemeManager. During the transition period, this delegates to the existing static SchemeManager for scheme data.

MecThemeManager: MEC-backed implementation of IThemeManager. During the transition period (PR #5411), this delegates writes to the legacy static ThemeManager because the runtime theme/scheme dictionary is still owned by Settings. The Phase A2 work in #5416 will let this type own the theme/scheme data directly.

MenuBarSettings: Settings POCO for MenuBar defaults.

MenuSettings: Settings POCO for Menu defaults (ThemeScope).

MessageBoxSettings: Settings POCO for MessageBox visual defaults (ThemeScope).

MouseFlagsArrayJsonConverter: Serializes and deserializes MouseFlags arrays as JSON string arrays (e.g. ["LeftButtonPressed+Shift", "LeftButtonReleased"]).

NerdFontsSettings: Settings POCO for Terminal.Gui.Text.NerdFonts defaults (ThemeScope).

PopoverMenuSettings: Settings POCO for PopoverMenu defaults (SettingsScope).

SchemeManager: Holds the Schemes that define the Attributes that are used by views to render themselves. A Scheme is a mapping from VisualRoles (such as Focus) to Attributes. A Scheme defines how a View should look based on its purpose (e.g. Menu or Dialog).

Scope<T>

Defines a configuration settings scope. Classes that inherit from this abstract class can be used to define scopes for configuration settings. Each scope is a JSON object that contains a set of configuration settings.

When constructed, the dictionary will be populated with uninitialized configuration properties for the scope (HasValue will be false).

SelectorBaseSettings: Settings POCO for SelectorBase defaults (ThemeScope).

SettingsScope: INTERNAL: The root object of Terminal.Gui configuration settings / JSON schema. Contains only properties attributed with SettingsScope.

SourcesManager: Manages the ConfigurationManager Sources and provides the API for loading them. Source is a location where a configuration can be stored. Sources are defined in ConfigLocations.

StatusBarSettings: Settings POCO for StatusBar defaults (ThemeScope).

TextFieldSettings: Settings POCO for TextField defaults (ThemeScope).

TextViewSettings: Settings POCO for TextView defaults (ThemeScope).

ThemeChanges: Static facade that raises when the active theme — or any setting that affects views reading from *Settings.Defaults — has changed. Provided for consumers that cannot take a IThemeManager dependency (typically View subclasses constructed before an IApplication is available).

ThemeManager: Manages Themes.

ThemeScope: The root object for a Theme. A Theme is a set of settings that are applied to the running Application as a group.

ThemeSettings: Settings POCO for theme selection (SettingsScope). Controls which theme is active and what themes are available.

TraceSettings: Settings POCO for Trace defaults (SettingsScope).

TuiConfigurationBuilder: Builds and manages a Terminal.Gui MEC-based configuration, loading from all standard sources in the correct precedence order.

TuiConfigurationExtensions: Extension methods for IConfigurationBuilder that add Terminal.Gui configuration sources in the correct precedence order (matching the existing SourcesManager behavior).

WindowSettings: Settings POCO for Window visual defaults (ThemeScope).

Interfaces

ISchemeManager: Abstracts color scheme management. Provides access to named schemes.

IThemeManager: Abstracts theme management. Allows switching themes and querying available themes.

Enums

ConfigLocations: Describes the location of the configuration settings. The constants can be combined (bitwise) to specify multiple locations. The more significant the bit, the higher the priority the location, meaning that the last location will override the earlier ones.

Table of Contents