Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
IThemeService.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 <QColor>
8#include <QObject>
9#include <QString>
10#include <QVariantMap>
11
12namespace PhosphorTheme {
13
14// The set of token names a service must publish. Snake_case mirrors the
15// canonical Phosphor palette (published at
16// https://phosphor-works.org/palette/) and matugen's JSON output,
17// so token strings round-trip without alias translation.
18//
19// This is the contract, shells, examples, and tests reference token names
20// from here, not raw strings. New tokens go here first; QML / matugen
21// templates / tests catch up afterwards.
22struct PHOSPHORTHEME_EXPORT TokenNames
23{
24 // Surfaces (M3 surface ramp).
25 static constexpr auto Background = "background";
26 static constexpr auto Surface = "surface";
27 static constexpr auto SurfaceContainer = "surface_container";
28 static constexpr auto SurfaceContainerHigh = "surface_container_high";
29 static constexpr auto SurfaceVariant = "surface_variant";
30 static constexpr auto OnSurface = "on_surface";
31 static constexpr auto OnSurfaceVariant = "on_surface_variant";
32
33 // Accents (M3 primary / secondary / tertiary).
34 static constexpr auto Primary = "primary";
35 static constexpr auto OnPrimary = "on_primary";
36 static constexpr auto PrimaryContainer = "primary_container";
37 static constexpr auto OnPrimaryContainer = "on_primary_container";
38 static constexpr auto Secondary = "secondary";
39 static constexpr auto OnSecondary = "on_secondary";
40 static constexpr auto SecondaryContainer = "secondary_container";
41 static constexpr auto Tertiary = "tertiary";
42 static constexpr auto OnTertiary = "on_tertiary";
43 static constexpr auto TertiaryContainer = "tertiary_container";
44
45 // Error.
46 static constexpr auto Error = "error";
47 static constexpr auto OnError = "on_error";
48 static constexpr auto ErrorContainer = "error_container";
49
50 // Outline.
51 static constexpr auto Outline = "outline";
52 static constexpr auto OutlineVariant = "outline_variant";
53
54 // Status (drawn from the ANSI 16 ramp).
55 static constexpr auto Success = "success";
56 static constexpr auto SuccessBright = "success_bright";
57 static constexpr auto Warning = "warning";
58 static constexpr auto WarningBright = "warning_bright";
59 static constexpr auto ErrorBright = "error_bright";
60 static constexpr auto Info = "info";
61 static constexpr auto InfoBright = "info_bright";
62
63 // Brand-gradient stops, drive the connected-corner / accent gradients
64 // throughout the shell. These are not Material 3 standard tokens; they
65 // come from the [extensions.brand] block of the canonical Phosphor
66 // palette (https://phosphor-works.org/palette/).
67 static constexpr auto BrandStop0 = "brand_stop_0";
68 static constexpr auto BrandStop1 = "brand_stop_1";
69 static constexpr auto BrandStop2 = "brand_stop_2";
70 static constexpr auto BrandStop3 = "brand_stop_3";
71};
72
73// Service contract for the active theme palette.
74//
75// A shell instantiates exactly one IThemeService (the default concrete
76// implementation is `PaletteStore`) and exposes it to QML. Alternate
77// implementations (test mocks, remote-driven services) plug in by
78// satisfying this interface and registering the instance with the QML
79// engine before `Phosphor.Theme` is imported.
80//
81// The interface stays pure-virtual to keep tests cheap: no QObject base,
82// no signal/slot machinery exposed at the abstract layer. Concrete
83// implementations bring their own QObject if they need notifications.
84class PHOSPHORTHEME_EXPORT IThemeService
85{
86public:
87 virtual ~IThemeService() = default;
88
89 // Read the full token map (`token name` → QColor) for the active
90 // palette. Stable order is not promised; callers iterate by key.
91 [[nodiscard]] virtual QVariantMap palette() const = 0;
92
93 // Look up a single token by name (one of TokenNames::*). Returns an
94 // invalid color if the token isn't in the active palette, caller's
95 // problem to handle, since "token missing" is a programming error.
96 [[nodiscard]] virtual QColor token(const QString& name) const = 0;
97
98 // Load a palette from a JSON byte array. Tokens missing from the JSON
99 // are left at their current value (does NOT reset to default). Returns
100 // true on parse success; false leaves the active palette untouched.
101 virtual bool loadFromJson(const QByteArray& json) = 0;
102
103 // Apply a parsed token map directly. Same merge semantics as
104 // loadFromJson but skips the JSON round-trip, used by MatugenRunner
105 // and any other in-process source that already has QColor values.
106 // Empty maps are a no-op.
107 virtual void applyTokens(const QVariantMap& tokens) = 0;
108
109 // Load a palette from a JSON file path. Sets up a filesystem watch on
110 // the path so subsequent on-disk edits hot-reload the palette. Returns
111 // true on read+parse success.
112 virtual bool loadFromFile(const QString& path) = 0;
113
114 // Reset the palette to the built-in canonical defaults (Phosphor dark).
115 // Stops any active filesystem watch.
116 virtual void resetToDefaults() = 0;
117};
118
119} // namespace PhosphorTheme
Definition IThemeService.h:85
virtual void resetToDefaults()=0
virtual bool loadFromFile(const QString &path)=0
virtual ~IThemeService()=default
virtual QColor token(const QString &name) const =0
virtual QVariantMap palette() const =0
virtual void applyTokens(const QVariantMap &tokens)=0
virtual bool loadFromJson(const QByteArray &json)=0
Definition AppearanceLibrary.h:10
Definition IThemeService.h:23
static constexpr auto OnSecondary
Definition IThemeService.h:39
static constexpr auto OutlineVariant
Definition IThemeService.h:52
static constexpr auto Outline
Definition IThemeService.h:51
static constexpr auto TertiaryContainer
Definition IThemeService.h:43
static constexpr auto SurfaceContainerHigh
Definition IThemeService.h:28
static constexpr auto SurfaceContainer
Definition IThemeService.h:27
static constexpr auto BrandStop3
Definition IThemeService.h:70
static constexpr auto OnError
Definition IThemeService.h:47
static constexpr auto BrandStop0
Definition IThemeService.h:67
static constexpr auto SurfaceVariant
Definition IThemeService.h:29
static constexpr auto Secondary
Definition IThemeService.h:38
static constexpr auto Primary
Definition IThemeService.h:34
static constexpr auto Surface
Definition IThemeService.h:26
static constexpr auto BrandStop1
Definition IThemeService.h:68
static constexpr auto ErrorContainer
Definition IThemeService.h:48
static constexpr auto OnSurface
Definition IThemeService.h:30
static constexpr auto PrimaryContainer
Definition IThemeService.h:36
static constexpr auto InfoBright
Definition IThemeService.h:61
static constexpr auto Error
Definition IThemeService.h:46
static constexpr auto Tertiary
Definition IThemeService.h:41
static constexpr auto OnPrimaryContainer
Definition IThemeService.h:37
static constexpr auto ErrorBright
Definition IThemeService.h:59
static constexpr auto Warning
Definition IThemeService.h:57
static constexpr auto OnTertiary
Definition IThemeService.h:42
static constexpr auto BrandStop2
Definition IThemeService.h:69
static constexpr auto Info
Definition IThemeService.h:60
static constexpr auto OnPrimary
Definition IThemeService.h:35
static constexpr auto Background
Definition IThemeService.h:25
static constexpr auto SecondaryContainer
Definition IThemeService.h:40
static constexpr auto SuccessBright
Definition IThemeService.h:56
static constexpr auto WarningBright
Definition IThemeService.h:58
static constexpr auto Success
Definition IThemeService.h:55
static constexpr auto OnSurfaceVariant
Definition IThemeService.h:31