feat(wallpaper): support configurable background color (#2671)

* feat(wallpaper): support configurable background color

* chore(translations): update settings search index

* revert(wallpaper): keep Pad naming instead of Center

quickshell/Common/SettingsData.qml

@@ -242,6 +242,24 @@ Singleton {
     property string wallpaperFillMode: "Fill"
     property bool blurredWallpaperLayer: false
     property bool blurWallpaperOnOverview: false
+    property string wallpaperBackgroundColorMode: "black"
+    property string wallpaperBackgroundCustomColor: "#000000"
+    readonly property color effectiveWallpaperBackgroundColor: {
+        switch (wallpaperBackgroundColorMode) {
+        case "black":
+            return "#000000";
+        case "white":
+            return "#ffffff";
+        case "primary":
+            return Theme.primary;
+        case "surface":
+            return Theme.surfaceContainer;
+        case "custom":
+            return wallpaperBackgroundCustomColor;
+        default:
+            return "#000000";
+        }
+    }
 
     property bool frameEnabled: false
     onFrameEnabledChanged: saveSettings()

quickshell/Common/settings/SettingsSpec.js

@@ -74,6 +74,8 @@ var SPEC = {
     wallpaperFillMode: { def: "Fill" },
     blurredWallpaperLayer: { def: false },
     blurWallpaperOnOverview: { def: false },
+    wallpaperBackgroundColorMode: { def: "black" },
+    wallpaperBackgroundCustomColor: { def: "#000000" },
 
     showLauncherButton: { def: true },
     showWorkspaceSwitcher: { def: true },

quickshell/Modules/BlurredWallpaperBackground.qml

@@ -43,6 +43,11 @@ Variants {
             id: root
             anchors.fill: parent
 
+            Rectangle {
+                anchors.fill: parent
+                color: SettingsData.effectiveWallpaperBackgroundColor
+            }
+
             function encodeFileUrl(path) {
                 if (!path)
                     return "";
@@ -137,6 +142,12 @@ Variants {
                 function onWallpaperFillModeChanged() {
                     root.invalidate();
                 }
+                function onWallpaperBackgroundColorModeChanged() {
+                    root.invalidate();
+                }
+                function onWallpaperBackgroundCustomColorChanged() {
+                    root.invalidate();
+                }
             }
 
             Connections {

quickshell/Modules/Greetd/GreetdSettings.qml

@@ -79,6 +79,24 @@ Singleton {
     property var screenPreferences: ({})
     property int animationSpeed: 2
     property string wallpaperFillMode: "Fill"
+    property string wallpaperBackgroundColorMode: "black"
+    property string wallpaperBackgroundCustomColor: "#000000"
+    readonly property color effectiveWallpaperBackgroundColor: {
+        switch (wallpaperBackgroundColorMode) {
+        case "black":
+            return "#000000";
+        case "white":
+            return "#ffffff";
+        case "primary":
+            return (typeof Theme !== "undefined") ? Theme.primary : "#000000";
+        case "surface":
+            return (typeof Theme !== "undefined") ? Theme.surfaceContainer : "#000000";
+        case "custom":
+            return wallpaperBackgroundCustomColor;
+        default:
+            return "#000000";
+        }
+    }
 
     function parseSettings(content) {
         try {
@@ -147,6 +165,8 @@ Singleton {
             screenPreferences = settings.screenPreferences !== undefined ? settings.screenPreferences : ({});
             animationSpeed = settings.animationSpeed !== undefined ? settings.animationSpeed : 2;
             wallpaperFillMode = settings.wallpaperFillMode !== undefined ? settings.wallpaperFillMode : "Fill";
+            wallpaperBackgroundColorMode = settings.wallpaperBackgroundColorMode !== undefined ? settings.wallpaperBackgroundColorMode : "black";
+            wallpaperBackgroundCustomColor = settings.wallpaperBackgroundCustomColor !== undefined ? settings.wallpaperBackgroundCustomColor : "#000000";
 
             if (typeof Theme !== "undefined") {
                 if (currentThemeName === "custom" && customThemeFile) {

quickshell/Modules/Greetd/GreeterContent.qml

@@ -794,6 +794,11 @@ Item {
         }
     }
 
+    Rectangle {
+        anchors.fill: parent
+        color: GreetdSettings.effectiveWallpaperBackgroundColor
+    }
+
     DankBackdrop {
         anchors.fill: parent
         screenName: root.screenName

quickshell/Modules/Lock/LockScreenContent.qml

@@ -182,6 +182,11 @@ Item {
         }
     }
 
+    Rectangle {
+        anchors.fill: parent
+        color: SettingsData.effectiveWallpaperBackgroundColor
+    }
+
     Loader {
         anchors.fill: parent
         active: {

quickshell/Modules/Settings/WallpaperTab.qml

@@ -354,6 +354,28 @@ Item {
                     }
                 }
 
+                ColorDropdownRow {
+                    tab: "wallpaper"
+                    tags: ["background", "color", "fill", "fit", "custom"]
+                    settingKey: "wallpaperBackgroundColorMode"
+                    text: I18n.tr("Background Color")
+                    description: I18n.tr("Color shown for areas not covered by wallpaper (e.g. Fit or Pad modes)")
+                    visible: root.currentWallpaper !== "" && !root.currentWallpaper.startsWith("#")
+                    dropdownWidth: 220
+                    options: [
+                        { "value": "black", "label": I18n.tr("Black") },
+                        { "value": "white", "label": I18n.tr("White") },
+                        { "value": "primary", "label": I18n.tr("Primary Theme Color") },
+                        { "value": "surface", "label": I18n.tr("Surface Container") },
+                        { "value": "custom", "label": I18n.tr("Custom") }
+                    ]
+                    currentMode: SettingsData.wallpaperBackgroundColorMode
+                    customColor: SettingsData.wallpaperBackgroundCustomColor || "#000000"
+                    pickerTitle: I18n.tr("Wallpaper Background Color")
+                    onModeSelected: mode => SettingsData.set("wallpaperBackgroundColorMode", mode)
+                    onCustomColorSelected: selectedColor => SettingsData.set("wallpaperBackgroundCustomColor", selectedColor.toString())
+                }
+
                 Rectangle {
                     width: parent.width
                     height: 1

quickshell/Modules/WallpaperBackground.qml

@@ -42,6 +42,11 @@ Variants {
             id: root
             anchors.fill: parent
 
+            Rectangle {
+                anchors.fill: parent
+                color: SettingsData.effectiveWallpaperBackgroundColor
+            }
+
             function encodeFileUrl(path) {
                 if (!path)
                     return "";
@@ -131,6 +136,12 @@ Variants {
                 function onWallpaperFillModeChanged() {
                     root.invalidate();
                 }
+                function onWallpaperBackgroundColorModeChanged() {
+                    root.invalidate();
+                }
+                function onWallpaperBackgroundCustomColorChanged() {
+                    root.invalidate();
+                }
             }
 
             Connections {

quickshell/translations/settings_search_index.json

@@ -343,28 +343,26 @@
     "category": "Personalization",
     "keywords": [
       "appearance",
+      "areas",
       "background",
       "bg",
+      "color",
+      "colour",
+      "covered",
       "custom",
       "customize",
-      "dark",
-      "dark mode",
-      "day",
       "desktop",
-      "different",
+      "hue",
       "image",
-      "light",
-      "light mode",
-      "mode",
-      "night",
       "personal",
       "personalization",
       "picture",
-      "wallpaper",
+      "shown",
-      "wallpapers"
+      "tint",
+      "wallpaper"
     ],
     "icon": "wallpaper",
-    "description": "Set different wallpapers for light and dark mode"
+    "description": "Color shown for areas not covered by wallpaper (e.g. Fit or Pad modes)"
   },
   {
     "section": "selectedMonitor",