refactor(wallpapers): centralize engine state handling in WallpaperManager

- Move engine enable/disable logic from WallpaperEngine into WallpaperManager.set_wallpaper()
- Add finished signal to WallpaperEngine instead of calling WallpaperManager directly
- Remove engine param from ImageGallery, callers now use unified manager API
- Consolidate set_wallpaper and _commit_wallpaper into single function
- Fix duplicate _run_after_thread call in change_background

Author: amnweb

src/core/widgets/services/wallpapers/wallpaper_engine.py

@@ -3,6 +3,7 @@
 """
 
 import ctypes
+import logging
 import math
 import os
 import winreg
@@ -22,8 +23,7 @@
     WS_POPUP,
 )
 
-from core.widgets.services.wallpapers.wallpaper_manager import WallpaperManager
-
+logger = logging.getLogger("wallpaper_engine")
 user32 = ctypes.WinDLL("user32", use_last_error=True)
 
 HWND = wintypes.HWND
@@ -153,6 +153,9 @@ def _read_background_color() -> QColor:
 def _locate_workerw() -> int:
     """Find the WorkerW window that sits behind desktop icons."""
     progman = user32.FindWindowW("Progman", None)
+    if not progman:
+        logger.warning("Could not locate Progman. Wallpaper animation skipped.")
+        return 0
     user32.SendMessageTimeoutW(progman, WM_SPAWN_WORKER, 0, 0, 0, 1000, ctypes.byref(ULONG_PTR()))
     worker = HWND()
 
@@ -187,14 +190,17 @@ def _enum_proc(hwnd, _):
         user32.EnumWindows(_enum_proc, 0)
 
     if not worker:
-        raise RuntimeError("Could not locate WorkerW")
+        logger.warning("Could not locate WorkerW. Wallpaper animation skipped.")
+        return 0
     user32.ShowWindow(worker, 5)
     return worker
 
 
-def _attach_to_workerw(widget: QWidget) -> None:
+def _attach_to_workerw(widget: QWidget) -> bool:
     """Parent *widget* to WorkerW and compute per-monitor screen areas."""
     worker = _locate_workerw()
+    if not worker:
+        return False
     hwnd = HWND(int(widget.winId()))
 
     exstyle = GetWindowLongPtr(hwnd, GWL_EXSTYLE)
@@ -216,6 +222,7 @@ def _attach_to_workerw(widget: QWidget) -> None:
     widget.set_screen_areas(areas)
 
     user32.SetWindowPos(hwnd, HWND_TOP, 0, 0, ww, wh, SWP_NOACTIVATE | SWP_FRAMECHANGED)
+    return True
 
 
 class _ImageLoader(QThread):
@@ -238,6 +245,8 @@ class WallpaperEngine(QWidget):
     _ANIMATION_MS = 1200
     _FRAME_MS = 16
 
+    finished = pyqtSignal()
+
     def __init__(self, image_path: str, animation: str = "circle") -> None:
         super().__init__()
         self._image_path = image_path
@@ -277,17 +286,18 @@ def _on_images_loaded(self, new_img: QImage, old_img: QImage) -> None:
         self._pixmap_new = QPixmap.fromImage(new_img)
         self._pixmap_old = QPixmap.fromImage(old_img)
 
-        # If either image fails to load, skip animation and set wallpaper immediately
+        # If either image fails to load, skip animation and let caller commit immediately
         if self._pixmap_new.isNull() or self._pixmap_old.isNull():
-            try:
-                WallpaperManager().set_wallpaper(self._image_path)
-            except Exception:
-                pass
+            self.finished.emit()
             self.deleteLater()
             return
 
         self.setWindowOpacity(0.0)
-        _attach_to_workerw(self)
+        if not _attach_to_workerw(self):
+            self.finished.emit()
+            self.deleteLater()
+            return
+
         self.show()
         QTimer.singleShot(0, self._start_fade_in)
 
@@ -487,10 +497,7 @@ def _on_finished(self) -> None:
         self.update()
         if not self._committed:
             self._committed = True
-            try:
-                WallpaperManager().set_wallpaper(self._image_path)
-            except Exception:
-                pass
+            self.finished.emit()
 
     def _clip_path_for_monitor(self, dx: int, dy: int, dw: int, dh: int, t: float) -> QPainterPath:
         """Reveal shape for the new wallpaper."""

src/core/widgets/services/wallpapers/wallpaper_manager.py

@@ -11,6 +11,7 @@
 
 from core.events.service import EventService
 from core.utils.win32.bindings.shell32 import IDesktopWallpaper
+from core.widgets.services.wallpapers.wallpaper_engine import WallpaperEngine
 
 
 class WallpaperManager(QObject):
@@ -37,6 +38,8 @@ def __init__(self):
         self._is_running = False
         self._last_image = None
         self._timer_running = False
+        self._engine_config = None
+        self._engine = None
 
         self._event_service = EventService()
 
@@ -45,7 +48,12 @@ def __init__(self):
         self._event_service.register_event("set_wallpaper_signal", self._set_wallpaper_signal)
 
     def configure(
-        self, image_path: str | list[str], update_interval: int, change_automatically: bool, run_after: list[str]
+        self,
+        image_path: str | list[str],
+        update_interval: int,
+        change_automatically: bool,
+        run_after: list[str],
+        engine=None,
     ):
         """
         Configure the manager.
@@ -56,6 +64,7 @@ def configure(
             self._image_paths = image_path
 
         self._run_after = run_after
+        self._engine_config = engine
 
         if change_automatically and not self._timer_running:
             if update_interval and update_interval > 0:
@@ -68,23 +77,27 @@ def configure(
     def _timer_callback(self):
         self.change_background()
 
-    def set_wallpaper(self, image_path: str, monitor_id: str | None = None):
-        """
-        Set the desktop wallpaper using the IDesktopWallpaper COM interface.
-        Args:
-            image_path: Absolute path to the wallpaper image file
-            monitor_id: Monitor device path from GetMonitorDevicePathAt, or None for all monitors
-        """
+    def set_wallpaper(self, image_path: str, monitor_id: str | None = None, animate: bool = True):
+        """Set the desktop wallpaper, using the YASB engine animation when enabled."""
+        eng = self._engine_config
+        if animate and monitor_id is None and eng and eng.enabled:
+            try:
+                self._engine = WallpaperEngine(image_path, eng.animation)
+                self._engine.finished.connect(lambda: self.set_wallpaper(image_path, animate=False))
+                self._engine.start()
+                return
+            except Exception as e:
+                logging.error("Wallpaper engine failed, falling back: %s", e)
+
         pythoncom.CoInitialize()
         try:
-            desktop_wallpaper_clsid = GUID("{C2CF3110-460E-4fc1-B9D0-8A1C0C9CC4BD}")
-            desktop_wallpaper = comtypes.client.CreateObject(desktop_wallpaper_clsid, interface=IDesktopWallpaper)
-            abs_path = os.path.abspath(image_path)
-            desktop_wallpaper.SetWallpaper(monitor_id, abs_path)
-
+            clsid = GUID("{C2CF3110-460E-4fc1-B9D0-8A1C0C9CC4BD}")
+            dwp = comtypes.client.CreateObject(clsid, interface=IDesktopWallpaper)
+            dwp.SetWallpaper(monitor_id, os.path.abspath(image_path))
         except Exception as e:
-            logging.error("Failed to set wallpaper using IDesktopWallpaper: %s", e)
-            raise
+            logging.error("Failed to set wallpaper: %s", e)
+            self._is_running = False
+            return
         self._run_after_thread(image_path)
 
     def get_monitor_ids(self) -> list[str]:
@@ -139,7 +152,7 @@ def change_background(self, image_path: str = None):
             self._last_image = new_wallpaper
         except Exception as e:
             logging.error("Error setting wallpaper %s: %s", new_wallpaper, e)
-        self._run_after_thread(new_wallpaper)
+            self._is_running = False
 
     def _run_after_thread(self, image_path: str):
         if self._run_after:

src/core/widgets/services/wallpapers/wallpapers_gallery.py

@@ -34,7 +34,6 @@
 from core.utils.win32.backdrop import enable_blur
 from core.utils.win32.utils import apply_qmenu_style
 from core.utils.win32.window_actions import force_foreground_focus
-from core.widgets.services.wallpapers.wallpaper_engine import WallpaperEngine
 from core.widgets.services.wallpapers.wallpaper_manager import WallpaperManager
 
 
@@ -159,10 +158,9 @@ def run(self):
 class ImageGallery(QMainWindow):
     """ImageGallery displays a gallery of images with navigation and lazy loading features."""
 
-    def __init__(self, image_paths, gallery, engine=None):
+    def __init__(self, image_paths, gallery):
         super().__init__()
         self.gallery = gallery
-        self.engine = engine  # EngineConfig | None
 
         if isinstance(image_paths, str):
             self.image_paths = [image_paths]
@@ -684,20 +682,13 @@ def show_context_menu_for_image(self, index: int, pos):
     def _apply_wallpaper_on_monitor(self, image_path: str, monitor_id: str) -> None:
         """Set wallpaper on a specific monitor (no animation)."""
         self.fade_out_and_close_gallery()
-        WallpaperManager().set_wallpaper(image_path, monitor_id=monitor_id)
+        WallpaperManager().set_wallpaper(image_path, monitor_id=monitor_id, animate=False)
 
     def _apply_wallpaper(self, image_path: str, monitor_id: str | None) -> None:
-        """Apply wallpaper with engine animation (all screens) or direct per-monitor."""
+        """Apply wallpaper. The manager handles engine animation and fallbacks."""
         if monitor_id is None:
-            animation = self.engine.animation if self.engine else "circle"
-            if self.engine and self.engine.enabled:
-                self.fade_out_and_close_gallery()
-                self._engine = WallpaperEngine(image_path, animation)
-                self._engine.destroyed.connect(lambda: setattr(self, "_engine", None))
-                self._engine.start()
-            else:
-                self.fade_out_and_close_gallery()
-                WallpaperManager().set_wallpaper(image_path)
+            self.fade_out_and_close_gallery()
+            WallpaperManager().set_wallpaper(image_path)
         else:
             self._apply_wallpaper_on_monitor(image_path, monitor_id)
 

src/core/widgets/yasb/wallpapers.py

@@ -20,6 +20,7 @@ def __init__(self, config: WallpapersConfig):
             self.config.update_interval,
             self.config.change_automatically,
             self.config.run_after,
+            self.config.engine,
         )
 
         # Connect signals
@@ -56,6 +57,5 @@ def _toggle_widget(self):
             self._image_gallery = ImageGallery(
                 self.config.image_path,
                 self.config.gallery.model_dump(),
-                self.config.engine,
             )
             self._image_gallery.fade_in_gallery(parent=self)