Table of Contents

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:

  1. Application directory (appSettings.json)
  2. User directory (~/.tui/)
  3. Environment variables
  4. 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;

See Also

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

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.

Edit this page