noctalia-shell/Commons/Settings.qml

pragma Singleton

import QtQuick
import Quickshell
import Quickshell.Io
import qs.Commons
import qs.Services
import "../Helpers/QtObj2JS.js" as QtObj2JS

Singleton {
  id: root

  // Used to access via Settings.data.xxx.yyy
  readonly property alias data: adapter
  property bool isLoaded: false
  property bool directoriesCreated: false
  property int settingsVersion: 19
  property bool isDebug: Quickshell.env("NOCTALIA_DEBUG") === "1"

  // Define our app directories
  // Default config directory: ~/.config/noctalia
  // Default cache directory: ~/.cache/noctalia
  property string shellName: "noctalia"
  property string configDir: Quickshell.env("NOCTALIA_CONFIG_DIR") || (Quickshell.env("XDG_CONFIG_HOME") || Quickshell.env("HOME") + "/.config") + "/" + shellName + "/"
  property string cacheDir: Quickshell.env("NOCTALIA_CACHE_DIR") || (Quickshell.env("XDG_CACHE_HOME") || Quickshell.env("HOME") + "/.cache") + "/" + shellName + "/"
  property string cacheDirImages: cacheDir + "images/"
  property string cacheDirImagesWallpapers: cacheDir + "images/wallpapers/"
  property string cacheDirImagesNotifications: cacheDir + "images/notifications/"
  property string settingsFile: Quickshell.env("NOCTALIA_SETTINGS_FILE") || (configDir + "settings.json")

  property string defaultLocation: "Tokyo"
  property string defaultAvatar: Quickshell.env("HOME") + "/.face"
  property string defaultVideosDirectory: Quickshell.env("HOME") + "/Videos"
  property string defaultWallpapersDirectory: Quickshell.env("HOME") + "/Pictures/Wallpapers"

  // Signal emitted when settings are loaded after startupcale changes
  signal settingsLoaded
  signal settingsSaved

  // -----------------------------------------------------
  // -----------------------------------------------------
  // Ensure directories exist before FileView tries to read files
  Component.onCompleted: {
    // ensure settings dir exists
    Quickshell.execDetached(["mkdir", "-p", configDir])
    Quickshell.execDetached(["mkdir", "-p", cacheDir])

    Quickshell.execDetached(["mkdir", "-p", cacheDirImagesWallpapers])
    Quickshell.execDetached(["mkdir", "-p", cacheDirImagesNotifications])

    // Mark directories as created and trigger file loading
    directoriesCreated = true

    // This should only be activated once when the settings structure has changed
    // Then it should be commented out again, regular users don't need to generate
    // default settings on every start
    if (isDebug) {
      generateDefaultSettings()
    }

    // Patch-in the local default, resolved to user's home
    adapter.general.avatarImage = defaultAvatar
    adapter.screenRecorder.directory = defaultVideosDirectory
    adapter.wallpaper.directory = defaultWallpapersDirectory
    adapter.wallpaper.defaultWallpaper = Quickshell.shellDir + "/Assets/Wallpaper/noctalia.png"

    // Set the adapter to the settingsFileView to trigger the real settings load
    settingsFileView.adapter = adapter
  }

  // Don't write settings to disk immediately
  // This avoid excessive IO when a variable changes rapidly (ex: sliders)
  Timer {
    id: saveTimer
    running: false
    interval: 1000
    onTriggered: {
      root.saveImmediate()
    }
  }

  FileView {
    id: settingsFileView
    path: directoriesCreated ? settingsFile : undefined
    printErrors: false
    watchChanges: true
    onFileChanged: reload()
    onAdapterUpdated: saveTimer.start()

    // Trigger initial load when path changes from empty to actual path
    onPathChanged: {
      if (path !== undefined) {
        reload()
      }
    }
    onLoaded: function () {
      if (!isLoaded) {
        Logger.i("Settings", "Settings loaded")

        upgradeSettingsData()
        validateMonitorConfigurations()
        isLoaded = true

        // Emit the signal
        root.settingsLoaded()

        // Finally, update our local settings version
        adapter.settingsVersion = settingsVersion
      }
    }
    onLoadFailed: function (error) {
      if (error.toString().includes("No such file") || error === 2) {
        // File doesn't exist, create it with default values
        writeAdapter()
        // Also write to fallback if set
        if (Quickshell.env("NOCTALIA_SETTINGS_FALLBACK")) {
          settingsFallbackFileView.writeAdapter()
        }
      }
    }
  }

  // Fallback FileView for writing settings to alternate location
  FileView {
    id: settingsFallbackFileView
    path: Quickshell.env("NOCTALIA_SETTINGS_FALLBACK") || ""
    adapter: Quickshell.env("NOCTALIA_SETTINGS_FALLBACK") ? adapter : null
    printErrors: false
    watchChanges: false
  }
  JsonAdapter {
    id: adapter

    property int settingsVersion: root.settingsVersion
    property bool setupCompleted: false

    // bar - Per-monitor configuration support
    property JsonObject bar: JsonObject {
      // Sync all monitors toggle - when true, all monitors use the "default" config
      property bool syncAcrossMonitors: false

      // Per-monitor configurations stored as array of objects
      // Each object has: { monitorName: "DP-1", position: "top", ... }
      property list<var> monitorsConfig: []

      // Monitor visibility filter - controls which monitors show the bar
      // Empty array = show on all monitors
      property list<string> monitors: []

      // Legacy properties for backward compatibility (will be migrated)
      property string position: "top"
      property real backgroundOpacity: 1.0
      property string density: "default"
      property bool showCapsule: true
      property bool floating: false
      property real marginVertical: 0.25
      property real marginHorizontal: 0.25
      property bool outerCorners: true
      property bool exclusive: true
      property JsonObject widgets: JsonObject {
        property list<var> left: []
        property list<var> center: []
        property list<var> right: []
      }
    }

    // general
    property JsonObject general: JsonObject {
      property string avatarImage: ""
      property bool dimDesktop: true
      property bool showScreenCorners: false
      property bool forceBlackScreenCorners: false
      property real scaleRatio: 1.0
      property real radiusRatio: 1.0
      property real screenRadiusRatio: 1.0
      property real animationSpeed: 1.0
      property bool animationDisabled: false
      property bool compactLockScreen: false
      property bool lockOnSuspend: true
      property bool enableShadows: true
      property string shadowDirection: "bottom_right"
      property int shadowOffsetX: 2
      property int shadowOffsetY: 3
      property string language: ""
    }

    // ui
    property JsonObject ui: JsonObject {
      property string fontDefault: "Roboto"
      property string fontFixed: "DejaVu Sans Mono"
      property real fontDefaultScale: 1.0
      property real fontFixedScale: 1.0
      property bool tooltipsEnabled: true
      property bool panelsAttachedToBar: true
      property bool panelsOverlayLayer: false
    }

    // location
    property JsonObject location: JsonObject {
      property string name: defaultLocation
      property bool weatherEnabled: true
      property bool useFahrenheit: false
      property bool use12hourFormat: false
      property bool showWeekNumberInCalendar: false
      property bool showCalendarEvents: true
      property bool showCalendarWeather: true
      property bool analogClockInCalendar: false
      property int firstDayOfWeek: -1 // -1 = auto (use locale), 0 = Sunday, 1 = Monday, 6 = Saturday
    }

    // screen recorder
    property JsonObject screenRecorder: JsonObject {
      property string directory: ""
      property int frameRate: 60
      property string audioCodec: "opus"
      property string videoCodec: "h264"
      property string quality: "very_high"
      property string colorRange: "limited"
      property bool showCursor: true
      property string audioSource: "default_output"
      property string videoSource: "portal"
    }

    // wallpaper
    property JsonObject wallpaper: JsonObject {
      property bool enabled: true
      property bool overviewEnabled: true
      property string directory: ""
      property bool enableMultiMonitorDirectories: false
      property bool recursiveSearch: false
      property bool setWallpaperOnAllMonitors: true
      property string defaultWallpaper: ""
      property string fillMode: "crop"
      property color fillColor: "#000000"
      property bool randomEnabled: false
      property int randomIntervalSec: 300 // 5 min
      property int transitionDuration: 1500 // 1500 ms
      property string transitionType: "random"
      property real transitionEdgeSmoothness: 0.05
      property list<var> monitors: []
      property string panelPosition: "follow_bar"
    }

    // applauncher
    property JsonObject appLauncher: JsonObject {
      property bool enableClipboardHistory: false
      // Position: center, top_left, top_right, bottom_left, bottom_right, bottom_center, top_center
      property string position: "center"
      property real backgroundOpacity: 1.0
      property list<string> pinnedExecs: []
      property bool useApp2Unit: false
      property bool sortByMostUsed: true
      property string terminalCommand: "xterm -e"
      property bool customLaunchPrefixEnabled: false
      property string customLaunchPrefix: ""
    }

    // control center
    property JsonObject controlCenter: JsonObject {
      // Position: close_to_bar_button, center, top_left, top_right, bottom_left, bottom_right, bottom_center, top_center
      property string position: "close_to_bar_button"
      property JsonObject shortcuts
      shortcuts: JsonObject {
        property list<var> left: [{
            "id": "WiFi"
          }, {
            "id": "Bluetooth"
          }, {
            "id": "ScreenRecorder"
          }, {
            "id": "WallpaperSelector"
          }]
        property list<var> right: [{
            "id": "Notifications"
          }, {
            "id": "PowerProfile"
          }, {
            "id": "KeepAwake"
          }, {
            "id": "NightLight"
          }]
      }
      property list<var> cards: [{
          "id": "profile-card",
          "enabled": true
        }, {
          "id": "shortcuts-card",
          "enabled": true
        }, {
          "id": "audio-card",
          "enabled": true
        }, {
          "id": "weather-card",
          "enabled": true
        }, {
          "id": "media-sysmon-card",
          "enabled": true
        }]
    }

    // dock
    property JsonObject dock: JsonObject {
      property bool enabled: true
      property string displayMode: "always_visible" // "always_visible", "auto_hide", "exclusive"
      property real backgroundOpacity: 1.0
      property real floatingRatio: 1.0
      property real size: 1
      property bool onlySameOutput: true
      property list<string> monitors: []
      // Desktop entry IDs pinned to the dock (e.g., "org.kde.konsole", "firefox.desktop")
      property list<string> pinnedApps: []
      property bool colorizeIcons: false
    }

    // network
    property JsonObject network: JsonObject {
      property bool wifiEnabled: true
    }

    // notifications
    property JsonObject notifications: JsonObject {
      property bool doNotDisturb: false
      property list<string> monitors: []
      property string location: "top_right"
      property bool overlayLayer: true
      property real backgroundOpacity: 1.0
      property bool respectExpireTimeout: false
      property int lowUrgencyDuration: 3
      property int normalUrgencyDuration: 8
      property int criticalUrgencyDuration: 15
    }

    // on-screen display
    property JsonObject osd: JsonObject {
      property bool enabled: true
      property string location: "top_right"
      property list<string> monitors: []
      property int autoHideMs: 2000
      property bool overlayLayer: true
    }

    // audio
    property JsonObject audio: JsonObject {
      property int volumeStep: 5
      property bool volumeOverdrive: false
      property int cavaFrameRate: 60
      property string visualizerType: "linear"
      property list<string> mprisBlacklist: []
      property string preferredPlayer: ""
    }

    // brightness
    property JsonObject brightness: JsonObject {
      property int brightnessStep: 5
      property bool enforceMinimum: true
      property bool enableDdcSupport: false
    }

    property JsonObject colorSchemes: JsonObject {
      property bool useWallpaperColors: false
      property string predefinedScheme: "Noctalia (default)"
      property bool darkMode: true
      property string schedulingMode: "off"
      property string manualSunrise: "06:30"
      property string manualSunset: "18:30"
      property string matugenSchemeType: "scheme-fruit-salad"
      property bool generateTemplatesForPredefined: true
    }

    // templates toggles
    property JsonObject templates: JsonObject {
      property bool gtk: false
      property bool qt: false
      property bool kcolorscheme: false
      property bool alacritty: false
      property bool kitty: false
      property bool ghostty: false
      property bool foot: false
      property bool wezterm: false
      property bool fuzzel: false
      property bool discord: false
      property bool discord_vesktop: false
      property bool discord_webcord: false
      property bool discord_armcord: false
      property bool discord_equibop: false
      property bool discord_lightcord: false
      property bool discord_dorion: false
      property bool pywalfox: false
      property bool vicinae: false
      property bool walker: false
      property bool code: false
      property bool enableUserTemplates: false
    }

    // night light
    property JsonObject nightLight: JsonObject {
      property bool enabled: false
      property bool forced: false
      property bool autoSchedule: true
      property string nightTemp: "4000"
      property string dayTemp: "6500"
      property string manualSunrise: "06:30"
      property string manualSunset: "18:30"
    }

    // hooks
    property JsonObject hooks: JsonObject {
      property bool enabled: false
      property string wallpaperChange: ""
      property string darkModeChange: ""
    }

    // battery
    property JsonObject battery: JsonObject {
      property int chargingMode: 0
    }
  }

  // -----------------------------------------------------
  // Function to preprocess paths by expanding "~" to user's home directory
  function preprocessPath(path) {
    if (typeof path !== "string" || path === "") {
      return path
    }

    // Expand "~" to user's home directory
    if (path.startsWith("~/")) {
      return Quickshell.env("HOME") + path.substring(1)
    } else if (path === "~") {
      return Quickshell.env("HOME")
    }

    return path
  }

  // -----------------------------------------------------
  // Helper functions for per-monitor bar configuration

  // Get the default bar configuration object
  function getDefaultBarConfig() {
    return {
      "position": "top",
      "backgroundOpacity": 1.0,
      "density": "default",
      "showCapsule": true,
      "floating": false,
      "marginVertical": 0.25,
      "marginHorizontal": 0.25,
      "outerCorners": true,
      "exclusive": true,
      "widgets": {
        "left": [{
            "id": "SystemMonitor"
          }, {
            "id": "ActiveWindow"
          }, {
            "id": "MediaMini"
          }],
        "center": [{
            "id": "Workspace"
          }],
        "right": [{
            "id": "ScreenRecorder"
          }, {
            "id": "Tray"
          }, {
            "id": "NotificationHistory"
          }, {
            "id": "Battery"
          }, {
            "id": "Volume"
          }, {
            "id": "Brightness"
          }, {
            "id": "Clock"
          }, {
            "id": "ControlCenter"
          }]
      }
    }
  }

  // Get bar configuration for a specific monitor
  function getMonitorBarConfig(monitorName) {
    // If syncing across monitors, use the default config
    if (adapter.bar.syncAcrossMonitors) {
      // Find the "default" config entry
      for (var i = 0; i < adapter.bar.monitorsConfig.length; i++) {
        if (adapter.bar.monitorsConfig[i].monitorName === "default") {
          return adapter.bar.monitorsConfig[i]
        }
      }
      return getDefaultBarConfig()
    }

    // Try to find monitor-specific config
    for (var i = 0; i < adapter.bar.monitorsConfig.length; i++) {
      if (adapter.bar.monitorsConfig[i].monitorName === monitorName) {
        return adapter.bar.monitorsConfig[i]
      }
    }

    // Fallback to default config
    for (var i = 0; i < adapter.bar.monitorsConfig.length; i++) {
      if (adapter.bar.monitorsConfig[i].monitorName === "default") {
        return adapter.bar.monitorsConfig[i]
      }
    }

    // Last resort: return hardcoded defaults
    return getDefaultBarConfig()
  }

  // Set bar configuration for a specific monitor
  function setMonitorBarConfig(monitorName, config) {
    // Add monitorName to the config object
    var configWithName = JSON.parse(JSON.stringify(config))
    configWithName.monitorName = monitorName

    // Find and replace existing config, or append if not found
    var found = false
    var newConfigs = []

    for (var i = 0; i < adapter.bar.monitorsConfig.length; i++) {
      if (adapter.bar.monitorsConfig[i].monitorName === monitorName) {
        newConfigs.push(configWithName)
        found = true
      } else {
        newConfigs.push(adapter.bar.monitorsConfig[i])
      }
    }

    if (!found) {
      newConfigs.push(configWithName)
    }

    adapter.bar.monitorsConfig = newConfigs
  }

  // Ensure a monitor has a configuration (creates from default if missing)
  function ensureMonitorBarConfig(monitorName) {
    // Check if config already exists
    for (var i = 0; i < adapter.bar.monitorsConfig.length; i++) {
      if (adapter.bar.monitorsConfig[i].monitorName === monitorName) {
        return
        // Already exists
      }
    }

    // Try to copy from first available monitor (not "default")
    var firstMonitorConfig = null
    for (var i = 0; i < adapter.bar.monitorsConfig.length; i++) {
      if (adapter.bar.monitorsConfig[i].monitorName !== "default") {
        firstMonitorConfig = adapter.bar.monitorsConfig[i]
        break
      }
    }

    if (firstMonitorConfig) {
      Logger.i("Settings", `Creating config for new monitor ${monitorName} by copying from ${firstMonitorConfig.monitorName}`)
      var sourceConfig = JSON.parse(JSON.stringify(firstMonitorConfig))
      delete sourceConfig.monitorName // Remove the old monitor name
      setMonitorBarConfig(monitorName, sourceConfig)
    } else {
      // Try to use default config
      for (var i = 0; i < adapter.bar.monitorsConfig.length; i++) {
        if (adapter.bar.monitorsConfig[i].monitorName === "default") {
          Logger.i("Settings", `Creating config for new monitor ${monitorName} from default`)
          var defaultConfig = JSON.parse(JSON.stringify(adapter.bar.monitorsConfig[i]))
          delete defaultConfig.monitorName
          setMonitorBarConfig(monitorName, defaultConfig)
          return
        }
      }

      // Last resort: use hardcoded defaults
      Logger.i("Settings", `Creating config for new monitor ${monitorName} with hardcoded defaults`)
      setMonitorBarConfig(monitorName, getDefaultBarConfig())
    }
  }

  // Get widget settings for a specific monitor and section
  function getWidgetSettings(monitorName, section, widgetIndex) {
    var config = getMonitorBarConfig(monitorName)
    if (!config || !config.widgets || !config.widgets[section]) {
      return {}
    }
    var widgets = config.widgets[section]
    if (widgetIndex >= 0 && widgetIndex < widgets.length) {
      return widgets[widgetIndex]
    }
    return {}
  }

  // Update widget settings for a specific monitor and section
  function setWidgetSettings(monitorName, section, widgetIndex, newSettings) {
    var config = JSON.parse(JSON.stringify(getMonitorBarConfig(monitorName)))
    if (!config.widgets) {
      config.widgets = {
        "left": [],
        "center": [],
        "right": []
      }
    }
    if (!config.widgets[section]) {
      config.widgets[section] = []
    }
    if (widgetIndex >= 0 && widgetIndex < config.widgets[section].length) {
      config.widgets[section][widgetIndex] = newSettings
      setMonitorBarConfig(monitorName, config)
      return true
    }
    return false
  }

  // -----------------------------------------------------
  // Public function to trigger immediate settings saving
  function saveImmediate() {
    settingsFileView.writeAdapter()
    // Write to fallback location if set
    if (Quickshell.env("NOCTALIA_SETTINGS_FALLBACK")) {
      settingsFallbackFileView.writeAdapter()
    }
    root.settingsSaved() // Emit signal after saving
  }

  // -----------------------------------------------------
  // Generate default settings at the root of the repo
  function generateDefaultSettings() {
    try {
      Logger.d("Settings", "Generating settings-default.json")

      // Prepare a clean JSON
      var plainAdapter = QtObj2JS.qtObjectToPlainObject(adapter)
      var jsonData = JSON.stringify(plainAdapter, null, 2)

      var defaultPath = Quickshell.shellDir + "/Assets/settings-default.json"

      // Encode transfer it has base64 to avoid any escaping issue
      var base64Data = Qt.btoa(jsonData)
      Quickshell.execDetached(["sh", "-c", `echo "${base64Data}" | base64 -d > "${defaultPath}"`])
    } catch (error) {
      Logger.e("Settings", "Failed to generate default settings file: " + error)
    }
  }

  // -----------------------------------------------------
  // Function to validate monitor configurations
  function validateMonitorConfigurations() {
    var availableScreenNames = []
    for (var i = 0; i < Quickshell.screens.length; i++) {
      availableScreenNames.push(Quickshell.screens[i].name)
    }

    Logger.d("Settings", "Available monitors: [" + availableScreenNames.join(", ") + "]")

    // Validate bar monitor visibility filter
    if (adapter.bar.monitors && adapter.bar.monitors.length > 0) {
      Logger.d("Settings", "Configured bar monitor filter: [" + adapter.bar.monitors.join(", ") + "]")
      var hasValidBarMonitor = false
      for (var j = 0; j < adapter.bar.monitors.length; j++) {
        if (availableScreenNames.includes(adapter.bar.monitors[j])) {
          hasValidBarMonitor = true
          break
        }
      }
      if (!hasValidBarMonitor) {
        Logger.w("Settings", "No configured bar monitors found on system, clearing bar monitor filter list")
        adapter.bar.monitors = []
      }
    }

    // Ensure all connected monitors have configurations
    for (var k = 0; k < availableScreenNames.length; k++) {
      ensureMonitorBarConfig(availableScreenNames[k])
    }
  }

  // -----------------------------------------------------
  // Migrate old bar settings structure to per-monitor configuration
  function migrateBarSettingsToPerMonitor() {
    // Check if migration is needed - look for non-empty monitorsConfig array
    var hasMonitorConfigs = adapter.bar.monitorsConfig && adapter.bar.monitorsConfig.length > 0

    // If we already have monitor configs, no migration needed
    if (hasMonitorConfigs) {
      return
    }

    // Check if we have the old structure (widgets property exists at bar level)
    if (!adapter.bar.widgets || !adapter.bar.widgets.left) {
      return
    }

    Logger.i("Settings", "Migrating bar configuration to per-monitor structure")

    // Build the old configuration object from legacy properties
    var oldConfig = {
      "position": adapter.bar.position || "top",
      "backgroundOpacity": adapter.bar.backgroundOpacity !== undefined ? adapter.bar.backgroundOpacity : 1.0,
      "density": adapter.bar.density || "default",
      "showCapsule": adapter.bar.showCapsule !== undefined ? adapter.bar.showCapsule : true,
      "floating": adapter.bar.floating !== undefined ? adapter.bar.floating : false,
      "marginVertical": adapter.bar.marginVertical !== undefined ? adapter.bar.marginVertical : 0.25,
      "marginHorizontal": adapter.bar.marginHorizontal !== undefined ? adapter.bar.marginHorizontal : 0.25,
      "outerCorners": adapter.bar.outerCorners !== undefined ? adapter.bar.outerCorners : true,
      "exclusive": adapter.bar.exclusive !== undefined ? adapter.bar.exclusive : true,
      "widgets": {
        "left": [],
        "center": [],
        "right": []
      }
    }

    // Copy widgets
    if (adapter.bar.widgets.left) {
      oldConfig.widgets.left = JSON.parse(JSON.stringify(adapter.bar.widgets.left))
    }
    if (adapter.bar.widgets.center) {
      oldConfig.widgets.center = JSON.parse(JSON.stringify(adapter.bar.widgets.center))
    }
    if (adapter.bar.widgets.right) {
      oldConfig.widgets.right = JSON.parse(JSON.stringify(adapter.bar.widgets.right))
    }

    // Apply this config to all current monitors
    for (var i = 0; i < Quickshell.screens.length; i++) {
      var screenName = Quickshell.screens[i].name
      Logger.i("Settings", `Applying migrated bar config to monitor: ${screenName}`)
      setMonitorBarConfig(screenName, oldConfig)
    }

    // Also set as default config
    setMonitorBarConfig("default", oldConfig)

    // Set syncAcrossMonitors to false (user can enable it if they want)
    adapter.bar.syncAcrossMonitors = false

    Logger.i("Settings", "Bar configuration migration complete")
  }

  // -----------------------------------------------------
  // If the settings structure has changed, ensure
  // backward compatibility by upgrading the settings
  function upgradeSettingsData() {
    // Wait for BarWidgetRegistry to be ready
    if (!BarWidgetRegistry.widgets || Object.keys(BarWidgetRegistry.widgets).length === 0) {
      Logger.w("Settings", "BarWidgetRegistry not ready, deferring upgrade")
      Qt.callLater(upgradeSettingsData)
      return
    }

    // TEMP - disable Open panels on overlay which used to be true by default.
    if (adapter.settingsVersion < 18) {
      try {
        if (adapter.ui.panelsOverlayLayer) {
          adapter.ui.panelsOverlayLayer = false
          Logger.i("Settings", "Upgraded panelsOverlayLayer to false by default")
        }
      } catch (e) {

      }
    }

    // TEMP
    if (adapter.settingsVersion < 19) {
      // Migrate old bar configuration to per-monitor structure
      migrateBarSettingsToPerMonitor()
    }

    const sections = ["left", "center", "right"]

    // Upgrade widgets for all monitor configurations
    upgradeAllMonitorWidgets(sections)
  }

  // -----------------------------------------------------
  // Upgrade widgets across all monitor configurations
  function upgradeAllMonitorWidgets(sections) {
    // Iterate over all monitor configurations
    var monitorNames = []
    for (var key in adapter.bar.monitorsConfig) {
      if (adapter.bar.monitorsConfig.hasOwnProperty(key)) {
        monitorNames.push(key)
      }
    }

    for (var m = 0; m < monitorNames.length; m++) {
      var monitorName = monitorNames[m]
      var monitorConfig = adapter.bar.monitorsConfig[monitorName]

      if (!monitorConfig || !monitorConfig.widgets) {
        continue
      }

      Logger.d("Settings", `Upgrading widgets for monitor: ${monitorName}`)

      // -----------------
      // 1st. convert old widget id to new id
      for (var s = 0; s < sections.length; s++) {
        const sectionName = sections[s]
        if (!monitorConfig.widgets[sectionName])
          continue

        for (var i = 0; i < monitorConfig.widgets[sectionName].length; i++) {
          var widget = monitorConfig.widgets[sectionName][i]

          switch (widget.id) {
          case "DarkModeToggle":
            widget.id = "DarkMode"
            break
          case "PowerToggle":
            widget.id = "SessionMenu"
            break
          case "ScreenRecorderIndicator":
            widget.id = "ScreenRecorder"
            break
          case "SidePanelToggle":
            widget.id = "ControlCenter"
            break
          }
        }
      }

      // -----------------
      // 2nd. remove any non existing widget type
      var removedWidget = false
      for (var s = 0; s < sections.length; s++) {
        const sectionName = sections[s]
        if (!monitorConfig.widgets[sectionName])
          continue

        const widgets = monitorConfig.widgets[sectionName]
        // Iterate backward through the widgets array, so it does not break when removing a widget
        for (var i = widgets.length - 1; i >= 0; i--) {
          var widget = widgets[i]
          if (!BarWidgetRegistry.hasWidget(widget.id)) {
            Logger.w(`Settings`, `Deleted invalid widget ${widget.id} from ${monitorName}`)
            widgets.splice(i, 1)
            removedWidget = true
          }
        }
      }

      // -----------------
      // 3rd. upgrade widget settings
      for (var s = 0; s < sections.length; s++) {
        const sectionName = sections[s]
        if (!monitorConfig.widgets[sectionName])
          continue

        for (var i = 0; i < monitorConfig.widgets[sectionName].length; i++) {
          var widget = monitorConfig.widgets[sectionName][i]

          // Check if widget registry supports user settings, if it does not, then there is nothing to do
          const reg = BarWidgetRegistry.widgetMetadata[widget.id]
          if ((reg === undefined) || (reg.allowUserSettings === undefined) || !reg.allowUserSettings) {
            continue
          }

          if (upgradeWidget(widget)) {
            Logger.d("Settings", `Upgraded ${widget.id} widget on ${monitorName}:`, JSON.stringify(widget))
          }
        }
      }

      // -----------------
      // 4th. safety check
      // if a widget was deleted, ensure we still have a control center
      if (removedWidget) {
        var gotControlCenter = false
        for (var s = 0; s < sections.length; s++) {
          const sectionName = sections[s]
          if (!monitorConfig.widgets[sectionName])
            continue

          for (var i = 0; i < monitorConfig.widgets[sectionName].length; i++) {
            var widget = monitorConfig.widgets[sectionName][i]
            if (widget.id === "ControlCenter") {
              gotControlCenter = true
              break
            }
          }
        }

        if (!gotControlCenter) {
          if (!monitorConfig.widgets["right"]) {
            monitorConfig.widgets["right"] = []
          }
          monitorConfig.widgets["right"].push({
                                                "id": "ControlCenter"
                                              })
          Logger.w("Settings", `Added a ControlCenter widget to ${monitorName} right section`)
        }
      }
    }
  }

  // -----------------------------------------------------
  function upgradeWidget(widget) {
    // Backup the widget definition before altering
    const widgetBefore = JSON.stringify(widget)

    // Get all existing custom settings keys
    const keys = Object.keys(BarWidgetRegistry.widgetMetadata[widget.id])

    // Delete deprecated user settings from the wiget
    for (const k of Object.keys(widget)) {
      if (k === "id" || k === "allowUserSettings") {
        continue
      }
      if (!keys.includes(k)) {
        delete widget[k]
      }
    }

    // Inject missing default setting (metaData) from BarWidgetRegistry
    for (var i = 0; i < keys.length; i++) {
      const k = keys[i]
      if (k === "id" || k === "allowUserSettings") {
        continue
      }

      if (widget[k] === undefined) {
        widget[k] = BarWidgetRegistry.widgetMetadata[widget.id][k]
      }
    }

    // Compare settings, to detect if something has been upgraded
    const widgetAfter = JSON.stringify(widget)
    return (widgetAfter !== widgetBefore)
  }
}