feat(lockscreen): add lockscreen-specific wallpaper target in unified wallpaper selector

Fixes #1641

Written mostly by an LLM since I don't know QML, works fine from my
testing however.

Currently there seems to be a 1-2s delay before loading the image with
a custom lockscreen wallpaper set when locking, if anyone has any idea
why or how to fix, please help!

- add lockscreen wallpaper light/dark settings and service APIs
- expose desktop vs lockscreen target tabs in Wallpaper panel
- fallback to desktop wallpaper when lockscreen wallpaper unset
- allow selector access when wallpaper management disabled via lockscreen override toggle

Co-authored-by: pi with GPT-5.3-Codex <pi-gpt-5.3-codex@codex.local>

Author: bitbloxhub

Assets/Translations/en.json

@@ -1438,6 +1438,8 @@
       "compact-lockscreen-label": "Compact lock screen",
       "enable-lockscreen-media-controls-description": "Show interactive media playback controls on the lock screen.",
       "enable-lockscreen-media-controls-label": "Lock screen media controls",
+      "enable-lock-screen-wallpaper-description": "When desktop wallpaper management is disabled, keep lock screen wallpaper rendering enabled.",
+      "enable-lock-screen-wallpaper-label": "Enable lock screen wallpaper",
       "lock-on-suspend-description": "Automatically lock the screen when suspending the system.",
       "lock-on-suspend-label": "Lock on suspend",
       "lock-screen-animations-description": "Enable or disable lockscreen animations.",
@@ -2082,6 +2084,8 @@
       "apikey-placeholder": "Enter your Wallhaven API Key",
       "appearance-dark-tab": "Dark",
       "appearance-light-tab": "Light",
+      "target-desktop-tab": "Desktop",
+      "target-lock-screen-tab": "Lock screen",
       "categories-anime": "Anime",
       "categories-label": "Categories",
       "categories-people": "People",

Assets/settings-default.json

@@ -192,6 +192,7 @@
   },
   "wallpaper": {
     "enabled": true,
+    "enableLockScreenWallpaper": false,
     "overviewEnabled": false,
     "directory": "",
     "monitorDirectories": [],
@@ -200,6 +201,8 @@
     "viewMode": "single",
     "setWallpaperOnAllMonitors": true,
     "linkLightAndDarkWallpapers": true,
+    "lockScreenWallpaperLight": "",
+    "lockScreenWallpaperDark": "",
     "fillMode": "crop",
     "fillColor": "#000000",
     "useSolidColor": false,

Assets/settings-search-index.json

@@ -1709,6 +1709,18 @@
       "!Settings.data.general.compactLockScreen"
     ]
   },
+  {
+    "labelKey": "panels.lock-screen.enable-lock-screen-wallpaper-label",
+    "descriptionKey": "panels.lock-screen.enable-lock-screen-wallpaper-description",
+    "widget": "NToggle",
+    "tab": 11,
+    "tabLabel": "panels.lock-screen.title",
+    "subTab": 0,
+    "subTabLabel": "common.appearance",
+    "visibleWhen": [
+      "!Settings.data.wallpaper.enabled"
+    ]
+  },
   {
     "labelKey": "panels.lock-screen.lock-screen-animations-label",
     "descriptionKey": "panels.lock-screen.lock-screen-animations-description",

Commons/Settings.qml

@@ -405,6 +405,7 @@ Singleton {
     // wallpaper
     property JsonObject wallpaper: JsonObject {
       property bool enabled: true
+      property bool enableLockScreenWallpaper: false
       property bool overviewEnabled: false
       property string directory: ""
       property list<var> monitorDirectories: []
@@ -413,6 +414,8 @@ Singleton {
       property string viewMode: "single" // "single" | "recursive" | "browse"
       property bool setWallpaperOnAllMonitors: true
       property bool linkLightAndDarkWallpapers: true
+      property string lockScreenWallpaperLight: ""
+      property string lockScreenWallpaperDark: ""
       property string fillMode: "crop"
       property color fillColor: "#000000"
       property bool useSolidColor: false

Modules/Bar/Widgets/WallpaperSelector.qml

@@ -32,7 +32,7 @@ NIconButton {
 
   readonly property string iconColorKey: widgetSettings.iconColor !== undefined ? widgetSettings.iconColor : widgetMetadata.iconColor
 
-  enabled: Settings.data.wallpaper.enabled
+  enabled: Settings.data.wallpaper.enabled || Settings.data.wallpaper.enableLockScreenWallpaper
   baseSize: Style.getCapsuleHeightForScreen(screen?.name)
   applyUiScale: false
   customRadius: Style.radiusL

Modules/LockScreen/LockScreenBackground.qml

@@ -13,6 +13,7 @@ Item {
   // Cached wallpaper path - exposed for parent components
   property string resolvedWallpaperPath: ""
   property color tintColor: Settings.data.colorSchemes.darkMode ? Color.mSurface : Color.mOnSurface
+  readonly property bool lockScreenWallpaperEnabled: Settings.data.wallpaper.enabled || Settings.data.wallpaper.enableLockScreenWallpaper
 
   required property var screen
 
@@ -43,6 +44,19 @@ Item {
         Qt.callLater(requestCachedWallpaper);
       }
     }
+    function onLockScreenWallpaperChanged(path) {
+      Qt.callLater(requestCachedWallpaper);
+    }
+  }
+
+  Connections {
+    target: Settings.data.wallpaper
+    function onEnabledChanged() {
+      Qt.callLater(requestCachedWallpaper);
+    }
+    function onEnableLockScreenWallpaperChanged() {
+      Qt.callLater(requestCachedWallpaper);
+    }
   }
 
   // Listen for display scale changes
@@ -60,13 +74,18 @@ Item {
       return;
     }
 
+    if (!lockScreenWallpaperEnabled) {
+      resolvedWallpaperPath = "";
+      return;
+    }
+
     // Check for solid color mode first
     if (Settings.data.wallpaper.useSolidColor) {
       resolvedWallpaperPath = "";
       return;
     }
 
-    const originalPath = WallpaperService.getWallpaper(screen.name) || "";
+    const originalPath = WallpaperService.getLockScreenWallpaper(screen.name) || "";
     if (originalPath === "") {
       resolvedWallpaperPath = "";
       return;
@@ -91,14 +110,11 @@ Item {
       return;
     }
 
-    // Don't set resolvedWallpaperPath until cache is ready
-    // This prevents loading the original huge image
+    // Show original immediately, then swap to cached when ready
+    resolvedWallpaperPath = originalPath
     ImageCacheService.getLarge(originalPath, targetWidth, targetHeight, function (cachedPath, success) {
       if (success) {
         resolvedWallpaperPath = cachedPath;
-      } else {
-        // Only fall back to original if caching failed
-        resolvedWallpaperPath = originalPath;
       }
     });
   }
@@ -111,7 +127,7 @@ Item {
 
   Image {
     id: lockBgImage
-    visible: source !== "" && Settings.data.wallpaper.enabled && !Settings.data.wallpaper.useSolidColor && (!PowerProfileService.noctaliaPerformanceMode || !Settings.data.noctaliaPerformance.disableWallpaper)
+    visible: source !== "" && lockScreenWallpaperEnabled && !Settings.data.wallpaper.useSolidColor && (!PowerProfileService.noctaliaPerformanceMode || !Settings.data.noctaliaPerformance.disableWallpaper)
     anchors.fill: parent
     fillMode: Image.PreserveAspectCrop
     source: resolvedWallpaperPath

Modules/Panels/ControlCenter/Widgets/WallpaperSelector.qml

@@ -7,7 +7,7 @@ import qs.Widgets
 NIconButtonHot {
   property ShellScreen screen
 
-  enabled: Settings.data.wallpaper.enabled
+  enabled: Settings.data.wallpaper.enabled || Settings.data.wallpaper.enableLockScreenWallpaper
   icon: "wallpaper-selector"
   tooltipText: I18n.tr("wallpaper.panel.title")
   onClicked: PanelService.getPanel("wallpaperPanel", screen)?.toggle()

Modules/Panels/Settings/Tabs/LockScreen/AppearanceSubTab.qml

@@ -85,6 +85,15 @@ ColumnLayout {
     defaultValue: Settings.getDefaultValue("general.enableLockScreenMediaControls")
   }
 
+  NToggle {
+    label: I18n.tr("panels.lock-screen.enable-lock-screen-wallpaper-label")
+    description: I18n.tr("panels.lock-screen.enable-lock-screen-wallpaper-description")
+    checked: Settings.data.wallpaper.enableLockScreenWallpaper
+    onToggled: checked => Settings.data.wallpaper.enableLockScreenWallpaper = checked
+    visible: !Settings.data.wallpaper.enabled
+    defaultValue: Settings.getDefaultValue("wallpaper.enableLockScreenWallpaper")
+  }
+
   NToggle {
     label: I18n.tr("panels.lock-screen.lock-screen-animations-label")
     description: I18n.tr("panels.lock-screen.lock-screen-animations-description")

Modules/Panels/Settings/Tabs/Wallpaper/GeneralSubTab.qml

@@ -26,7 +26,7 @@ ColumnLayout {
   }
 
   ColumnLayout {
-    enabled: Settings.data.wallpaper.enabled
+    enabled: Settings.data.wallpaper.enabled || Settings.data.wallpaper.enableLockScreenWallpaper
     spacing: Style.marginL
     Layout.fillWidth: true
 

Modules/Panels/Wallpaper/WallpaperPanel.qml

@@ -141,10 +141,10 @@ SmartPanel {
     property var currentScreen: Quickshell.screens[currentScreenIndex]
     property string filterText: ""
     property int appearanceTabIndex: 0
+    property int wallpaperTargetTabIndex: 0 // 0 = desktop, 1 = lock screen
     readonly property bool headerScreensStripAvailable: !Settings.data.wallpaper.setWallpaperOnAllMonitors || Settings.data.wallpaper.enableMultiMonitorDirectories
     readonly property bool headerDevicesButtonVisible: Quickshell.screens.length > 1 || Settings.data.wallpaper.enableMultiMonitorDirectories
     property alias screenRepeater: screenRepeater
-
     Component.onCompleted: {
       root.contentItem = panelContent;
     }
@@ -182,6 +182,13 @@ SmartPanel {
       }
     }
 
+    function getSelectedTargetWallpaper(screenName) {
+      if (wallpaperTargetTabIndex === 1) {
+        return WallpaperService.getLockScreenWallpaper(screenName);
+      }
+      return WallpaperService.getWallpaperPathForSlot(screenName, WallpaperService.wallpaperSelectionAppearance);
+    }
+
     color: "transparent"
 
     // Wallhaven settings popup
@@ -222,6 +229,7 @@ SmartPanel {
           wallhavenView.gridView.currentIndex = -1;
         }
         panelContent.appearanceTabIndex = Settings.data.colorSchemes.darkMode ? 1 : 0;
+        panelContent.wallpaperTargetTabIndex = (!Settings.data.wallpaper.enabled && Settings.data.wallpaper.enableLockScreenWallpaper) ? 1 : 0;
         WallpaperService.wallpaperSelectionAppearance = panelContent.appearanceTabIndex === 1 ? "dark" : "light";
         // Give initial focus to search input
         Qt.callLater(() => {
@@ -297,7 +305,7 @@ SmartPanel {
             }
 
             NIconButton {
-              visible: Settings.data.wallpaper.enabled
+              visible: Settings.data.wallpaper.enabled || Settings.data.wallpaper.enableLockScreenWallpaper
               icon: "dark-mode"
               tooltipText: Settings.data.wallpaper.linkLightAndDarkWallpapers ? I18n.tr("wallpaper.panel.header-separate-light-dark-tooltip") : I18n.tr("wallpaper.panel.header-link-light-dark-tooltip")
               baseSize: Style.baseWidgetSize * 0.8
@@ -350,7 +358,7 @@ SmartPanel {
 
           NTabBar {
             id: appearanceTabBar
-            visible: Settings.data.wallpaper.enabled && !Settings.data.wallpaper.linkLightAndDarkWallpapers
+            visible: (Settings.data.wallpaper.enabled || Settings.data.wallpaper.enableLockScreenWallpaper) && !Settings.data.wallpaper.linkLightAndDarkWallpapers
             Layout.fillWidth: true
             currentIndex: panelContent.appearanceTabIndex
             spacing: Style.marginM
@@ -377,6 +385,39 @@ SmartPanel {
             }
           }
 
+          NTabBar {
+            id: wallpaperTargetTabBar
+            visible: Settings.data.wallpaper.enabled || Settings.data.wallpaper.enableLockScreenWallpaper
+            Layout.fillWidth: true
+            currentIndex: panelContent.wallpaperTargetTabIndex
+            spacing: Style.marginM
+            distributeEvenly: true
+
+            onCurrentIndexChanged: {
+              if (currentIndex < 0) {
+                return;
+              }
+              panelContent.wallpaperTargetTabIndex = currentIndex;
+              for (var i = 0; i < screenRepeater.count; i++) {
+                let item = screenRepeater.itemAt(i);
+                if (item && item.refreshWallpaperScreenData) {
+                  item.refreshWallpaperScreenData();
+                }
+              }
+            }
+
+            NTabButton {
+              text: I18n.tr("wallpaper.panel.target-desktop-tab")
+              tabIndex: 0
+              checked: wallpaperTargetTabBar.currentIndex === 0
+            }
+            NTabButton {
+              text: I18n.tr("wallpaper.panel.target-lock-screen-tab")
+              tabIndex: 1
+              checked: wallpaperTargetTabBar.currentIndex === 1
+            }
+          }
+
           NTabBar {
             id: screenTabBar
             visible: panelContent.headerScreensStripAvailable
@@ -829,12 +870,17 @@ SmartPanel {
       target: WallpaperService
       function onWallpaperChanged(screenName, path) {
         if (targetScreen !== null && screenName === targetScreen.name) {
-          currentWallpaper = WallpaperService.getWallpaperPathForSlot(targetScreen.name, WallpaperService.wallpaperSelectionAppearance);
+          currentWallpaper = panelContent.getSelectedTargetWallpaper(targetScreen.name);
+        }
+      }
+      function onLockScreenWallpaperChanged(path) {
+        if (targetScreen !== null) {
+          currentWallpaper = panelContent.getSelectedTargetWallpaper(targetScreen.name);
         }
       }
       function onWallpaperSelectionAppearanceChanged() {
         if (targetScreen !== null) {
-          currentWallpaper = WallpaperService.getWallpaperPathForSlot(targetScreen.name, WallpaperService.wallpaperSelectionAppearance);
+          currentWallpaper = panelContent.getSelectedTargetWallpaper(targetScreen.name);
           updateFiltered(false);
         }
       }
@@ -869,7 +915,7 @@ SmartPanel {
         return;
       }
 
-      currentWallpaper = WallpaperService.getWallpaperPathForSlot(targetScreen.name, WallpaperService.wallpaperSelectionAppearance);
+      currentWallpaper = panelContent.getSelectedTargetWallpaper(targetScreen.name);
 
       if (isBrowseMode) {
         // In browse mode, scan current directory for both files and directories
@@ -899,12 +945,15 @@ SmartPanel {
       if (isDirectory) {
         WallpaperService.setBrowsePath(targetScreen.name, path);
       } else {
-        var screen = Settings.data.wallpaper.setWallpaperOnAllMonitors ? undefined : targetScreen.name;
-        WallpaperService.changeWallpaper(path, screen, WallpaperService.wallpaperSelectionAppearance);
-        WallpaperService.applyFavoriteTheme(path, screen, WallpaperService.wallpaperSelectionAppearance);
+        if (panelContent.wallpaperTargetTabIndex === 1) {
+          WallpaperService.changeLockScreenWallpaper(path, WallpaperService.wallpaperSelectionAppearance);
+        } else {
+          var screen = Settings.data.wallpaper.setWallpaperOnAllMonitors ? undefined : targetScreen.name;
+          WallpaperService.changeWallpaper(path, screen, WallpaperService.wallpaperSelectionAppearance);
+          WallpaperService.applyFavoriteTheme(path, screen, WallpaperService.wallpaperSelectionAppearance);
+        }
       }
     }
-
     // Helper function to cycle view modes
     function cycleViewMode() {
       var mode = Settings.data.wallpaper.viewMode;
@@ -1922,13 +1971,17 @@ SmartPanel {
       if (typeof WallhavenService !== "undefined") {
         WallhavenService.downloadWallpaper(wallpaper, function (success, localPath) {
           if (success) {
-            var whScreen = Settings.data.wallpaper.setWallpaperOnAllMonitors ? undefined : Quickshell.screens[currentScreenIndex].name;
-            if (!Settings.data.wallpaper.setWallpaperOnAllMonitors && currentScreenIndex < Quickshell.screens.length) {
-              WallpaperService.changeWallpaper(localPath, Quickshell.screens[currentScreenIndex].name, WallpaperService.wallpaperSelectionAppearance);
+            if (panelContent.wallpaperTargetTabIndex === 1) {
+              WallpaperService.changeLockScreenWallpaper(localPath, WallpaperService.wallpaperSelectionAppearance);
             } else {
-              WallpaperService.changeWallpaper(localPath, undefined, WallpaperService.wallpaperSelectionAppearance);
+              var whScreen = Settings.data.wallpaper.setWallpaperOnAllMonitors ? undefined : Quickshell.screens[currentScreenIndex].name;
+              if (!Settings.data.wallpaper.setWallpaperOnAllMonitors && currentScreenIndex < Quickshell.screens.length) {
+                WallpaperService.changeWallpaper(localPath, Quickshell.screens[currentScreenIndex].name, WallpaperService.wallpaperSelectionAppearance);
+              } else {
+                WallpaperService.changeWallpaper(localPath, undefined, WallpaperService.wallpaperSelectionAppearance);
+              }
+              WallpaperService.applyFavoriteTheme(localPath, whScreen, WallpaperService.wallpaperSelectionAppearance);
             }
-            WallpaperService.applyFavoriteTheme(localPath, whScreen, WallpaperService.wallpaperSelectionAppearance);
           }
         });
       }