From 61bfe2f537d7e04a01df2985bb9672bd6fad16fd Mon Sep 17 00:00:00 2001 From: Tig Date: Sat, 23 Nov 2024 08:52:09 -0700 Subject: [PATCH] Renamed property. Updated conceptual docs. --- Example/Example.cs | 3 + Terminal.Gui/Configuration/ConfigLocations.cs | 4 +- .../Configuration/ConfigurationManager.cs | 8 +- UnitTests/Application/ApplicationTests.cs | 4 +- .../Configuration/ConfigurationMangerTests.cs | 2 +- docfx/docs/config.md | 84 +++++-------------- 6 files changed, 32 insertions(+), 73 deletions(-) diff --git a/Example/Example.cs b/Example/Example.cs index 39126f4d9..1d13f47b2 100644 --- a/Example/Example.cs +++ b/Example/Example.cs @@ -6,6 +6,9 @@ using System; using Terminal.Gui; +// Override the default configuraiton for the application to use the Light theme +ConfigurationManager.RuntimeConfig = """{ "Theme": "Light" }"""; + Application.Run ().Dispose (); // Before the application exits, reset Terminal.Gui for clean shutdown diff --git a/Terminal.Gui/Configuration/ConfigLocations.cs b/Terminal.Gui/Configuration/ConfigLocations.cs index cf84a068f..c2499c6c3 100644 --- a/Terminal.Gui/Configuration/ConfigLocations.cs +++ b/Terminal.Gui/Configuration/ConfigLocations.cs @@ -48,9 +48,9 @@ public enum ConfigLocations AppHome = 0b_0010_0000, /// - /// Settings in . + /// Settings in the static property. /// - Memory = 0b_0100_0000, + Runtime = 0b_0100_0000, /// This constant is a combination of all locations All = 0b_1111_1111 diff --git a/Terminal.Gui/Configuration/ConfigurationManager.cs b/Terminal.Gui/Configuration/ConfigurationManager.cs index b793b612b..dff4abed4 100644 --- a/Terminal.Gui/Configuration/ConfigurationManager.cs +++ b/Terminal.Gui/Configuration/ConfigurationManager.cs @@ -221,9 +221,9 @@ public static class ConfigurationManager } /// - /// Gets or sets the in-memory config.json. See . + /// Gets or sets the in-memory config.json. See . /// - public static string? Memory { get; set; } + public static string? RuntimeConfig { get; set; } /// /// Loads all settings found in the configuration storage locations (). Optionally, resets @@ -285,9 +285,9 @@ public static class ConfigurationManager Settings?.Update ($"~/.tui/{AppName}.{_configFilename}"); } - if (Locations.HasFlag (ConfigLocations.Memory) && !string.IsNullOrEmpty (Memory)) + if (Locations.HasFlag (ConfigLocations.Runtime) && !string.IsNullOrEmpty (RuntimeConfig)) { - Settings?.Update (Memory, "ConfigurationManager.Memory"); + Settings?.Update (RuntimeConfig, "ConfigurationManager.Memory"); } ThemeManager.SelectedTheme = Settings!["Theme"].PropertyValue as string ?? "Default"; diff --git a/UnitTests/Application/ApplicationTests.cs b/UnitTests/Application/ApplicationTests.cs index 18689dbb9..38400d8a2 100644 --- a/UnitTests/Application/ApplicationTests.cs +++ b/UnitTests/Application/ApplicationTests.cs @@ -539,10 +539,10 @@ public class ApplicationTests public void Init_KeyBindings_Set_To_Custom () { // arrange - Locations = ConfigLocations.Memory; + Locations = ConfigLocations.Runtime; ThrowOnJsonErrors = true; - Memory = """ + RuntimeConfig = """ { "Application.QuitKey": "Ctrl-Q" } diff --git a/UnitTests/Configuration/ConfigurationMangerTests.cs b/UnitTests/Configuration/ConfigurationMangerTests.cs index 6d697d2ab..3c6c50174 100644 --- a/UnitTests/Configuration/ConfigurationMangerTests.cs +++ b/UnitTests/Configuration/ConfigurationMangerTests.cs @@ -220,7 +220,7 @@ public class ConfigurationManagerTests Assert.Equal (Key.Esc, (Key)Settings! ["Application.QuitKey"].PropertyValue); // act - Memory = """ + RuntimeConfig = """ { "Application.QuitKey": "Ctrl-Q" diff --git a/docfx/docs/config.md b/docfx/docs/config.md index cb1754343..e593f921f 100644 --- a/docfx/docs/config.md +++ b/docfx/docs/config.md @@ -12,17 +12,19 @@ Settings that will apply to all applications (global settings) reside in files n Settings are applied using the following precedence (higher precedence settings overwrite lower precedence settings): -1. App-specific settings in the users's home directory (`~/.tui/appname.config.json`). -- Highest precedence. +1. @Terminal.Gui.ConfigLocations.Runtime - Settings stored in the @Terminal.Gui.ConfigurationManager.RuntimeConfig static property --- Hightest precedence. -2. App-specific settings in the directory the app was launched from (`./.tui/appname.config.json`). +2. @Terminal.Gui.ConfigLocations.AppHome - App-specific settings in the users's home directory (`~/.tui/appname.config.json`). -3. App settings in app resources (`Resources/config.json`). +3. @Terminal.Gui.ConfigLocations.AppCurrent - App-specific settings in the directory the app was launched from (`./.tui/appname.config.json`). -4. Global settings in the the user's home directory (`~/.tui/config.json`). +4. @Terminal.Gui.ConfigLocations.AppResources - App settings in app resources (`Resources/config.json`). -5. Global settings in the directory the app was launched from (`./.tui/config.json`). +5. @Terminal.Gui.ConfigLocations.GlobalHome - Global settings in the the user's home directory (`~/.tui/config.json`). -6. Default settings in the Terminal.Gui assembly -- Lowest precedence. +6. @Terminal.Gui.ConfigLocations.GlobalCurrent - Global settings in the directory the app was launched from (`./.tui/config.json`). + +7. @Terminal.Gui.ConfigLocations.Default - Default settings in the Terminal.Gui assembly -- Lowest precedence. The `UI Catalog` application provides an example of how to use the [`ConfigurationManager`](~/api/Terminal.Gui.ConfigurationManager.yml) class to load and save configuration files. The `Configuration Editor` scenario provides an editor that allows users to edit the configuration files. UI Catalog also uses a file system watcher to detect changes to the configuration files to tell [`ConfigurationManager`](~/api/Terminal.Gui.ConfigurationManager.yml) to reload them; allowing users to change settings without having to restart the application. @@ -67,71 +69,25 @@ A Theme is a named collection of settings that impact the visual style of Termin Themes support defining ColorSchemes as well as various default settings for Views. Both the default color schemes and user-defined color schemes can be configured. See [ColorSchemes](~/api/Terminal.Gui.Colors.yml) for more information. -# Example Configuration File - -```json -{ - "$schema": "https://gui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json", - "Application.QuitKey": { - "Key": "Esc" - }, - "AppSettings": { - "UICatalog.StatusBar": false - }, - "Theme": "UI Catalog Theme", - "Themes": [ - { - "UI Catalog Theme": { - "ColorSchemes": [ - { - "UI Catalog Scheme": { - "Normal": { - "Foreground": "White", - "Background": "Green" - }, - "Focus": { - "Foreground": "Green", - "Background": "White" - }, - "HotNormal": { - "Foreground": "Blue", - "Background": "Green" - }, - "HotFocus": { - "Foreground": "BrightRed", - "Background": "White" - }, - "Disabled": { - "Foreground": "BrightGreen", - "Background": "Gray" - } - } - }, - { - "TopLevel": { - "Normal": { - "Foreground": "DarkGray", - "Background": "White" - ... - } - } - } - ], - "Dialog.DefaultEffect3D": false - } - } - ] -} -``` # Key Bindings Key bindings are defined in the `KeyBindings` property of the configuration file. The value is an array of objects, each object defining a key binding. The key binding object has the following properties: -- `Key`: The key to bind to. The format is a string describing the key (e.g. "q", "Q, "Ctrl-Q"). Function keys are specified as "F1", "F2", etc. +- `Key`: The key to bind to. The format is a string describing the key (e.g. "q", "Q, "Ctrl+Q"). Function keys are specified as "F1", "F2", etc. # Configuration File Schema -Settings are defined in JSON format, according to the schema found here: +Settings are defined in JSON format, according to the schema found here: https://gui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json + +## Schema + +[!code-json[tui-config-schema.json](../schemas/tui-config-schema.json)] + +# The Default Config File + +To illustrate the syntax, the below is the `config.json` file found in `Terminal.Gui.dll`: + +[!code-json[config.json](../../Terminal.Gui/Resources/config.json)] \ No newline at end of file