theme_manager.h

Go to the documentation of this file.

 
#pragma once
 
#include <QColor>
#include <QFont>
#include <QHash>
#include <QMutex>
#include <QObject>
#include <QPalette>
#include <QList>
#include <QString>
#include <QStringList>
 
class SystemThemeDetector;
struct ThemeDraft;

enum class ThemeContrast { Standard, High };

struct ThemeInfo {
    QString name;           
    QString internalName;   
    int     version = 0;    
    QString description;    
    QString author;         
    ThemeContrast contrast = ThemeContrast::Standard; 
    bool    builtIn = false;
    QString filePath;       
};
 
struct ThemeSectionInfo {
    bool required;
    QStringList tokens;
};
 
struct ThemeColorPair {
    QColor light;
    QColor dark;

    QColor forMode(bool isDarkMode) const { return isDarkMode ? dark : light; }
    void setForMode(bool isDarkMode, const QColor &color) { (isDarkMode ? dark : light) = color; }

    static bool sameColor(const QColor &a, const QColor &b) {
        return a.isValid() == b.isValid() && (!a.isValid() || a.rgba() == b.rgba());
    }

    bool isValid() const { return light.isValid() && dark.isValid(); }
    bool operator==(const ThemeColorPair &other) const {
        return sameColor(light, other.light) && sameColor(dark, other.dark);
    }
    bool operator!=(const ThemeColorPair &other) const { return !(*this == other); }
};

struct ThemeFontHint {
    QString family;         
    int     pointSize = 0;  

    bool isSet() const { return !family.isEmpty() || pointSize > 0; }
    bool operator==(const ThemeFontHint &other) const {
        return family == other.family && pointSize == other.pointSize;
    }
    bool operator!=(const ThemeFontHint &other) const { return !(*this == other); }
};

struct ThemeParseReport {
    QStringList messages;
    int invalidValues = 0;
    int unknownTopLevelKeys = 0;
};

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,
 
        // Accent
        AccentSuccess,
        AccentWarning,
        AccentError,
        AccentInfo,
 
        // Expert
        ExpertNone,
        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.
        FilterBookmarkDisplay,  // 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 fixed grays
                                // via theme.filter.history.
 
        // Code editor (Lua Debugger script editor) — surface, gutter and
        // paused-line colours, then the syntax highlighting foreground
        // colours.  Every key is optional; an omitted one uses the
        // editor's built-in light / dark default.
        CodeBackground,
        CodeText,
        CodeSelection,
        CodeSelectionText,
        CodeGutter,
        CodeGutterText,
        CodePausedLine,
        CodeString,
        CodeKeyword,
        CodeNumber,
        CodeBuiltIn,
        CodeFunctionCall,
        CodeComment,
 
        // Syntax highlighting — foreground text colours for code- and
        // data-viewers (JSON, hex, 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 background — when omitted, the builder uses
        // packets.selection, else brand.primary.
        PaletteHighlight,
        // Selection foreground — when omitted, the builder picks
        // contrastingText() of the resolved highlight.  Themes whose
        // selection 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
 
        // Welcome header bar (derived from the palette's Highlight)
        HeaderBackground,
 
        // Section headers (derived from brand + QPalette)
        SectionHeader,
        SectionHeaderHover,
 
        // Structural form chrome — borders, dividers, muted text.
        // ControlBorder is the WCAG-enforced derivation of palette.mid
        // against palette.base (the non-text ratio of the active
        // contrast set), used to frame interactive controls without
        // overshooting like palette.shadow does in light mode.
        // MutedText is a derived de-emphasized text color
        // (palette text mixed toward base, contrast-adapted to base)
        // for secondary labels and plot reference lines.
        ControlBorder,
        MutedText,
 
        // Theme border section, every key optional.
        // BorderField frames text fields; when the theme does not set
        // it, it is ControlBorder.
        // BorderSeparator is a softer mix of base + mid, kept the divider
        // ratio of the active contrast set apart from base, for
        // hairlines between sections; themes set it when the derived
        // value is too pronounced (Stratoshark uses an explicit value
        // matching its midlight).
        BorderField,
        BorderSeparator,
 
        // Raised surfaces ("cards") on Base and the colors drawn on
        // them.  In dark mode CardBackground is kept the dark card
        // surface ratio of the active contrast set apart from Base,
        // starting from the theme's palette.alternateBase pin or Base;
        // in light mode it is that color unchanged.
        // CardBorder frames it and is used for lines on it.
        // CardSectionHeader* and CardFocusRing are the section header
        // and focus colors re-derived to read on the card.  CardLink is
        // the application Link in light mode (lifted only when it does
        // not read on the card), lifted further in dark mode so that it
        // reads on CardLinkHover at body-text contrast.  CardLinkHover
        // is the item hover fill with the card as base, moved toward
        // the card until CardLink reads on it (large-text contrast in
        // light mode).  OverlayCard* is the card surface for overlays
        // over a black scrim, such as the startup splash: the lighter of
        // Base and CardBackground, with its own border.
        CardBackground,
        CardBorder,
        CardSectionHeader,
        CardSectionHeaderHover,
        CardLink,
        CardLinkHover,
        CardFocusRing,
        OverlayCardBackground,
        OverlayCardBorder,
 
        // Welcome header title and version text (derived with HeaderBackground)
        HeaderText,
        HeaderTextMuted,
 
        // Update bar (derived from accent.success).  UpdateDot: the
        // status dot, accent.success, kept non-text contrast apart
        // from the bar in high contrast.
        UpdateBackground,
        UpdateBorder,
        UpdateText,
        UpdateTextHighlight,
        UpdateLink,
        UpdateLinkHover,
        UpdateLinkPressed,
        UpdateButtonBg,
        UpdateButtonHover,
        UpdateButtonPressed,
        UpdateButtonDisabledBg,
        UpdateButtonDisabledText,
        UpdateDismissHoverBg,
        UpdateDismissPressedBg,
        UpdateDot,
 
        // 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.  The `TextOn*` prefix keeps
        // them out of the accent section.
        TextOnSuccess,
        TextOnWarning,
        TextOnError,
        TextOnInfo,
 
        // Foreground on the filter validity tints, derived as the
        // contrastingText() of the matching Filter* token.  Named
        // `TextOn*` for the same section-grouping reason as above.
        TextOnFilterValid,
        TextOnFilterInvalid,
        TextOnFilterDeprecated,
 
        // Line tints of a text diff (added, changed, removed lines) and notice
        // banners (background and frame): palette.base tinted toward an
        // accent, stronger in dark mode.  Derived only, not settable.
        DiffAdded,
        DiffChanged,
        DiffRemoved,
        NoticeInfo,
        NoticeInfoBorder,
        NoticeError,
        NoticeErrorBorder,
 
        // None
        NoRole
    };
    Q_ENUM(ThemeToken)
 
    
    static ThemeToken tokenFromName(const QString &name);
 
    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();

    static bool isBuiltInTheme(const QString &internalName);

    static QString personalThemesDir();

    static QString personalThemePath(const QString &stem);

    static QString selectedThemeName();

    static void setSelectedThemeName(const QString &name);

    bool loadDraft(const QString &internalName, ThemeDraft &out,
                   QString *errorString = nullptr,
                   ThemeParseReport *report = nullptr) const;

    bool parseDraft(const QByteArray &jsonc, const QString &internalName,
                    ThemeDraft &out, QString *errorString = nullptr,
                    ThemeParseReport *report = nullptr) const;

    QHash<ThemeToken, ThemeColorPair> resolveDraftTokens(const ThemeDraft &draft,
                                                         bool dark,
                                                         QPalette *palette = nullptr,
                                                         QHash<ThemeToken, const char *> *sources = nullptr,
                                                         int gui_contrast = UseRecentContrast) const;

    ThemeToken paletteRoleToken(QPalette::ColorRole role) const;

    ThemeToken tokenForName(const QString &name) const;

    static QHash<ThemeToken, QColor> flattenTokens(const QHash<ThemeToken, ThemeColorPair> &tokens,
                                                   bool dark);

    const QList<ThemeToken> &requiredTokens() const { return requiredTokens_; }

    struct SettableKey {
        ThemeToken token;
        QString    section; 
        QString    key;     
    };

    const QList<SettableKey> &settableKeys() const { return settableKeys_; }

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

    QHash<ThemeToken, QColor> previewTheme(const QString &internalName,
                                           PreviewScheme scheme,
                                           int gui_contrast = UseRecentContrast,
                                           bool *declaresWindow = nullptr) 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 void setNoticeState(QWidget *w, const QString &state);

    static bool isDark();

    bool isDarkMode() const;

    ThemeMode mode() const;

    void setMode(ThemeMode mode);

    ThemeContrast contrast() const;

    static bool canDetectSystemContrast();

    static bool systemPrefersHighContrast();

    static ThemeContrast effectiveContrast(int gui_contrast, ThemeContrast declared);

    static constexpr int UseRecentContrast = -1;

    QColor graphColor(int idx) 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_;
    QHash<ThemeManager::ThemeToken, ThemeColorPair> parsedColors_;
    QList<ThemeColorPair> graphColors_;
 
    QHash<QString, ThemeSectionInfo> sections_;
    QList<ThemeToken> requiredTokens_;
    QList<SettableKey> settableKeys_;
 
    // 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;
 
    // Contrast level of the last apply; compared against a fresh
    // effectiveContrast() when the OS contrast preference changes.
    ThemeContrast contrast_ = ThemeContrast::Standard;
 
    // 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 whenever the effective light/dark
    // scheme changes (mode flip or OS notification): on macOS by dropping
    // the application palette and reading back the platform palette Qt
    // resolves, on Windows (Qt ≥ 6.8) from
    // `qApp->style()->standardPalette()`.  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();

    void applyTheme();

    static ThemeMode modeFromPrefs(int gui_color_scheme);

    void applyToStyleHints();

    void applyApplicationStyleSheet();

    bool loadTheme(const QString &themeName = QString());
 
};

struct ThemeDraft {
    ThemeInfo info;                                            
    QHash<ThemeManager::ThemeToken, ThemeColorPair> colors;    
    QList<ThemeColorPair> graphColors;                         
    ThemeFontHint regularFont;                                 
    ThemeFontHint monospaceFont;                               

    static const QList<ThemeManager::ThemeToken> &requiredTokens();

    ThemeManager::ThemeToken firstMissingRequired() const;

    bool hasRequiredColors() const;

    bool declaresWindow() const;

    bool sameColors(const ThemeDraft &other) const;

    int removeInvalidEntries();

    bool operator==(const ThemeDraft &other) const;
    bool operator!=(const ThemeDraft &other) const { return !(*this == other); }
};