Fixes #2181 - (Really) Adds configuration manager (#2365)

2025-12-26 15:57:56 +01:00 · 2023-02-21 00:34:18 +13:00
parent eb90d6abff
commit 9425b2a720
56 changed files with 5103 additions and 809 deletions
--- a/docfx/articles/config.md
+++ b/docfx/articles/config.md
@@ -0,0 +1,110 @@
+# Configuration Management
+
+Terminal.Gui provides configuration and theme management for Terminal.Gui applications via the [`ConfigurationManager`](~/api/Terminal.Gui/Terminal.Gui.Configuration.
+
+1) **Settings**. Settings are applied to the [`Application`](~/api/Terminal.Gui/Terminal.Gui.Application.yml) class. Settings are accessed via the `Settings` property of the [`ConfigurationManager`](~/api/Terminal.Gui/Terminal.Gui.Configuration.ConfigurationManager.yml) class.
+2) **Themes**. Themes are a named collection of settings impacting how applications look. The default theme is named "Default". The built-in configuration stored within the Terminal.Gui library defines two additional themes: "Dark", and "Light". Additional themes can be defined in the configuration files.
+3) **AppSettings**. AppSettings allow applicaitons to use the  [`ConfigurationManager`](~/api/Terminal.Gui/Terminal.Gui.Configuration.ConfigurationManager.yml) to store and retrieve application-specific settings.
+
+The The [`ConfigurationManager`](~/api/Terminal.Gui/Terminal.Gui.Configuration.ConfigurationManager.yml) will look for configuration files in the `.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 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 following precedence (higher precedence settings overwrite lower precedence settings):
+
+1. App specific settings found in the users's home directory (`~/.tui/appname.config.json`). -- Highest precedence.
+
+2. App specific settings found in the directory the app was launched from (`./.tui/appname.config.json`).
+
+3. App settings in app resources (`Resources/config.json`).
+
+4. Global settings found in the the user's home directory (`~/.tui/config.json`).
+
+5. Global settings found in the directory the app was launched from (`./.tui/config.json`).
+
+6. Default settings defined in the Terminal.Gui assembly -- Lowest precedence.
+
+The `UI Catalog` application provides an example of how to use the [`ConfigurationManager`](~/api/Terminal.Gui/Terminal.Gui.Configuration.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/Terminal.Gui.Configuration.ConfigurationManager.yml) to reaload them; allowing users to change settings without having to restart the application.
+
+# What Can Be Configured
+
+## Settings
+
+Settings for the [`Application`](~/api/Terminal.Gui/Terminal.Gui.Application.yml) class.
+    * [QuitKey](~/api/Terminal.Gui/Terminal.Gui.Application.yml#QuitKey)
+    * [AlternateForwardKey](~/api/Terminal.Gui/Terminal.Gui.Application.yml#AlternateForwardKey)
+    * [AlternateBackwardKey](~/api/Terminal.Gui/Terminal.Gui.Application.yml#AlternateBackwardKey)
+    * [UseSystemConsole](~/api/Terminal.Gui/Terminal.Gui.Application.yml#UseSystemConsole)
+    * [IsMouseDisabled](~/api/Terminal.Gui/Terminal.Gui.Application.yml#IsMouseDisabled)
+    * [HeightAsBuffer](~/api/Terminal.Gui/Terminal.Gui.Application.yml#HeightAsBuffer)
+
+## Themes
+
+A Theme is a named collection of settings that impact the visual style of Terminal.Gui applications. The default theme is named "Default". The built-in configuration stored within the Terminal.Gui library defines two more themes: "Dark", and "Light". Additional themes can be defined in the configuration files. 
+
+The Json property `Theme` defines the name of the theme that will be used. If the theme is not found, the default theme will be used.
+
+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/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
+      }
+    }
+  ]
+}
+```
+
+# Configuration File Schema
+
+Settings are defined in JSON format, according to the schema found here: 
+
+https://gui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json
--- a/docfx/articles/index.md
+++ b/docfx/articles/index.md
@@ -5,5 +5,6 @@
 * [Keyboard Event Processing](keyboard.md)
 * [Event Processing and the Application Main Loop](mainloop.md)
 * [Cross-platform Driver Model](drivers.md)
+* [Configuration and Theme Manager](config.md)
 * [TableView Deep Dive](tableview.md)
 * [TreeView Deep Dive](treeview.md)
--- a/docfx/build.ps1
+++ b/docfx/build.ps1
@@ -1,11 +1,20 @@
 # Builds the Terminal.gui API documentation using docfx

-dotnet build --configuration Release ../Terminal.sln
+$prevPwd = $PWD; Set-Location -ErrorAction Stop -LiteralPath $PSScriptRoot

-rm ../docs -Recurse -Force -ErrorAction SilentlyContinue
+try {
+    $PWD  # output the current location 

-$env:DOCFX_SOURCE_BRANCH_NAME="main"
+    dotnet build --configuration Release ../Terminal.sln

-docfx --metadata
+    rm ../docs -Recurse -Force -ErrorAction SilentlyContinue
+
+    $env:DOCFX_SOURCE_BRANCH_NAME="main"
+
+    docfx --metadata --serve --force
+}
+finally {
+  # Restore the previous location.
+  $prevPwd | Set-Location
+}

-docfx --serve --force
--- a/docfx/docfx.json
+++ b/docfx/docfx.json
@@ -16,7 +16,7 @@
      "dest": "api/Terminal.Gui",
      "shouldSkipMarkup": true,
      "properties": {
-          "TargetFramework": "net6.0"
+          "TargetFramework": "net7.0"
      }
    },
    {
@@ -35,7 +35,7 @@
      "dest": "api/UICatalog",
      "shouldSkipMarkup": false,
      "properties": {
-          "TargetFramework": "net6.0"
+          "TargetFramework": "net7.0"
      }
    }
  ],
@@ -67,7 +67,8 @@
    "resource": [
      {
        "files": [
-          "images/**"
+          "images/**",
+          "schemas/**"
        ],
        "exclude": [
          "obj/**",
--- a/docfx/images/sample.gif
+++ b/docfx/images/sample.gif
--- a/docfx/index.md
+++ b/docfx/index.md
@@ -14,6 +14,7 @@ A toolkit for building rich console apps for .NET, .NET Core, and Mono that work
 * [Keyboard Event Processing](~/articles/keyboard.md)
 * [Event Processing and the Application Main Loop](~/articles/mainloop.md)
 * [Cross-platform Driver Model](~/articles/drivers.md)
+* [Configuration and Theme Manager](~/articles/config.md)
 * [TableView Deep Dive](~/articles/tableview.md)
 * [TreeView Deep Dive](~/articles/treeview.md)

--- a/docfx/schemas/tui-config-schema.json
+++ b/docfx/schemas/tui-config-schema.json
@@ -0,0 +1,296 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "The JSON schema for the Terminal.Gui Configuration Manager (https://gui-cs.github.io/Terminal.Gui/schemas/tui-config-schema.json).",
+  "type": "object",
+  "properties": {
+    "Application.HeightAsBuffer": {
+      "description": "See HeightAsBuffer API documentation.",
+      "type": "boolean"
+    },
+    "Application.AlternateForwardKey": {
+      "description": "Alternative key for navigating forwards through views. SCtrl+Tab is the primary key.",
+      "$ref": "#/definitions/Key"
+    },
+    "Application.AlternateBackwardKey": {
+      "description": "Alternative key for navigating backwards through views. Shift+Ctrl+Tab is the primary key.",
+      "$ref": "#/definitions/Key"
+    },
+    "Application.QuitKey": {
+      "description": "The key to quit the application. Ctrl+Q is the default.",
+      "$ref": "#/definitions/Key"
+    },
+    "Application.IsMouseDisabled": {
+      "description": "Disable or enable the mouse. The mouse is enabled by default.",
+      "type": "boolean"
+    },
+    "Application.UseSystemConsole": {
+      "description": "If true, forces the use of the System.Console-based (aka NetDriver) driver. The default is false.",
+      "type": "boolean"
+    },
+    "Theme": {
+      "description": "The currently selected theme. The default is 'Default'.",
+      "type": "string"
+    },
+    "Themes": {
+      "description": "An array of Theme objects. Each Theme specifies a set of settings for an application. Set Theme to the name of the active theme.",
+      "type": "array",
+      "properties": {
+        "Themes": {
+          "$ref": "#/definitions/Theme"
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/ColorScheme"
+      }
+    }
+  },
+  "definitions": {
+    "Theme": {
+      "description": "A Theme is a collection of settings that are named.",
+      "type": "object",
+      "properties": {
+        "ColorSchemes": {
+          "description": "The ColorSchemes defined for this Theme.",
+          "$ref": "#/definitions/ColorSchemes"
+        }
+      }
+    },
+    "ColorSchemes": {
+      "description": "A list of ColorSchemes. Each ColorScheme specifies a set of Attributes (Foreground & Background).",
+      "type": "array",
+      "properties": {
+        "TopLevel": {
+          "$ref": "#/definitions/ColorScheme"
+        },
+        "Base": {
+          "$ref": "#/definitions/ColorScheme"
+        },
+        "Dialog": {
+          "$ref": "#/definitions/ColorScheme"
+        },
+        "Menu": {
+          "$ref": "#/definitions/ColorScheme"
+        },
+        "Error": {
+          "$ref": "#/definitions/ColorScheme"
+        }
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/ColorScheme"
+      }
+    },
+    "ColorScheme": {
+      "description": "A Terminal.Gui ColorScheme. Specifies the Foreground & Background colors for modes of an Terminal.Gui app.",
+      "type": "object",
+      "properties": {
+        "Normal": {
+          "description": "The foreground and background color for text when the view is not focused, hot, or disabled.",
+          "$ref": "#/definitions/Attribute"
+        },
+        "Focus": {
+          "description": "The foreground and background color for text when the view has focus.",
+          "$ref": "#/definitions/Attribute"
+        },
+        "HotNormal": {
+          "description": "The foreground and background color for text when the view is highlighted (hot).",
+          "$ref": "#/definitions/Attribute"
+        },
+        "HotFocus": {
+          "description": "The foreground and background color for text when the view is highlighted (hot) and has focus.",
+          "$ref": "#/definitions/Attribute"
+        },
+        "Disabled": {
+          "description": "The foreground and background color for text when the view disabled.",
+          "$ref": "#/definitions/Attribute"
+        }
+      }
+    },
+    "Attribute": {
+      "description": "A Terminal.Gui color attribute. Specifies the Foreground & Background colors for Terminal.Gui output.",
+      "type": "object",
+      "properties": {
+        "Foreground": {
+          "$ref": "#/definitions/Color"
+        },
+        "Background": {
+          "$ref": "#/definitions/Color"
+        }
+      },
+      "required": [
+        "Foreground",
+        "Background"
+      ]
+    },
+    "Color": {
+      "description": "One be either one of 16 standard color names or an rgb(r,g,b) tuple.",
+      "$schema": "http://json-schema.org/draft-07/schema#",
+      "type": "string",
+      "properties": {
+        "color": {
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "Black",
+                "Blue",
+                "Green",
+                "Cyan",
+                "Red",
+                "Magenta",
+                "Brown",
+                "Gray",
+                "DarkGray",
+                "BrightBlue",
+                "BrightGreen",
+                "BrightCyan",
+                "BrightRed",
+                "BrightMagenta",
+                "BrightYellow",
+                "White"
+              ]
+            },
+            {
+              "type": "string",
+              "pattern": "^rgb\\(\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*,\\s*\\d{1,3}\\s*\\)$"
+            }
+          ]
+        }
+      }
+    },
+    "Key": {
+      "description": "A key pressed on the keyboard.",
+      "type": "object",
+      "properties": {
+        "Key": {
+          "description": "A key name (e.g. A, b, 1, 2, Enter, Esc, F5, etc.) or an integer value (e.g. 65, 66, 67, etc.).",
+          "oneOf": [
+            {
+              "type": "string",
+              "enum": [
+                "Null",
+                "Backspace",
+                "Tab",
+                "Enter",
+                "Clear",
+                "Esc",
+                "Space",
+                "D0",
+                "D1",
+                "D2",
+                "D3",
+                "D4",
+                "D5",
+                "D6",
+                "D7",
+                "D8",
+                "D9",
+                "0",
+                "1",
+                "2",
+                "3",
+                "4",
+                "5",
+                "6",
+                "7",
+                "8",
+                "9",
+                "a",
+                "b",
+                "c",
+                "d",
+                "e",
+                "f",
+                "g",
+                "h",
+                "i",
+                "j",
+                "k",
+                "l",
+                "m",
+                "n",
+                "o",
+                "p",
+                "q",
+                "r",
+                "s",
+                "t",
+                "u",
+                "v",
+                "w",
+                "x",
+                "y",
+                "z",
+                "A",
+                "B",
+                "C",
+                "D",
+                "E",
+                "F",
+                "G",
+                "H",
+                "I",
+                "J",
+                "K",
+                "L",
+                "M",
+                "N",
+                "O",
+                "P",
+                "Q",
+                "R",
+                "S",
+                "T",
+                "U",
+                "V",
+                "W",
+                "X",
+                "Y",
+                "Z",
+                "F1",
+                "F2",
+                "F3",
+                "F4",
+                "F5",
+                "F6",
+                "F7",
+                "F8",
+                "F9",
+                "F10",
+                "F11",
+                "F12",
+                "Insert",
+                "Delete",
+                "Home",
+                "End",
+                "PageUp",
+                "PageDown",
+                "Up",
+                "Down",
+                "Left",
+                "Right"
+              ]
+            },
+            {
+              "type": "integer"
+            }
+          ]
+        },
+        "Modifiers": {
+          "description": "A keyboard modifier (e.g. Ctrl, Alt, or Shift).",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "Ctrl",
+              "Alt",
+              "Shift"
+            ]
+          }
+        }
+      },
+      "required": [
+        "Key"
+      ]
+    }
+  }
+}