wallpaper

To use this library in your Go project, install it using go get:

go get github.com/reujab/wallpaper

The wallpaper package provides functions to retrieve the current wallpaper path and set new wallpapers using local files or URLs. You can also configure the scaling mode (e.g., wallpaper.Crop).

package main

import (
	"fmt"

	"github.com/reujab/wallpaper"
)

func main() {
	// Get the current wallpaper path
	background, err := wallpaper.Get()
	if err != nil {
		panic(err)
	}
	fmt.Println("Current wallpaper:", background)

	// Set wallpaper from a local file
	err = wallpaper.SetFromFile("/usr/share/backgrounds/gnome/adwaita-day.jpg")
	if err != nil {
		panic(err)
	}

	// Set wallpaper from a URL
	err = wallpaper.SetFromURL("https://i.imgur.com/pIwrYeM.jpg")
	if err != nil {
		panic(err)
	}

	// Set the wallpaper mode (e.g., Crop)
	err = wallpaper.SetMode(wallpaper.Crop)
	if err != nil {
		panic(err)
	}
}

The library is cross-platform and supports the following environments:

Native Support:

• Windows
• macOS
• GNOME
• KDE
• Cinnamon
• Unity
• Budgie
• XFCE
• LXDE
• MATE
• Deepin

Special Requirements:

• Wayland compositors: Set only; requires swaybg to be installed.
• i3: Set only; requires feh to be installed.

Use SetFromFile(file string) to change the desktop wallpaper to the image located at the provided file path. The implementation varies based on the detected desktop environment:

• GNOME: Uses gsettings with a file:// URI.
• KDE/XFCE: Uses desktop-specific internal methods.
• Cinnamon/MATE/Deepin: Uses dconf to write the URI or filename.
• LXDE: Uses pcmanfm -w.
• Fallback: If the desktop is not explicitly recognized, it attempts to use swaybg or feh -bg-fill.

err := wallpaper.SetFromFile("/path/to/image.jpg")
if err != nil {
	// handle error
}

To change the wallpaper on an XFCE desktop, use the setXFCE function. This function identifies all active desktop properties associated with last-image via xfconf-query and updates them to the specified file path. It iterates through all detected desktop properties to ensure the change is applied across the environment.

err := wallpaper.setXFCE("/path/to/your/image.jpg")
if err != nil {
    // handle error
}

Use setKDEMode(mode Mode) to change how the wallpaper is scaled or positioned on KDE Plasma desktops. This function accepts a Mode type (defined in the package) and applies the corresponding KDE FillMode configuration to all desktops via qdbus.

err := wallpaper.setKDEMode(wallpaper.Fit)
if err != nil {
    // handle error
}

To change how the wallpaper is scaled or positioned on XFCE desktops, use setXFCEMode. This function maps the project's Mode type to XFCE-specific integer strings (via xfconf-query) and applies them to all detected image-style properties.

Supported mappings:

• Center -> "1"
• Tile -> "2"
• Stretch -> "3"
• Fit -> "4"
• Crop -> "5"
• Span -> "5"

err := wallpaper.setXFCEMode(wallpaper.Crop)
if err != nil {
    // handle error
}

Use SetMode(mode Mode) to configure how the wallpaper is displayed (e.g., stretched, centered, tiled). The mode parameter must be of type Mode.

Supported behaviors depend on the desktop environment's capabilities. For GNOME-compliant environments, it uses gsettings to set picture-options.

// Note: Mode is a type defined elsewhere in the package
err := wallpaper.SetMode(wallpaper.Scaled)
if err != nil {
	// handle error
}

Use Get() to retrieve the absolute POSIX path of the currently active desktop wallpaper. This function executes an AppleScript via osascript to query the Finder application.

path, err := wallpaper.Get()
if err != nil {
    // handle error
}
fmt.Println("Current wallpaper:", path)

The SetMode(mode Mode) function is available for API compatibility but performs no action on macOS. It returns nil immediately.

// This call is a no-op on macOS
err := wallpaper.SetMode(wallpaper.Center)

Use SetFromURL(url string) to set the desktop wallpaper using an image URL. This function automatically downloads the image to a local cache directory and then applies it as the wallpaper. It returns an error if the download fails or if the desktop environment does not support setting the wallpaper.

err := wallpaper.SetFromURL("https://example.com/image.jpg")
if err != nil {
	// handle error
}

Use Get() to retrieve the file path of the currently set wallpaper. The function detects the desktop environment (e.g., GNOME, KDE, XFCE, Cinnamon, MATE, LXDE, Deepin) and attempts to fetch the path using the appropriate system tools like gsettings or dconf.

path, err := wallpaper.Get()
if err != nil {
	// handle error
}
fmt.Println("Current wallpaper:", path)