Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
MatugenRunner.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: 2026 fuddlesworth
2// SPDX-License-Identifier: LGPL-2.1-or-later
3#pragma once
4
5#include <PhosphorTheme/phosphortheme_export.h>
6
7#include <QObject>
8#include <QString>
9#include <QUrl>
10#include <QVariantMap>
11#include <QtQmlIntegration/qqmlintegration.h>
12
13#include <memory>
14
15class QProcess;
16
17namespace PhosphorTheme {
18
19// Spawns the external `matugen` binary on a wallpaper path, captures its
20// JSON output, parses it into a `token name -> QColor` map, and emits
21// `paletteReady` for the caller (typically a PaletteStore) to apply.
22//
23// MatugenRunner deliberately does NOT couple to PaletteStore directly:
24// the runner emits the parsed map, and the caller decides whether to
25// merge into the live palette, persist it to disk, or both. This keeps
26// the matugen integration testable without spinning up a full theme
27// service, and lets the CLI (which only wants the map) reuse the runner
28// without dragging in QML.
29//
30// Failure cases:
31// - matugen not on PATH → `failed` with reason
32// - wallpaper path missing → `failed`
33// - matugen exits non-zero → `failed` with stderr tail
34// - JSON unparseable / unexpected schema → `failed` with reason
35//
36// All failure paths leave any concurrent run state cleaned up.
37class PHOSPHORTHEME_EXPORT MatugenRunner : public QObject
38{
39 Q_OBJECT
40 QML_ELEMENT
41
42 // matugen invocation: `matugenBinary` is resolved on PATH unless an
43 // absolute path is given. Defaults to "matugen".
44 Q_PROPERTY(QString matugenBinary READ matugenBinary WRITE setMatugenBinary NOTIFY matugenBinaryChanged)
45
46 // Dark / light variant selection, matugen emits both; we pick the
47 // requested one before exposing. Default: "dark".
48 Q_PROPERTY(QString mode READ mode WRITE setMode NOTIFY modeChanged)
49
50 // Candidate-color preference. Matugen needs this flag whenever an
51 // image yields multiple source colors and matugen runs
52 // non-interactively. We invoke it as a subprocess with no TTY, so
53 // this is always our case. Default is "saturation", which picks the
54 // most saturated candidate and matches user expectations for a
55 // vibrant wallpaper-derived palette. Valid matugen values are
56 // "darkness", "lightness", "saturation", "less-saturation", "value",
57 // and "closest-to-fallback".
58 Q_PROPERTY(QString prefer READ prefer WRITE setPrefer NOTIFY preferChanged)
59
60 // True while a `run()` call is in flight. Bind UI busy indicators here.
61 Q_PROPERTY(bool running READ isRunning NOTIFY runningChanged)
62
63public:
64 explicit MatugenRunner(QObject* parent = nullptr);
65 ~MatugenRunner() override;
66
67 [[nodiscard]] QString matugenBinary() const;
68 void setMatugenBinary(const QString& binary);
69
70 [[nodiscard]] QString mode() const;
71 void setMode(const QString& mode);
72
73 [[nodiscard]] QString prefer() const;
74 void setPrefer(const QString& prefer);
75
76 [[nodiscard]] bool isRunning() const;
77
78 // Spawn matugen on `wallpaperPath`. Emits `paletteReady` on success,
79 // `failed` on any error path. A second `run` while one is already in
80 // flight cancels the previous run before starting.
81 Q_INVOKABLE void run(const QString& wallpaperPath);
82
83 // QUrl overload for QML callers (e.g. FileDialog.selectedFile is a
84 // url, not a string). Converts via QUrl::toLocalFile so every legal
85 // file URL form resolves correctly. Non-file URLs are rejected via
86 // the `failed` signal so a passing-but-wrong call surfaces visibly
87 // instead of spawning matugen with a malformed argument.
88 Q_INVOKABLE void run(const QUrl& wallpaperUrl);
89
90 // Cancel an in-flight run. Safe to call when nothing is running.
91 Q_INVOKABLE void cancel();
92
93 // Parse a matugen JSON byte array directly, no subprocess. Exposed
94 // for tests and for shells that drive matugen via a different
95 // mechanism (e.g. an existing CLI pipeline). Returns the token map;
96 // empty on parse failure (no signal fires).
97 [[nodiscard]] QVariantMap parseMatugenJson(const QByteArray& json, const QString& mode) const;
98
99Q_SIGNALS:
104
105 // The matugen invocation completed and yielded a non-empty token map.
106 // The map has Phosphor-canonical snake_case keys; any matugen names
107 // that don't round-trip have already been remapped.
108 void paletteReady(const QVariantMap& tokens, const QString& wallpaperPath);
109
110 // Anything that prevented `paletteReady` from firing, missing
111 // binary, non-zero exit, parse error. `reason` is human-readable.
112 void failed(const QString& wallpaperPath, const QString& reason);
113
114private:
115 void teardownProcess();
116 void cancelInflight();
117 void disposeProcess();
118 void emitRunningChangedIfTransitioned();
119
120 QString m_matugenBinary;
121 QString m_mode;
122 QString m_prefer;
123 QString m_pendingWallpaper;
124 std::unique_ptr<QProcess> m_process;
125 // Last value we actually emitted via runningChanged. The signal
126 // contract is "edge-triggered on real transitions". Sampling
127 // isRunning() at emit time isn't enough because Qt flips
128 // QProcess::state() to NotRunning BEFORE delivering errorOccurred,
129 // so a lambda observing isRunning() can miss the transition it's
130 // supposed to report. Tracking what we already told consumers
131 // pins the contract regardless of Qt's internal ordering.
132 bool m_lastEmittedRunning = false;
133};
134
135} // namespace PhosphorTheme
void setMatugenBinary(const QString &binary)
void failed(const QString &wallpaperPath, const QString &reason)
QVariantMap parseMatugenJson(const QByteArray &json, const QString &mode) const
void run(const QString &wallpaperPath)
QString matugenBinary() const
void run(const QUrl &wallpaperUrl)
MatugenRunner(QObject *parent=nullptr)
void paletteReady(const QVariantMap &tokens, const QString &wallpaperPath)
void setPrefer(const QString &prefer)
void setMode(const QString &mode)
Definition AppearanceLibrary.h:10