theme_manager.h

Go to the documentation of this file.

 
#ifndef THEME_MANAGER_H
#define THEME_MANAGER_H
 
#include <QColor>
#include <QFont>
#include <QHash>
#include <QMutex>
#include <QObject>
#include <QPalette>
#include <QString>
 
class SystemThemeDetector;

struct ThemeInfo {
    QString name;           
    QString internalName;   
    int     version = 0;    
    QString description;    
    QString author;         
};
 
struct ThemeSectionInfo {
    bool required;
    QStringList tokens;
};
 
struct ThemeColorPair {
    QColor light;
    QColor dark;
};

class ThemeManager : public QObject {
    Q_OBJECT
public:

    enum class ThemeMode {
        System,
        Dark,
        Light
    };
    Q_ENUM(ThemeMode)
 
    
    enum class PreviewScheme {
        Default,
        PreferLight,
        PreferDark
    };
    Q_ENUM(PreviewScheme)
 
    enum ThemeToken {
        // Brand
        BrandPrimary,
        BrandDeep,
 
        // Accent
        AccentSuccess,
        AccentWarning,
        AccentError,
        AccentInfo,
 
        // Expert
        ExpertComment,
        ExpertChat,
        ExpertNote,
        ExpertWarn,
        ExpertError,
        ExpertForeground,
 
        // Packets — for each state, <Name> is the row background tint and
        // <Name>Text is the foreground.  Hidden is text-only by design (it
        // dims an item that otherwise renders with the normal row bg).
        // When a theme omits a Text token, ThemeTokenHandler derives it
        // from contrastingText(<Name>) or PaletteText as appropriate.
        PacketsSelection,
        PacketsSelectionText,
        PacketsInactive,
        PacketsInactiveText,
        PacketsMarked,
        PacketsMarkedText,
        PacketsIgnored,
        PacketsIgnoredText,
        PacketsHidden,
 
        // Conversation — same fg/bg convention as Packets.
        ConversationClient,
        ConversationClientText,
        ConversationServer,
        ConversationServerText,
 
        // Filter state (single color per state — use as bg tint; pair
        // with QPalette::Text for foreground).  Derived from accent
        // when no explicit theme.filter override is set; the JSONC
        // "filter" section lets a theme pin saturated/historical values
        // that alpha-tinting the accent can't reach.  FilterBusy and
        // FilterBusyText carry the "I'm working" look used while a
        // capture filter compiles off-thread.
        FilterValid,
        FilterInvalid,
        FilterDeprecated,
        FilterBusy,
        FilterBusyText,
 
        // Inline filter-affordance glyph colours (icon fills, not bg tints):
        // the bookmark / clear / apply buttons inside the filter line.  Each
        // derives from the matching accent when a theme omits it (so every
        // theme has them defined), and theme.filter.<name> overrides per-token.
        // Display and capture bookmarks differ on purpose (blue vs green); the
        // match colour marks a filter already saved.
        FilterBookmark,         // display-filter bookmark   (← AccentInfo, blue)
        FilterBookmarkCapture,  // capture-filter bookmark   (← AccentSuccess, green)
        FilterBookmarkMatch,    // current filter is saved   (← AccentWarning, yellow)
        FilterClear,            // clear affordance (active) (← AccentError, red)
        FilterApply,            // apply affordance          (← AccentInfo, blue)
        FilterHistory,          // recent-filters arrow, dimmed at rest (← PaletteMid);
                                // the default theme pins the classic Tango grays
                                // (#555753 / #d3d7cf) via theme.filter.history.
 
        // Syntax highlighting — foreground text colours for code- and
        // data-viewers (JSON, hex, Lua debugger, etc.).  Derived so
        // the variant is darker in light mode and lighter in dark
        // mode, keeping enough contrast against PaletteBase.
        SyntaxKey,
        SyntaxString,
        SyntaxNumber,
 
        // Palette Overrides
        PaletteWindow,
        PaletteBase,
        PaletteText,
        PaletteWindowText,
        PaletteAlternateBase,
        PaletteMid,
        PaletteMidLight,
        // Selection foreground — when omitted, builder picks via
        // contrastingText(brand.primary).  Themes whose brand colour
        // sits on the WCAG luminance threshold (e.g. saturated mid-tone
        // teals/blues where contrastingText flips to black even though
        // white reads better) can pin this explicitly to white.
        PaletteHighlightedText,
#if QT_VERSION >= QT_VERSION_CHECK(6, 6, 0)
        PaletteAccent,
#endif
 
        // Header (derived from brand)
        HeaderGradientStart,
        HeaderGradientEnd,
 
        // Section headers (derived from brand + QPalette)
        SectionHeader,
        SectionHeaderHover,
 
        // Structural form chrome — borders, dividers, muted text.
        // FieldBorder is the WCAG-enforced derivation of palette.mid
        // against palette.base (≥ 3.0:1 ratio), used to frame
        // interactive controls without overshooting like palette.shadow
        // does in light mode.  Separator is a softer mix of base + mid
        // for hairlines between cards / sections; themes can override
        // it via the JSONC "separator" top-level key when the derived
        // value is too pronounced (Stratoshark uses an explicit value
        // matching its midlight).  MutedText is reserved for future
        // use — no consumer in tree today, but kept in the enum so
        // themes can grow into it without a binary-compat break.
        FieldBorder,
        Separator,
        MutedText,
 
        // Text on dark surfaces (derived from brand)
        TextOnDark,
        TextOnDarkMuted,
 
        // Update bar (derived from accent.success)
        UpdateGradientStart,
        UpdateGradientEnd,
        UpdateBorder,
        UpdateText,
        UpdateTextHighlight,
        UpdateLink,
        UpdateLinkHover,
        UpdateLinkPressed,
        UpdateButtonBg,
        UpdateButtonHover,
        UpdateButtonPressed,
        UpdateButtonDisabledBg,
        UpdateButtonDisabledText,
        UpdateDismissHoverBg,
        UpdateDismissPressedBg,
 
        // Accent aliases (derived)
        HighlightColorOrange,
        HighlightColorGreen,
 
        // Foreground colors for solid accent backgrounds — derived via
        // contrastingText() so they pick black or white depending on
        // the accent's WCAG luminance.  Use these when a QSS rule
        // paints text on top of an accent-coloured surface (the
        // "Development Build" badge, the "Download Update" button,
        // etc.) so the text stays readable across themes whose
        // accents fall on different sides of the contrast threshold.
        //
        // NOTE: these are intentionally named `TextOn*` rather than
        // `Accent*Text`.  ThemeManager's section auto-grouping treats
        // any enum name starting with "accent" as a required input in
        // the "accent" JSONC section (theme_manager.cpp section loop),
        // so `Accent*Text` derived tokens would make the parser demand
        // them from every theme file.  Following the existing
        // `TextOnDark` precedent keeps them ungrouped.
        TextOnSuccess,
        TextOnWarning,
        TextOnError,
        TextOnInfo,
 
        // None
        NoRole
    };
    Q_ENUM(ThemeToken)
 
    static ThemeManager* instance();

    static QString defaultThemeName();

    static QString resolveThemeName(const QString &name);

    static void init(const QString &theme = QString());
 
    void cleanup();

    ThemeInfo info() const;

    static QList<ThemeInfo> availableThemes();

    QColor color(ThemeToken role) const;
 
    bool colorIsAvailable(ThemeToken role) const;

    QHash<ThemeToken, QColor> previewTheme(const QString &internalName,
                                           PreviewScheme scheme) const;

    bool validateThemeFile(const QString &filePath) const;

    QString loadStyleSheet(const QString &name) const;

    static QString styleSheet(const QString &name);

    static void setValidationState(QWidget *w, const QString &state);

    static bool isDark();

    bool isDarkMode() const;

    ThemeMode mode() const;

    void setMode(ThemeMode mode);

    QColor graphColor(int idx) const;
 
    QColor graphDefaultColor() const;

    qsizetype graphColorCount() const;
 
signals:
    void themeChanged();
 
protected:
    explicit ThemeManager(QObject *parent = nullptr);
    ~ThemeManager();
 
private:
    static ThemeManager* instance_;
    static QMutex mutex_;
 
    ThemeInfo info_;
 
    // Flattened token -> color value, one map per mode
    QHash<ThemeManager::ThemeToken, ThemeColorPair> themeColors_;
    QList<ThemeColorPair> graphColors_;
 
    QHash<QString, ThemeSectionInfo> sections_;
 
    // mapping caches for role and palette resolution
    QHash<QString, ThemeToken> colorRoleCache_;
    QHash<QString, QPalette::ColorRole> paletteRoleCache_;
 
    // Light/dark selection: user's explicit choice plus the detector
    // that tracks the OS preference when mode == System.  The detector
    // is a private member — external code never sees it.  Lifetime is
    // managed via Qt's parent-child ownership: constructed with `this`
    // as parent, destroyed automatically with the ThemeManager.
    ThemeMode mode_ = ThemeMode::System;
    SystemThemeDetector *detector_ = nullptr;
 
    // Pristine OS palette snapshot used as the baseline when the palette
    // builder constructs a new theme palette.  Captured once at ctor
    // entry (before any setPalette() call could pollute QApplication's
    // live palette), and refreshed from `qApp->style()->standardPalette()`
    // whenever the effective light/dark scheme changes (mode flip or OS
    // notification).  Using this snapshot instead of
    // QApplication::palette() prevents the previous theme's palette
    // overrides from leaking into the next theme's baseline — without it,
    // switching from a theme with palette overrides (e.g. "inverted") to
    // one without (e.g. "default") would leave the prior overrides
    // visible.  Only consulted on platforms where the OS palette is
    // trusted (macOS, Windows Qt ≥ 6.8); ignored elsewhere.
    QPalette osBaseline_;

    QPalette baselineForBuild() const;

    void reapplyForSchemeChange();

    static ThemeMode modeFromPrefs(int gui_color_scheme);

    void applyToStyleHints();

    void applyApplicationStyleSheet();

    bool loadTheme(const QString &themeName = QString());
 
};
 
#endif /* THEME_MANAGER_H */