MU-Wallpaper Version 1.0.4
License: GPL V2

WELCOME TO MU-WALLPAPER

Mu-wallpaper is a fast, lightweight desktop wallpaper manager designed specifically for lightweight window managers and X11 multi-monitor setups. If you have multiple screens arranged via Xinerama, this tool lets you browse your image collection through a clean, responsive thumbnail grid and easily customize your workspace.

By default, double-clicking any image automatically applies it across all of your screens independently, scaling and fitting each picture perfectly to match every individual monitor without distortion. If you prefer variety, you can right-click any image to open a handy context menu. From there, you can choose to target a specific monitor in isolation—such as Screen 1 or Screen 2—leaving your other monitors completely untouched with their current wallpapers intact.

The software also features quick shortcuts to open your selected photos directly in external image editors like GIMP or mtPaint for quick touch-ups. Best of all, mu-wallpaper automatically saves your preferences. Whenever your session restarts or your window manager boots up, it automatically restores your last used wallpaper configuration with zero manual effort required.

RESTORING BACKGROUNDS AT STARTUP

Mu-wallpaper automatically saves your chosen wallpaper and monitor targets to a configuration file located at ~/.config/mu-wallpaper/current whenever you apply a background.

To automatically restore your backgrounds when your window manager or session starts up, you can configure your specific desktop environment or window manager startup mechanism:

1. IceWM:
Add the following line to your IceWM startup script (typically located at ~/.icewm/startup):
mu-wallpaperset &
Make sure your startup script is marked as executable by running: chmod +x ~/.icewm/startup
2. Fluxbox:
Add the following line to your Fluxbox startup file (located at ~/.fluxbox/startup) just before the exec line:
mu-wallpaperset &
3. JWM (Puppy Linux):
Add a StartupCommand tag inside your user configuration file (located at ~/.jwmrc or your personal configuration file):
mu-wallpaperset &

When mu-wallpaperset is executed with zero arguments during startup, it reads your saved preference file and applies your custom layout instantly.

STATUS OF THE SHELL SCRIPT

Please note that the old shell script wrapper (mu-wallpaperset.sh) is no longer used or required. It has been fully replaced by a native, high-performance compiled binary named mu-wallpaperset. This native Vala utility handles X11 root window atoms, per-monitor independent scaling, surface compositing, and startup configurations directly and efficiently.

COMPILATION INSTRUCTIONS

To build both mu-wallpaper and mu-wallpaperset from source, ensure you have the Vala compiler, GTK3 development libraries, Cairo, and Xlib development headers installed on your system (e.g., libgtk-3-dev, libgee-0.8-dev, libx11-dev, valac).

You can compile the binaries using the Vala compiler directly from your terminal using the following terminal commands:

1. Compile the wallpaper setter backend:
valac --pkg gtk+-3.0 --pkg gdk-3.0 --pkg cairo mu-wallpaperset.vala -o mu-wallpaperset
2. Compile the graphical frontend application:
valac --pkg gtk+-3.0 --pkg gdk-3.0 --pkg posix mu-wallpaper.vala -o mu-wallpaper

Once compiled, you can place both binaries into your system path (such as /usr/local/bin/) or run them locally from your working directory.

TECHNICAL SPECIFICATIONS & ARCHITECTURE

Mu-wallpaper is split into two primary, high-performance Vala components built on GTK3, Cairo, and Xlib:

1. mu-wallpaper.vala (Graphical Frontend):

* Written as a Gtk.Application supporting command-line arguments for custom wallpaper directories and background commands.
* Implements an asynchronous thumbnail generation pipeline that scans directories for PNG and JPEG files, scales them efficiently via GLib asynchronous streams and Gdk.Pixbuf, caches results locally, and automatically cleans up orphaned thumbnails.
* Features drag-and-drop support (text/uri-list), alphabetical sorting via GLib.GenericArray, and a dynamic Gtk.Menu context menu that queries active Gdk monitors to build per-screen target actions dynamically.

2. mu-wallpaperset.vala (X11 Backend & Root Manager):

* A native utility interfacing directly with Xlib and Cairo-Xlib surfaces to manage root window backgrounds under X11/Xinerama.
* Manages standard X11 root window atoms (_XROOTPMAP_ID and ESETROOT_PMAP_ID) and uses XSetCloseDownMode with RetainPermanent to prevent background pixmaps from being purged when client applications exit.
* Performs independent per-monitor scaling calculations (aspect-ratio preservation with coordinate clamping) across virtual desktop bounds.
* Implements intelligent surface compositing to read existing root pixmaps when targeting single monitors, ensuring non-targeted screens preserve their current wallpapers instead of reverting to black.
* Persists session choices to ~/.config/mu-wallpaper/current for seamless zero-argument startup restoration.

Here is a concise changelog entry documenting the latest improvements:

### Changelog: v1.0.4

* 1/4 size thumbnails option.
* folder selection
* Progress Status Integration: Added real-time generation progress feedback in the window title (`mu-wallpaper [Generating thumbnails: X/Y ...]`) during cache building.

Note: I have 400 JPGs in ~Wallpapers, building thumbnails can take 20 seconds.
For this reason now ~/Wallpapers/ as "main" folder will always use a different thumbnail cache than any other folder.

* Async Loading & Race Condition Prevention**: Introduced a `Cancellable` token and batch-buffered item collection to eliminate sorting glitches, blank slots, and thread/race conditions during folder switches.
* Isolated Caching: Separated caching paths into distinct subdirectories (`main/` for `~/Wallpapers` and `custom/` for external folders) to preserve primary collection thumbnails permanently and prevent accidental deletions.

## License

Distributed under the **GPL-2.0-or-later** license. See source files for details.