ContextQMD
Back to Terminal Gui

Configuration Management Deep Dive

docfx/docs/config.md

2.0.130.5 KB
Original Source

Configuration Management Deep Dive

Terminal.Gui provides a comprehensive configuration system that allows users and developers to customize application behavior and appearance through JSON configuration files. The ConfigurationManager enables persistent settings, themes, and application-specific preferences.

Table of Contents

Overview

The ConfigurationManager provides:

  • Persistent Settings - User preferences stored in JSON files
  • Theme System - Named collections of visual settings
  • Scheme Management - Color and text style definitions
  • Configuration Precedence - Layered configuration from multiple sources
  • Runtime Configuration - In-memory configuration without files
  • AOT Compatible - Works with Native AOT compilation

Key Features

  • JSON-based configuration with schema validation
  • Multiple configuration locations (user home, app directory, resources)
  • Process-wide settings using static properties
  • Built-in themes (Default, Dark, Light, etc.)
  • Custom glyphs and Unicode characters
  • Event-driven configuration changes

Getting Started

Enabling Configuration

ConfigurationManager is disabled by default and must be explicitly enabled:

csharp
using Terminal.Gui.Configuration;

class Program
{
    static void Main()
    {
        // Enable configuration with all sources
        ConfigurationManager.Enable(ConfigLocations.All);

        using IApplication app = Application.Create();
        app.Init();
        // ... rest of app
    }
}

Quick Example

csharp
// Enable configuration
ConfigurationManager.Enable(ConfigLocations.All);

// Listen for configuration changes
ConfigurationManager.Applied += (sender, e) => 
{
    Console.WriteLine("Configuration applied!");
};

// Switch themes
ThemeManager.Theme = "Dark";
ConfigurationManager.Apply();

Configuration Scopes

Terminal.Gui uses three configuration scopes, each serving a different purpose:

1. SettingsScope

System-level settings that affect Terminal.Gui behavior. Only Terminal.Gui library developers can define SettingsScope properties.

csharp
[ConfigurationProperty(Scope = typeof(SettingsScope))]
public static bool Force16Colors { get; set; } = false;

Examples:

  • Application.DefaultKeyBindings (e.g. Command.Quit) - Default keys for application-level commands
  • Driver.Force16Colors - Force 16-color mode
  • Key.Separator - Character separating keys in key combinations

2. ThemeScope

Visual appearance settings that can be themed. Only Terminal.Gui library developers can define ThemeScope properties.

csharp
[ConfigurationProperty(Scope = typeof(ThemeScope))]
public static LineStyle DefaultBorderStyle { get; set; } = LineStyle.Single;

Examples:

  • Window.DefaultBorderStyle - Default border style for windows
  • Dialog.DefaultShadow - Default shadow style for dialogs
  • xref:Terminal.Gui.Drawing.Schemes - Color schemes for the theme

3. AppSettingsScope (Default)

Application-specific settings. Application developers can define AppSettingsScope properties for their apps.

csharp
[ConfigurationProperty] // AppSettingsScope is default
public static string MyAppSetting { get; set; } = "default value";

Important:

Configuration Locations and Precedence

Configuration is loaded from multiple locations with increasing precedence (higher numbers override lower):

ConfigLocations Enum

ConfigLocations specifies where configuration can be loaded from:

  1. ConfigLocations.HardCoded (Lowest Precedence)

    • Default values in code (static property initializers)
    • Always available, even when ConfigurationManager is disabled

  2. ConfigLocations.LibraryResources

    • Settings in Terminal.Gui.dll resources (Terminal.Gui.Resources.config.json)
    • Defines default themes and settings for the library

  3. ConfigLocations.AppResources

    • App-specific resources (MyApp.Resources.config.json or Resources/config.json)
    • Embedded in the application assembly

  4. ConfigLocations.GlobalHome

    • Global file in user's home directory (~/.tui/config.json)

  5. ConfigLocations.GlobalCurrent

    • Global file in current directory (./.tui/config.json)

  6. ConfigLocations.AppHome

    • App-specific file in user's home directory (~/.tui/MyApp.config.json)

  7. ConfigLocations.AppCurrent

    • App-specific file in current directory (./.tui/MyApp.config.json)

  8. ConfigLocations.Env

    • Settings from the TUI_CONFIG environment variable
    • Useful for container environments and CI/CD pipelines

  9. ConfigLocations.Runtime (Highest Precedence)

Precedence Diagram

mermaid
graph TD
    A[1. Hard-coded Defaults] --> B[2. Library Resources]
    B --> C[3. App Resources]
    C --> D[4. Global Home Directory]
    D --> E[5. Global Current Directory]
    E --> F[6. App Home Directory]
    F --> G[7. App Current Directory]
    G --> H[8. Environment Variable TUI_CONFIG]
    H --> I[9. Runtime Config - Highest Priority]
    
    style A fill:#f9f9f9
    style I fill:#90EE90

File Locations

Global Settings (config.json):

  • Windows: C:\Users\username\.tui\config.json
  • macOS/Linux: ~/.tui/config.json or ./.tui/config.json

App-Specific Settings (AppName.config.json):

  • Windows: C:\Users\username\.tui\UICatalog.config.json
  • macOS/Linux: ~/.tui/UICatalog.config.json or ./.tui/UICatalog.config.json

Environment Variable (TUI_CONFIG):

bash
# Linux/macOS
export TUI_CONFIG='{"Application.DefaultKeyBindings": {"Quit": {"All": ["Ctrl+Q"]}}}'

# Windows PowerShell
$env:TUI_CONFIG='{"Application.DefaultKeyBindings": {"Quit": {"All": ["Ctrl+Q"]}}}'

Themes and Schemes

Theme System

A Theme is a named collection of visual settings bundled together. Terminal.Gui includes several built-in themes.

Built-in Themes

  • Default - The default Terminal.Gui theme (matches hard-coded defaults)
  • Dark - Dark color scheme with heavy borders
  • Light - Light color scheme
  • TurboPascal 5 - Classic Turbo Pascal IDE colors
  • And more - See Terminal.Gui/Resources/config.json for all built-in themes

Using Themes

csharp
// Get current theme
ThemeScope currentTheme = ThemeManager.GetCurrentTheme();

// Get all available themes (null if ConfigurationManager not yet initialized)
ConcurrentDictionary<string, ThemeScope>? themes = ThemeManager.Themes;
if (themes is null)
{
    return; // ConfigurationManager not yet initialized
}

// Get theme names
ImmutableList<string> themeNames = ThemeManager.GetThemeNames();

// Switch themes
ThemeManager.Theme = "Dark";
ConfigurationManager.Apply();

// Listen for theme changes
ThemeManager.ThemeChanged += (sender, e) => 
{
    // e.Value is the new theme name
    // Update UI based on new theme
};

Scheme System

A Scheme defines the colors and text styles for a specific UI context (e.g., Dialog, Menu, Accent).

See the Scheme Deep Dive for complete details on the scheme system.

Built-in Schemes

Schemes enum defines the standard schemes:

  • Base - Default for most views
  • Accent - Secondary/alternate scheme for visual distinction (opaque, derived from Base)
  • Dialog - Dialogs and message boxes
  • Menu - Menus and status bars
  • Error - Error messages and dialogs

Working with Schemes

csharp
// Get all schemes for current theme
Dictionary<string, Scheme?> schemes = SchemeManager.GetSchemesForCurrentTheme();

// Get specific scheme
Scheme dialogScheme = SchemeManager.GetScheme(Schemes.Dialog);

// Get scheme names
ImmutableList<string> schemeNames = SchemeManager.GetSchemeNames();

// Add custom scheme
SchemeManager.AddScheme("MyScheme", new Scheme
{
    Normal = new Attribute(Color.White, Color.Blue),
    Focus = new Attribute(Color.Black, Color.Cyan)
});

Custom Schemes for Individual Views

Any view can be given a named scheme by setting View.SchemeName. When set, GetScheme() looks up that name in the active theme and uses it if found. If the name is not found in the current theme, it falls back through the normal resolution chain (SuperView → "Base" → hard-coded "Base") rather than throwing.

csharp
// 1. Register the custom scheme (call before Application.Init or after ConfigurationManager.Apply)
SchemeManager.AddScheme("Highlight", new Scheme
{
    Normal = new Attribute(Color.Black, Color.BrightYellow),
    Focus = new Attribute(Color.White, Color.BrightYellow)
});

// 2. Assign the scheme name to any view
Label warningLabel = new () { Text = "Warning!" };
warningLabel.SchemeName = "Highlight";

Custom schemes can also be defined in a config JSON file so they are theme-aware:

json
{
  "Themes": [
    {
      "Default": {
        "Schemes": [
          {
            "Highlight": {
              "Normal": { "Foreground": "Black", "Background": "BrightYellow" },
              "Focus":  { "Foreground": "White", "Background": "BrightYellow" }
            }
          }
        ]
      }
    }
  ]
}

When the active theme changes, any view with SchemeName = "Highlight" automatically picks up the new theme's definition of that scheme.

Scheme Resolution Order

View.GetScheme() resolves the scheme for a view using the following priority order:

mermaid
flowchart TD
    A([GetScheme called]) --> B{HasScheme?\nexplicit Scheme set}
    B -- Yes --> C([Return explicit Scheme])
    B -- No --> D{SchemeName set?}
    D -- No --> E{SuperView exists?}
    D -- Yes --> F{TryGetScheme\nSchemeName found?}
    F -- Yes --> G([Return named Scheme])
    F -- No --> H[/Logging.Warning emitted/]
    H --> E
    E -- Yes --> I([Return SuperView.GetScheme])
    E -- No --> J{TryGetScheme\n'Base' found?}
    J -- Yes --> K([Return 'Base' from active theme])
    J -- No --> L([Return hard-coded 'Base'])
PriorityConditionResult
1HasScheme is trueExplicit Scheme instance used as-is
2SchemeName is set and found in active themeNamed scheme returned
3SchemeName is set but not foundLogging.Warning emitted; fallback continues
4SuperView existsSuperView.GetScheme() (recursive)
5"Base" exists in active themeActive theme's "Base" scheme
6(last resort)Hard-coded "Base" — always available

When writing code that looks up a scheme by name, prefer SchemeManager.TryGetScheme() over SchemeManager.GetScheme(string) — the Try variant returns false instead of throwing KeyNotFoundException when the name is not found.

csharp
if (SchemeManager.TryGetScheme("Highlight", out Scheme? scheme))
{
    // use scheme
}

Scheme Structure

Each Scheme maps VisualRole to Attribute:

json
{
  "Accent": {
    "Normal": {
      "Foreground": "BrightGreen",
      "Background": "Black",
      "Style": "None"
    },
    "Focus": {
      "Foreground": "White",
      "Background": "Cyan",
      "Style": "Bold"
    },
    "HotNormal": {
      "Foreground": "Yellow",
      "Background": "Black"
    },
    "HotFocus": {
      "Foreground": "Blue",
      "Background": "Cyan",
      "Style": "Underline"
    },
    "Active": {
      "Foreground": "White",
      "Background": "DarkCyan"
    },
    "HotActive": {
      "Foreground": "Yellow",
      "Background": "DarkCyan"
    },
    "Highlight": {
      "Foreground": "Black",
      "Background": "BrightGreen"
    },
    "Editable": {
      "Foreground": "White",
      "Background": "DarkBlue"
    },
    "ReadOnly": {
      "Foreground": "Gray",
      "Background": "Black"
    },
    "Disabled": {
      "Foreground": "DarkGray",
      "Background": "Black",
      "Style": "Faint"
    }
  }
}

Defining Configuration Properties

Basic Property Definition

Application developers define settings using the ConfigurationPropertyAttribute:

csharp
public class MyApp
{
    [ConfigurationProperty]
    public static string MySetting { get; set; } = "Default Value";
    
    [ConfigurationProperty]
    public static int MaxItems { get; set; } = 100;
}

Requirements:

  • Must be public or internal
  • Must be static
  • Must be a property (not a field)
  • Must have a default value

Property Naming

AppSettings properties are automatically prefixed with the class name to ensure global uniqueness:

csharp
// Code
public class MyApp
{
    [ConfigurationProperty]
    public static string MySetting { get; set; } = "value";
}

// JSON
{
  "AppSettings": {
    "MyApp.MySetting": "value"
  }
}

Scope Specification

Use the Scope parameter to specify non-default scopes (Terminal.Gui library only):

csharp
// SettingsScope - Library-wide settings
[ConfigurationProperty(Scope = typeof(SettingsScope))]
public static bool Force16Colors { get; set; } = false;

// ThemeScope - Visual settings
[ConfigurationProperty(Scope = typeof(ThemeScope))]
public static LineStyle DefaultBorderStyle { get; set; } = LineStyle.Single;

// AppSettingsScope - Application settings (default)
[ConfigurationProperty] // or explicitly: Scope = typeof(AppSettingsScope)
public static string MyAppSetting { get; set; } = "default";

Omit Class Name (Advanced)

For library developers only, use OmitClassName = true for cleaner JSON:

csharp
[ConfigurationProperty(Scope = typeof(ThemeScope), OmitClassName = true)]
public static Dictionary<string, Scheme> Schemes { get; set; } = new();

Loading and Applying Configuration

Enable with Load and Apply

The simplest approach - enable and load in one call:

csharp
ConfigurationManager.Enable(ConfigLocations.All);

This:

  1. Enables ConfigurationManager
  2. Loads configuration from all locations
  3. Applies settings to the application

Granular Control

For more control, use xref:Terminal.Gui.Configuration.ConfigurationManager's Load and Apply() separately:

csharp
// Enable without loading
ConfigurationManager.Enable(ConfigLocations.None);

// Load from specific locations
ConfigurationManager.Load(ConfigLocations.GlobalHome | ConfigLocations.AppResources);

// Apply settings
ConfigurationManager.Apply();

Runtime Configuration

Set configuration directly in code without files:

csharp
ConfigurationManager.RuntimeConfig = @"
{
  ""Application.DefaultKeyBindings.Quit"": ""Ctrl+Q"",
  ""Application.Force16Colors"": true
}";

ConfigurationManager.Enable(ConfigLocations.Runtime);

Reset to Defaults

Reset all settings to hard-coded defaults:

csharp
ConfigurationManager.ResetToHardCodedDefaults();

Events

The ConfigurationManager provides events to track configuration changes:

Applied Event

Raised after configuration is applied to the application:

csharp
ConfigurationManager.Applied += (_, _) => 
{
    // Configuration has been applied
    // Update UI or refresh views
};

Updated Event

Raised after configuration is loaded from a source or reset (before Apply() is called):

csharp
ConfigurationManager.Updated += (_, _) => 
{
    // Configuration has been loaded or reset
    // Inspect ConfigurationManager.Settings if needed
};

ThemeChanged Event

Raised when the active theme changes:

csharp
ThemeManager.ThemeChanged += (_, e) => 
{
    // e.Value is the new theme name
    // Refresh all views to use new theme
    // From within a View, use: App?.Current?.SetNeedsDraw();
    // Or access via IApplication instance: app.Current?.SetNeedsDraw();
};

What Can Be Configured

Application Settings

System-wide settings from SettingsScope:

json
{
  "Application.DefaultKeyBindings.Quit": "Esc",
  "Driver.Force16Colors": false,
  "Application.IsMouseDisabled": false,
  "Application.DefaultKeyBindings.Arrange": "Ctrl+F5",
  "Application.DefaultKeyBindings.NextTabStop": "Tab",
  "Application.DefaultKeyBindings.PreviousTabStop": "Shift+Tab",
  "Application.DefaultKeyBindings.NextTabGroup": "F6",
  "Application.DefaultKeyBindings.PreviousTabGroup": "Shift+F6",
  "Key.Separator": "+"
}

Key Binding Settings

Configurable key bindings use the PlatformKeyBinding format to support platform-aware defaults. See Key Binding Overrides for the full JSON format.

json
{
  "Application.DefaultKeyBindings": {
    "Quit": { "All": ["Esc"] },
    "Suspend": { "Linux": ["Ctrl+Z"], "Macos": ["Ctrl+Z"] },
    "Arrange": { "All": ["Ctrl+F5"] }
  },
  "View.DefaultKeyBindings": {
    "Copy": { "All": ["Ctrl+C"] },
    "Undo": { "All": ["Ctrl+Z"], "Linux": ["Ctrl+/"], "Macos": ["Ctrl+/"] }
  },
  "View.ViewKeyBindings": {
    "TextField": {
      "CutToEndOfLine": { "All": ["Ctrl+K"] }
    }
  }
}

View-Specific Settings

Settings for individual View types from ThemeScope:

json
{
  "Window.DefaultBorderStyle": "Single",
  "Window.DefaultShadow": "None",
  "Dialog.DefaultBorderStyle": "Heavy",
  "Dialog.DefaultShadow": "Transparent",
  "Dialog.DefaultButtonAlignment": "End",
  "FrameView.DefaultBorderStyle": "Rounded",
  "Button.DefaultShadow": "None",
  "PopoverMenu.DefaultKey": "Shift+F10",
  "FileDialog.MaxSearchResults": 10000
}

Glyphs

Customize the Unicode characters used for drawing:

json
{
  "Glyphs.RightArrow": "►",
  "Glyphs.LeftArrow": "U+25C4",
  "Glyphs.DownArrow": "\\u25BC",
  "Glyphs.UpArrow": 965010,
  "Glyphs.LeftBracket": "[",
  "Glyphs.RightBracket": "]",
  "Glyphs.Checked": "☑",
  "Glyphs.UnChecked": "☐",
  "Glyphs.Selected": "◉",
  "Glyphs.UnSelected": "○"
}

Glyphs can be specified as:

  • Unicode character: "►"
  • U+ format: "U+25C4"
  • UTF-16 format: "\\u25BC"
  • Decimal codepoint: 965010

Key Binding Overrides

Key bindings for Application-level commands, base View commands, and per-view commands can all be overridden in configuration. See Keyboard Deep Dive - Configurable Key Bindings for the full architecture.

Override Application-level key bindings (e.g., change the Quit key):

json
{
  "Application.DefaultKeyBindings": {
    "Quit": { "All": ["Ctrl+Q"] },
    "Suspend": { "Linux": ["Ctrl+Z"], "Macos": ["Ctrl+Z"] }
  }
}

Override base View key bindings (affects all views that support those commands):

json
{
  "View.DefaultKeyBindings": {
    "Copy": { "All": ["Ctrl+C", "Ctrl+Insert"] },
    "Paste": { "All": ["Ctrl+V", "Shift+Insert"] },
    "Undo": { "All": ["Ctrl+Z"], "Linux": ["Ctrl+/"], "Macos": ["Ctrl+/"] }
  }
}

Override per-view key bindings using View.ViewKeyBindings (maps view type name to command overrides):

json
{
  "View.ViewKeyBindings": {
    "TextField": {
      "Undo": { "All": ["Ctrl+Z"] },
      "CutToEndOfLine": { "All": ["Ctrl+K"] }
    },
    "TextView": {
      "Redo": { "All": ["Ctrl+Shift+Z"], "Windows": ["Ctrl+Y"] }
    }
  }
}

Each entry uses the PlatformKeyBinding format with optional All, Windows, Linux, and Macos string arrays. All keys apply on every platform; platform-specific arrays add additional bindings for that OS.

Discovering Configuration Properties

To find all available configuration properties:

csharp
// Get hard-coded configuration as a JSON string
string hardCodedJson = ConfigurationManager.GetHardCodedConfig();
Console.WriteLine(hardCodedJson);

// Or get an empty configuration skeleton
string emptyJson = ConfigurationManager.GetEmptyConfig();

Or search the source code for [ConfigurationProperty] attributes.

Themes and Schemes

Theme Structure

A theme is a named collection bundling visual settings and schemes:

json
{
  "Themes": [
    {
      "Dark": {
        "Dialog.DefaultBorderStyle": "Heavy",
        "Dialog.DefaultShadow": "Transparent",
        "Window.DefaultBorderStyle": "Single",
        "Button.DefaultShadow": "Opaque",
        "Schemes": [
          {
            "Accent": {
              "Normal": { "Foreground": "BrightGreen", "Background": "Black" },
              "Focus": { "Foreground": "White", "Background": "Cyan" }
            },
            "Dialog": {
              "Normal": { "Foreground": "Black", "Background": "Gray" }
            }
          }
        ]
      }
    }
  ]
}

Creating Custom Themes

Custom themes can be defined in configuration files:

json
{
  "Themes": [
    {
      "MyCustomTheme": {
        "Window.DefaultBorderStyle": "Double",
        "Dialog.DefaultShadow": "Opaque",
        "Schemes": [
          {
            "Base": {
              "Normal": {
                "Foreground": "Cyan",
                "Background": "Black",
                "Style": "Bold"
              }
            }
          }
        ]
      }
    }
  ]
}

Then activate the theme:

csharp
ThemeManager.Theme = "MyCustomTheme";
ConfigurationManager.Apply();

Theme Inheritance

Themes only override specified properties. To build on an existing theme:

csharp
// Start with default theme
ThemeManager.Theme = "Default";
ConfigurationManager.Apply();

// Apply custom theme (overrides only what's specified)
ThemeManager.Theme = "MyCustomTheme";
ConfigurationManager.Apply();

TextStyle in Schemes

Each Attribute in a scheme now includes TextStyle:

json
{
  "Normal": {
    "Foreground": "White",
    "Background": "Blue",
    "Style": "Bold, Underline"
  }
}

Available styles (combinable):

  • None
  • Bold
  • Faint
  • Italic
  • Underline
  • Blink
  • Reverse
  • Strikethrough

Configuration File Format

Schema

All configuration files must conform to the JSON schema:

Schema URL: https://gui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json

Root Structure

json
{
  "$schema": "https://gui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json",
  
  // SettingsScope properties
  "Application.DefaultKeyBindings.Quit": "Esc",
  "Application.Force16Colors": false,
  
  // Current theme name
  "Theme": "Dark",
  
  // Theme definitions
  "Themes": [
    {
      "Dark": {
        // ThemeScope properties
        "Window.DefaultBorderStyle": "Single",
        // Schemes
        "Schemes": [ ... ]
      }
    }
  ],
  
  // AppSettings
  "AppSettings": {
    "MyApp.MySetting": "value"
  }
}

Best Practices

For Application Developers

1. Enable Early

Enable ConfigurationManager at the start of Main(), before creating the application:

csharp
static void Main()
{
    ConfigurationManager.Enable(ConfigLocations.All);
    using IApplication app = Application.Create();
    app.Init();
    // ...
}

2. Use AppSettings for App Configuration

csharp
public class MyApp
{
    [ConfigurationProperty]
    public static bool ShowWelcomeMessage { get; set; } = true;
    
    [ConfigurationProperty]
    public static string DefaultDirectory { get; set; } = "";
}

3. Ship Default Configuration as Resource

Include a Resources/config.json file in your app:

xml
<ItemGroup>
  <EmbeddedResource Include="Resources\config.json" />
</ItemGroup>

4. Handle Configuration Changes

csharp
ConfigurationManager.Applied += (sender, e) => 
{
    // Refresh UI when configuration changes
    RefreshAllViews();
};

For Library Developers

1. Use Appropriate Scopes

2. Provide Meaningful Defaults

csharp
[ConfigurationProperty(Scope = typeof(ThemeScope))]
public static LineStyle DefaultBorderStyle { get; set; } = LineStyle.Single;

3. Document Configuration Properties

csharp
/// <summary>
///     Gets or sets the default border style for all Windows.
/// </summary>
[ConfigurationProperty(Scope = typeof(ThemeScope))]
public static LineStyle DefaultBorderStyle { get; set; } = LineStyle.Single;

Process-Wide Settings

[!IMPORTANT] Configuration settings are applied at the process level.

Since configuration properties are static, changes affect all applications in the same process. This is typically not an issue for normal applications, but can affect scenarios with:

  • Multiple Terminal.Gui apps in the same process
  • Unit tests running in parallel
  • Hot reload scenarios

Advanced Topics

JSON Error Handling

Control how JSON parsing errors are handled:

json
{
  "ConfigurationManager.ThrowOnJsonErrors": true
}
  • false (default) - Silent failures, errors logged
  • true - Throws exceptions on JSON parsing errors

Get Configuration as JSON

Retrieve the current hard-coded defaults as a JSON string:

csharp
// Get the hard-coded configuration as JSON
string json = ConfigurationManager.GetHardCodedConfig();
File.WriteAllText("my-config.json", json);

// Get an empty configuration skeleton (just the $schema tag)
string empty = ConfigurationManager.GetEmptyConfig();

Disable ConfigurationManager

Disable and optionally reset to defaults:

csharp
// Disable but keep current settings
ConfigurationManager.Disable(resetToHardCodedDefaults: false);

// Disable and reset to hard-coded defaults
ConfigurationManager.Disable(resetToHardCodedDefaults: true);

File System Watching

Watch for configuration file changes:

csharp
var watcher = new FileSystemWatcher(
    Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), ".tui"));
watcher.Filter = "*.json";
watcher.Changed += (s, e) => 
{
    ConfigurationManager.Load(ConfigLocations.GlobalHome);
    ConfigurationManager.Apply();
};
watcher.EnableRaisingEvents = true;

See UICatalog's ConfigurationEditor scenario for a complete example.

Examples

Example 1: Simple Theme Switching

csharp
using Terminal.Gui;
using Terminal.Gui.Configuration;

ConfigurationManager.Enable(ConfigLocations.All);

using IApplication app = Application.Create();
app.Init();

OptionSelector themeSelector = new ()
{
    X = 1,
    Y = 1,
    Labels = ThemeManager.GetThemeNames()
};
themeSelector.ValueChanged += (_, e) =>
{
    IReadOnlyList<string>? labels = themeSelector.Labels;
    if (labels is null || e.NewValue is null)
    {
        return;
    }

    ThemeManager.Theme = labels[e.NewValue.Value];
    ConfigurationManager.Apply();
};

Window win = new () { Title = "Theme Demo" };
win.Add(themeSelector);
app.Run(win);

Example 2: Custom Application Settings

csharp
public class MyApp
{
    [ConfigurationProperty]
    public static string LastOpenedFile { get; set; } = "";
    
    [ConfigurationProperty]
    public static int WindowWidth { get; set; } = 80;
    
    [ConfigurationProperty]
    public static int WindowHeight { get; set; } = 25;
}

// Enable and use
ConfigurationManager.Enable(ConfigLocations.All);

// Settings are automatically loaded and applied
var window = new Window
{
    Width = MyApp.WindowWidth,
    Height = MyApp.WindowHeight
};

// Later, retrieve the hard-coded config as JSON
string json = ConfigurationManager.GetHardCodedConfig();
// Could save to file here

Example 3: Runtime Configuration

csharp
ConfigurationManager.RuntimeConfig = @"
{
  ""Application.DefaultKeyBindings"": {
    ""Quit"": { ""All"": [""Ctrl+Q""] }
  },
  ""Driver.Force16Colors"": true,
  ""Theme"": ""Dark""
}";

ConfigurationManager.Enable(ConfigLocations.Runtime);

// Settings are now applied
// Quit key is Ctrl+Q
// 16-color mode is forced
// Dark theme is active

See Also

UICatalog Examples

The UICatalog application demonstrates configuration management:

  • Configuration Editor - Interactive editor for configuration files
  • Themes - Theme viewer and selector
  • File System Watcher - Automatic reload on configuration file changes

API Reference