Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorShell::WallpaperService Class Reference

The shell's own wallpaper: which image each output shows. More...

#include <PhosphorShell/WallpaperService.h>

Inheritance diagram for PhosphorShell::WallpaperService:
[legend]

Signals

void imageChanged ()
void pathChanged ()
void effectivePathChanged (const QString &screenName)
 The answer to effectivePath(screenName) may have changed.

Public Member Functions

 WallpaperService (const QString &storePath, QObject *parent=nullptr)
 The shell-wide configured wallpaper: the all-screens entry, or when only per-screen entries exist, the first of those by name.
 WallpaperService (const QString &storePath, std::unique_ptr< PhosphorShaders::IWallpaperProvider > seedProvider, QObject *parent=nullptr)
 Same, with the first-run seed source injected.
 ~WallpaperService () override
QString storePath () const
 Where the store lives, as the constructor was given it.
QImage image () const
QString path () const
bool isAvailable () const
QString configuredPath (const QString &screenName=QString()) const
 The persisted wallpaper for screenName: its own entry, else the all-screens entry, else empty.
QString previewPath (const QString &screenName=QString()) const
 The transient preview for screenName, resolved the same way.
QString effectivePath (const QString &screenName=QString()) const
 What a surface on screenName should draw: the preview when one is set, otherwise the configured path.
bool setPath (const QString &path, const QString &screenName=QString())
 Persist path as the wallpaper for screenName, or for every screen when the name is empty (which also drops the per-screen entries, since "all screens" means all of them).
bool setPreview (const QString &path, const QString &screenName=QString())
 Show path on screenName (every screen when empty) without persisting it.
void clearPreview (const QString &screenName=QString())
 Drop the preview for screenName, or every preview when the name is empty.
void setAppearance (const QVariantMap &wallpapers)
QVariantMap appearanceSeed () const
QString effectiveFit (const QString &screenName=QString()) const
void refresh ()
 Re-decode path into image, for a consumer that knows the file changed on disk under the same name.

Detailed Description

The shell's own wallpaper: which image each output shows.

The shell owns the wallpaper surface, so this service is the store the surface reads and the picker writes. It is not a view onto another desktop's configuration. The store is a per-screen map keyed by output name, where the empty key is the wallpaper every output without an entry of its own shows, persisted at the store path the app hands the constructor (ShellEngine passes <config>/<shellName>/wallpaper.json, beside the shell file the loader discovers).

Two layers sit on top of the configured map, both per screen and both keyed the same way:

  • the configured path: what setPath() wrote and what survives a restart;
  • a transient preview: setPreview() / clearPreview(), which the picker uses to paint a hovered candidate under the windows without committing it. Never persisted.

effectivePath(screen) is what a surface on that output should draw: the preview if one is set (for that screen, else for all screens), otherwise the configured path (for that screen, else for all screens). effectivePathChanged(screen) fires whenever that answer may have changed for screen, with the empty name meaning every output.

First run: when the store is empty the service seeds it ONCE from the desktop the user is coming from (through PhosphorShaders:: createWallpaperProvider(), which reads Plasma / Hyprland / sway / GNOME configuration), so an existing session does not go black. After that seed the store is authoritative and the other desktop's configuration is never consulted again.

image is the decoded path (the shell-wide wallpaper), decoded on a worker thread via QThreadPool because a 4 K PNG decode would visibly stutter the shell, and pre-converted to RGBA8888 for ShaderBackground:

ShaderBackground {
    useWallpaper: PhosphorShell.wallpaper.available
    wallpaperTexture: PhosphorShell.wallpaper.image
}

Threading: every public method MUST be called from the GUI thread. The decode worker marshals back via QMetaObject::invokeMethod, so consumers never see the worker's QImage directly.

Constructor & Destructor Documentation

◆ WallpaperService() [1/2]

PhosphorShell::WallpaperService::WallpaperService ( const QString & storePath,
QObject * parent = nullptr )
explicit

The shell-wide configured wallpaper: the all-screens entry, or when only per-screen entries exist, the first of those by name.

storePath is the JSON file the configured map is read from and saved to. Empty keeps the map in memory only.

◆ WallpaperService() [2/2]

PhosphorShell::WallpaperService::WallpaperService ( const QString & storePath,
std::unique_ptr< PhosphorShaders::IWallpaperProvider > seedProvider,
QObject * parent = nullptr )

Same, with the first-run seed source injected.

Tests hand in a fake so the seed can be asserted without a desktop; the other constructor uses PhosphorShaders::createWallpaperProvider(). Null means no seed source.

◆ ~WallpaperService()

PhosphorShell::WallpaperService::~WallpaperService ( )
override

Member Function Documentation

◆ appearanceSeed()

QVariantMap PhosphorShell::WallpaperService::appearanceSeed ( ) const

◆ clearPreview()

void PhosphorShell::WallpaperService::clearPreview ( const QString & screenName = QString())

Drop the preview for screenName, or every preview when the name is empty.

◆ configuredPath()

QString PhosphorShell::WallpaperService::configuredPath ( const QString & screenName = QString()) const
nodiscard

The persisted wallpaper for screenName: its own entry, else the all-screens entry, else empty.

The empty name reads the all-screens entry itself.

◆ effectiveFit()

QString PhosphorShell::WallpaperService::effectiveFit ( const QString & screenName = QString()) const

◆ effectivePath()

QString PhosphorShell::WallpaperService::effectivePath ( const QString & screenName = QString()) const
nodiscard

What a surface on screenName should draw: the preview when one is set, otherwise the configured path.

◆ effectivePathChanged

void PhosphorShell::WallpaperService::effectivePathChanged ( const QString & screenName)
signal

The answer to effectivePath(screenName) may have changed.

An empty name means every screen.

◆ image()

QImage PhosphorShell::WallpaperService::image ( ) const
nodiscard

◆ imageChanged

void PhosphorShell::WallpaperService::imageChanged ( )
signal

◆ isAvailable()

bool PhosphorShell::WallpaperService::isAvailable ( ) const
nodiscard

◆ path()

QString PhosphorShell::WallpaperService::path ( ) const
nodiscard

◆ pathChanged

void PhosphorShell::WallpaperService::pathChanged ( )
signal

◆ previewPath()

QString PhosphorShell::WallpaperService::previewPath ( const QString & screenName = QString()) const
nodiscard

The transient preview for screenName, resolved the same way.

Empty when nothing is being previewed there.

◆ refresh()

void PhosphorShell::WallpaperService::refresh ( )

Re-decode path into image, for a consumer that knows the file changed on disk under the same name.

◆ setAppearance()

void PhosphorShell::WallpaperService::setAppearance ( const QVariantMap & wallpapers)

◆ setPath()

bool PhosphorShell::WallpaperService::setPath ( const QString & path,
const QString & screenName = QString() )

Persist path as the wallpaper for screenName, or for every screen when the name is empty (which also drops the per-screen entries, since "all screens" means all of them).

Returns false, and changes nothing, when path is not a readable image.

◆ setPreview()

bool PhosphorShell::WallpaperService::setPreview ( const QString & path,
const QString & screenName = QString() )

Show path on screenName (every screen when empty) without persisting it.

Returns false when path is not a readable image.

◆ storePath()

QString PhosphorShell::WallpaperService::storePath ( ) const
nodiscard

Where the store lives, as the constructor was given it.


The documentation for this class was generated from the following file: