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

The wallpaper candidates the picker strip scrolls through. More...

#include <PhosphorShellPicker/WallpaperCandidates.h>

Inheritance diagram for PhosphorShellPicker::WallpaperCandidates:
[legend]

Signals

void directoriesChanged ()
void currentPathChanged ()
void candidatesChanged ()

Public Member Functions

 WallpaperCandidates (QObject *parent=nullptr)
 Directories to scan, in order. Defaults to defaultDirectories().
 ~WallpaperCandidates () override
QStringList directories () const
void setDirectories (const QStringList &directories)
QString currentPath () const
void setCurrentPath (const QString &path)
QVariantList candidates () const
int count () const
void rescan ()
 Re-run the scan against directories and currentPath.

Static Public Member Functions

static QStringList defaultDirectories ()
 The user's wallpaper directory followed by the system ones, every existing wallpapers directory on the XDG data path.
static QList< Candidate > scanDirectory (const QString &directory)
 Scan one directory: its image files and its Plasma packages, sorted by name within each shape (files first).
static QString packageImage (const QString &packageDir)
 The image a Plasma wallpaper package offers: the largest under contents/images/ by the WxH in its name, or empty when the directory is not a package.
static QString packageName (const QString &packageDir)
 A package's display name from its metadata, or the directory name.
static bool isImageFile (const QString &fileName)
 Whether a file name carries a raster image suffix the picker offers.
static bool isUsableImage (const QFileInfo &entry)
 Whether a scanned entry is a REGULAR file the picker can offer.

Static Public Attributes

static constexpr int MaxCandidatesPerDirectory = 2000
 Most candidates taken from any one directory.

Detailed Description

The wallpaper candidates the picker strip scrolls through.

Scans the user's wallpaper directories (~/.local/share/wallpapers and every wallpapers directory under $XDG_DATA_DIRS, so the Plasma packages in /usr/share/wallpapers are included) for two shapes:

  • plain image files directly in a directory, and
  • Plasma wallpaper packages, a directory with contents/images/, for which the largest image by the WxH in its file name is the candidate and the package's metadata.json (or metadata.desktop) supplies the name.

The current wallpaper, when set, leads the list; every other candidate follows in directory order, then name order, with duplicates (the same file reached through two paths) dropped. The scan is synchronous and on the GUI thread: it lists directories, it does not decode images. The strip's thumbnails decode asynchronously through Image.

Constructor & Destructor Documentation

◆ WallpaperCandidates()

PhosphorShellPicker::WallpaperCandidates::WallpaperCandidates ( QObject * parent = nullptr)
explicit

Directories to scan, in order. Defaults to defaultDirectories().

The wallpaper in use, listed first. Empty when unknown. The scanned list as { path, name, source } maps, for a ListView.

◆ ~WallpaperCandidates()

PhosphorShellPicker::WallpaperCandidates::~WallpaperCandidates ( )
override

Member Function Documentation

◆ candidates()

QVariantList PhosphorShellPicker::WallpaperCandidates::candidates ( ) const
nodiscard

◆ candidatesChanged

void PhosphorShellPicker::WallpaperCandidates::candidatesChanged ( )
signal

◆ count()

int PhosphorShellPicker::WallpaperCandidates::count ( ) const
nodiscard

◆ currentPath()

QString PhosphorShellPicker::WallpaperCandidates::currentPath ( ) const
nodiscard

◆ currentPathChanged

void PhosphorShellPicker::WallpaperCandidates::currentPathChanged ( )
signal

◆ defaultDirectories()

QStringList PhosphorShellPicker::WallpaperCandidates::defaultDirectories ( )
staticnodiscard

The user's wallpaper directory followed by the system ones, every existing wallpapers directory on the XDG data path.

◆ directories()

QStringList PhosphorShellPicker::WallpaperCandidates::directories ( ) const
nodiscard

◆ directoriesChanged

void PhosphorShellPicker::WallpaperCandidates::directoriesChanged ( )
signal

◆ isImageFile()

bool PhosphorShellPicker::WallpaperCandidates::isImageFile ( const QString & fileName)
staticnodiscard

Whether a file name carries a raster image suffix the picker offers.

◆ isUsableImage()

bool PhosphorShellPicker::WallpaperCandidates::isUsableImage ( const QFileInfo & entry)
staticnodiscard

Whether a scanned entry is a REGULAR file the picker can offer.

QDir::Files admits fifos, sockets and device nodes, and a fifo with an image suffix would block the QML Image decode that opens it.

◆ packageImage()

QString PhosphorShellPicker::WallpaperCandidates::packageImage ( const QString & packageDir)
staticnodiscard

The image a Plasma wallpaper package offers: the largest under contents/images/ by the WxH in its name, or empty when the directory is not a package.

◆ packageName()

QString PhosphorShellPicker::WallpaperCandidates::packageName ( const QString & packageDir)
staticnodiscard

A package's display name from its metadata, or the directory name.

◆ rescan()

void PhosphorShellPicker::WallpaperCandidates::rescan ( )

Re-run the scan against directories and currentPath.

Emits candidatesChanged only when the list differs from the last scan.

◆ scanDirectory()

QList< Candidate > PhosphorShellPicker::WallpaperCandidates::scanDirectory ( const QString & directory)
staticnodiscard

Scan one directory: its image files and its Plasma packages, sorted by name within each shape (files first).

Pure, for the tests.

◆ setCurrentPath()

void PhosphorShellPicker::WallpaperCandidates::setCurrentPath ( const QString & path)

◆ setDirectories()

void PhosphorShellPicker::WallpaperCandidates::setDirectories ( const QStringList & directories)

Member Data Documentation

◆ MaxCandidatesPerDirectory

int PhosphorShellPicker::WallpaperCandidates::MaxCandidatesPerDirectory = 2000
staticconstexpr

Most candidates taken from any one directory.

The scan is synchronous and on the GUI thread, and each candidate becomes a QVariantMap the strip reads, so a large picture folder configured as a wallpaper root would otherwise stall the shell every time the picker opens.


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