color_math.h

Go to the documentation of this file.

 
#ifndef COLOR_MATH_H
#define COLOR_MATH_H
 
#include <ui/qt/utils/theme_manager.h>
 
#include <QColor>

class ColorMath
{
public:
    // ---------------------------------------------------------------
    // Luminance & contrast
    // ---------------------------------------------------------------

    static double relativeLuminance(const QColor &color);

    static qreal contrastRatio(const QColor &color1, const QColor &color2);

    static QColor ensureContrast(const QColor &c, const QColor &bg, qreal minRatio);

    static bool isDark(const QColor &color);

    struct ContrastRatios {
        ThemeContrast level;    
        qreal readableText;
        qreal largeText;
        qreal nonText;
        qreal divider;
        qreal distinctSurface;
        qreal cardSurfaceDark;
        qreal icon;
    };

    static constexpr ContrastRatios ratiosFor(ThemeContrast level)
    {
        const bool high = level == ThemeContrast::High;
        ContrastRatios r {};
        r.level           = level;
        r.readableText    = high ? ReadableTextRatioHigh    : ReadableTextRatio;
        r.largeText       = high ? LargeTextRatioHigh       : LargeTextRatio;
        r.nonText         = high ? NonTextRatioHigh         : NonTextRatio;
        r.divider         = high ? DividerRatioHigh         : DividerRatio;
        r.distinctSurface = high ? DistinctSurfaceRatioHigh : DistinctSurfaceRatio;
        r.cardSurfaceDark = high ? CardSurfaceRatioDarkHigh : CardSurfaceRatioDark;
        r.icon            = high ? IconContrastRatioHigh    : IconContrastRatio;
        return r;
    }

    static const ContrastRatios &activeRatios();

    static void setActiveContrast(ThemeContrast level);

    struct TextOnFill {
        QColor text;
        QColor fill;
    };

    static TextOnFill readableOnFill(const QColor &text, const QColor &fill, qreal minRatio);

    static QColor readableFill(const QColor &fill, const ContrastRatios &ratios = activeRatios());

    static TextOnFill selectionHover(const QColor &base, const QColor &selection,
                                     const QColor &text,
                                     const ContrastRatios &ratios = activeRatios());

    static QColor selectionHoverFill(const QColor &base, const QColor &selection,
                                     const ContrastRatios &ratios = activeRatios());

    static QColor readableText(const QColor &text, const QColor &surface,
                               const ContrastRatios &ratios = activeRatios());

    static bool isReadable(const QColor &text, const QColor &surface,
                           const ContrastRatios &ratios = activeRatios());
 
    // ---------------------------------------------------------------
    // Mix / shade
    // ---------------------------------------------------------------

    static QColor         mix(const QColor &a, const QColor &b, qreal ratio = 0.5);
    static ThemeColorPair mix(const ThemeColorPair &a, const ThemeColorPair &b, qreal ratio = 0.5);

    static QColor         darken(const QColor &c, int percent);
    static ThemeColorPair darken(const ThemeColorPair &p, int percent);

    static QColor         lighten(const QColor &c, int percent);
    static ThemeColorPair lighten(const ThemeColorPair &p, int percent);
 
    // ---------------------------------------------------------------
    // Alpha
    // ---------------------------------------------------------------

    static QColor         withAlpha(const QColor &c, int alpha);
    static ThemeColorPair withAlpha(const ThemeColorPair &p, int alpha);

    static QColor         withAlphaF(const QColor &c, qreal alpha);
    static ThemeColorPair withAlphaF(const ThemeColorPair &p, qreal alpha);
 
    // ---------------------------------------------------------------
    // Contrast & state
    // ---------------------------------------------------------------

    static QColor         contrastingText(const QColor &surface);
    static ThemeColorPair contrastingText(const ThemeColorPair &pair);

    static QColor         compositeOver(const QColor &surface, const QColor &backdrop);

    static QColor         contrastingTextOver(const QColor &surface, const QColor &backdrop);

    static QColor         disabled(const QColor &c, const QColor &background);
    static ThemeColorPair disabled(const ThemeColorPair &p, const QColor &background);

    static QColor         hoverBg(const QColor &c, const QColor &background);
    static ThemeColorPair hoverBg(const ThemeColorPair &p, const QColor &background);

    static QColor         hoverEmphasis(const QColor &c);
 
private:
    // The ratio values behind ratiosFor().  Private so that every
    // consumer goes through a ContrastRatios set and follows the
    // active contrast level.  The ...High siblings are the high
    // contrast targets: WCAG AAA for text (7:1 body, 4.5:1 large
    // text) and stronger non-text, divider and surface distances.
    static constexpr qreal DistinctSurfaceRatio = 1.5;
    static constexpr qreal DistinctSurfaceRatioHigh = 3.0;
    static constexpr qreal ReadableTextRatio = 4.5;
    static constexpr qreal ReadableTextRatioHigh = 7.0;
    static constexpr qreal CardSurfaceRatioDark = 1.25;
    static constexpr qreal CardSurfaceRatioDarkHigh = 1.6;
    static constexpr qreal DividerRatio = 1.6;
    static constexpr qreal DividerRatioHigh = 3.0;
    static constexpr qreal NonTextRatio = 3.0;
    static constexpr qreal NonTextRatioHigh = 4.5;
    static constexpr qreal LargeTextRatio = 3.0;
    static constexpr qreal LargeTextRatioHigh = 4.5;
    static constexpr qreal IconContrastRatio = 1.6;
    static constexpr qreal IconContrastRatioHigh = 4.5;
 
    // Percentage passed to QColor::lighter() by hoverEmphasis().
    // lighter() multiplies the HSV value by factor / 100, so 115 makes a
    // glyph about 15% brighter and keeps its hue; a colour already at full
    // value loses saturation instead and moves toward white.  The step is
    // small on purpose: hover should read as the same glyph lighting up,
    // not as a different colour (a 30% mix toward the text colour was
    // rejected as too dark).  Legibility is not this factor's job: the
    // contrast-adapting icon engine runs the result through
    // ensureContrast() against the field afterwards.  An int, not a
    // qreal, because lighter() takes an integer percentage; the qreal
    // constants above are contrast ratios only.
    static constexpr int HoverEmphasisFactor = 115;
};
 
#endif /* COLOR_MATH_H */