Namespace Terminal.Gui.Configuration

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

Terminal.Gui.Configuration provides a robust system for managing application settings, themes, and runtime configuration. This namespace includes the configuration manager, property attributes, and scoping mechanisms that allow applications to persist and load settings from various sources.

The configuration system supports multiple scopes (Settings, Themes, AppSettings) and sources (user directory, application directory, etc.), enabling flexible deployment and customization scenarios. It also provides theme inheritance and hot-reloading capabilities for dynamic configuration updates.

Key Components

ConfigurationManager: Central system for loading, applying, and managing configuration
ConfigProperty: Attribute for marking properties as configurable
Scopes: Settings, Theme, and AppSettings contexts
Sources: Multiple storage locations for configuration persistence

Example Usage

// Mark a property as configurable
[ConfigProperty]
public static bool MyFeatureEnabled { get; set; } = true;

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

Deep Dive

Configuration Management Deep Dive - Comprehensive configuration system documentation

Classes

AppSettingsScope: The Scope<T> class for application-defined configuration settings.

ConfigProperty: Holds a property's value and the PropertyInfo that allows ConfigurationManager to retrieve and apply the property's value.

ConfigurationManager

Provides settings and configuration management for Terminal.Gui applications. See the Configuration Deep Dive for more information: https://gui-cs.github.io/Terminal.Gui/docs/config.html.

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://gui-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.

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

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).

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.

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.

Enums