helper.cpp

// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
// SPDX-License-Identifier: BSD-2-Clause OR MIT
 
// Own header
#include "helper.h"
 
#include "absolutecolor.h"
#include "genericcolor.h"
#include "helperconversion.h"
#include "initializelibraryresources.h"
#include "rgbcolorspace.h"
#include <array>
#include <qchar.h>
#include <qcolor.h>
#include <qevent.h>
#include <qkeysequence.h>
#include <qpainter.h>
#include <qpixmap.h>
#include <qpoint.h>
#include <qsize.h>
#include <qstringliteral.h>
#include <qstyle.h>
#include <qstyleoption.h>
#include <qwidget.h>
 
#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
#include <qlist.h>
#else
#include <qstringlist.h>
#endif
 
#ifndef PERCEPTUALCOLORINTERNAL
#include <type_traits>
#include <utility>
#endif
 
namespace PerceptualColor
{
/** @internal
 *
 * @brief Number of vertical <em>standard</em> wheel steps done by a
 *  wheel event
 *
 * As the QWheelEvent documentation explains, there is a common physical
 * standard wheel step size for mouse wheels: 15°. But there are some
 * mouse models which use non-standard physical wheel step sizes for
 * their mouse wheel, for example because they have a higher wheel
 * resolution.
 *
 * This function converts the values in a QMouseEvent to the
 * <em>standard</em> wheel step count.
 *
 * @param event the QWheelEvent
 * @returns the count of vertical <em>standard</em> wheel steps done
 * within this mouse event. The value is positive for up-steps and
 * negative for down-steps. On a standard mouse wheel, moving the wheel
 * one physical step up will return the value 1. On a non-standard,
 * higher resolution mouse wheel, moving the wheel one physical step up
 * will return a smaller value, for example 0.7 */
qreal standardWheelStepCount(QWheelEvent *event)
{
    // QWheelEvent::angleDelta() returns 8 units for each degree.
    // The standard wheel step is 15°. So on a standard
    // mouse, one wheel step results in (8 × 15) units.
    return event->angleDelta().y() / static_cast<qreal>(8 * 15);
}
 
/** @internal
 *
 * @brief Background for semi-transparent colors.
 *
 * When showing a semi-transparent color, there has to be a background
 * on which it is shown. This function provides a suitable background
 * for showcasing a color.
 *
 * @param devicePixelRatioF The desired device-pixel ratio. Must be ≥ 1.
 *
 * @returns An image of a mosaic of neutral gray rectangles of different
 * lightness. You can use this as tiles to paint a background, starting from
 * the top-left corner. This image is made for LTR layouts. If you have an
 * RTL layout, you should horizontally mirror your paint buffer after painting
 * the tiles. The image has its device pixel ratio set to the value that was
 * given in the parameter.
 *
 * @note The image is considering the given device-pixel ratio to deliver
 * sharp (and correctly scaled) images also for HiDPI devices.
 * The painting does not use floating point drawing, but rounds
 * to full integers. Therefore, the result is always a sharp image.
 * This function takes care that each square has the same pixel size,
 * without scaling errors or anti-aliasing errors.
 *
 * @sa @ref AbstractDiagram::transparencyBackground()
 *
 * @todo Provide color management support! Currently, we use the same
 * value for red, green and blue, this might <em>not</em> be perfectly
 * neutral gray depending on the color profile of the monitor… And: We
 * should make sure that transparent colors are not applied by Qt on top
 * of this image. Instead, add a parameter to this function to get the
 * transparent color to paint above, and do color-managed overlay of the
 * transparent color, in Lch space. For each Lab (not Lch!) channel:
 * result = opacity * foreground + (100% - opacity) * background. */
QImage transparencyBackground(qreal devicePixelRatioF)
{
    // The valid lightness range is [0, 255]. The median is 127/128.
    // We use two color with equal distance to this median to get a
    // neutral gray.
    constexpr int lightnessDistance = 15;
    constexpr int lightnessOne = 127 - lightnessDistance;
    constexpr int lightnessTwo = 128 + lightnessDistance;
    constexpr int squareSizeInLogicalPixel = 10;
    const int squareSize = qRound(squareSizeInLogicalPixel * devicePixelRatioF);
 
    QImage temp(squareSize * 2, squareSize * 2, QImage::Format_RGB32);
    temp.fill(QColor(lightnessOne, lightnessOne, lightnessOne));
    QPainter painter(&temp);
    QColor foregroundColor(lightnessTwo, lightnessTwo, lightnessTwo);
    painter.fillRect(0, 0, squareSize, squareSize, foregroundColor);
    painter.fillRect(squareSize, squareSize, squareSize, squareSize, foregroundColor);
    temp.setDevicePixelRatio(devicePixelRatioF);
    return temp;
}
 
/** @internal
 *
 * @brief Draws a QWidget respecting Qt Style Sheets.
 *
 * When subclassing QWidget-derived classes, the Qt Style Sheets are
 * considered automatically. But when subclassing QWidget itself, the
 * Qt Style Sheets are <em>not</em> considered automatically. Also,
 * calling <tt>QWidget::paintEvent()</tt> from the subclass’s paint
 * event does not help. Instead, call this function from within your
 * subclass’s paint event. It uses some special code as documented
 * in the <em>Qt Style Sheets Reference</em> in the section about QWidget.
 *
 * @warning This function creates a QPainter for the widget. As there
 * should be not more than one QPainter at the same time for a given
 * paint device, you may not call this function while a QPainter
 * exists for the widget. Therefore, it is best to call this
 * function as very first statement in your paintEvent() implementation,
 * before initializing any QPainter.
 *
 * @param widget the widget */
void drawQWidgetStyleSheetAware(QWidget *widget)
{
    QStyleOption opt;
    opt.initFrom(widget);
    QPainter p(widget);
    widget->style()->drawPrimitive(QStyle::PE_Widget, &opt, &p, widget);
}
 
/** @internal
 *
 * @brief Provides prefix and suffix of a value from a given format string.
 *
 * A typical use case: You want to put a percent value into a spinbox. The
 * simple approach would be:
 * @snippet testhelper.cpp percentTraditional
 * It could be improved like this:
 * @snippet testhelper.cpp percentImproved
 * However, in some languages, the position of the prefix and suffix may be
 * reversed compared to English. Example: In English, you write 50\%, but in
 * Turkish, you write \%50. Qt does not offer an out-of-the-box solution for
 * this. This helper now provides complete internationalization for prefixes
 * and suffixes of spin boxes, allowing to do this easily in a fail-safe way:
 * @snippet testhelper.cpp percentFullyInternationalized
 *
 * @param formatString A translated string in the format "prefix%1suffix". It
 * should contain exactly <em>one</em> place marker as described in
 * <tt>QString::arg()</tt> like <tt>\%1</tt> or <tt>\%L2</tt>. This place
 * marker represents the value. Example: “Prefix\%1Suffix”. Prefix and suffix
 * may be empty.
 *
 * @returns If the <tt>formatString</tt> parameter has the correct format,
 * the prefix will be returned at <tt>QPair::first</tt> and the suffix will
 * be returned at <tt>QPair::second</tt>. Otherwise, they will be set to an
 * empty string. */
[[nodiscard]] QPair<QString, QString> getPrefixSuffix(const QString &formatString)
{
    // QString::arg() support for %L2, %5 etc which translators might expect:
    const auto list = formatString //
                          .arg(QStringLiteral("%1")) //
                          .split(QStringLiteral("%1"));
    if (list.count() == 2) {
        return QPair<QString, QString>(list.at(0), list.at(1));
    }
    return QPair<QString, QString>(QString(), QString());
}
 
/** @internal
 *
 * @brief Icon from theme.
 *
 * @param names List of names, preferred names first. The system’s icon
 *              themes are searched for this.
 * @param fallback If the system icon themes do not provide an icon, use
 *                 this fallback icon from the built-in resources.
 * @param type Type of widget color scheme for which the fallback icon (if
 *             used) should be suitable.
 *
 * @returns An icon from the system icons and or a fallback icons. If none is
 * available, an empty icon. */
QIcon qIconFromTheme(const QStringList &names, const QString &fallback, ColorSchemeType type)
{
#ifdef PERCEPTUALCOLORINTERNAL
    Q_UNUSED(names)
#else
    // Try to find icon in theme
    for (auto const &name : std::as_const(names)) {
        const QIcon myIcon = QIcon::fromTheme(name);
        if (!myIcon.isNull()) {
            return myIcon;
        }
    }
#endif
 
    // Return fallback icon
    initializeLibraryResources();
    QString path = QStringLiteral( //
        ":/PerceptualColor/icons/lighttheme/%1.svg");
    if (type == ColorSchemeType::Dark) {
        path = QStringLiteral( //
            ":/PerceptualColor/icons/darktheme/%1.svg");
    }
    return QIcon(path.arg(fallback));
}
 
/** @internal
 *
 * @brief Converts text with mnemonics to rich text rendering the mnemonics.
 *
 * At some places in Qt, mnemonics are used. For example, setting
 * <tt>QPushButton::setText()</tt> to "T&est" will make appear the text
 * "Test". If mnemonic support is enabled in the current platform theme,
 * the "e" is underlined.
 *
 * At some other places in Qt, rich text is used. For example, setting
 * <tt>QWidget::setToolTip()</tt> to "T<u>e</u>st" will make appear the text
 * "Test", but with the "e" underlined.
 *
 * @param mnemonicText A text that might contain mnemonics
 *
 * @returns A rich text that will render in rich-text-functions with the same
 * rendering as if the mnemonic text would have been
 * used in mnemonic-functions: If currently in the platform theme,
 * auto-mnemonics are enabled, the mnemonics are underlined. Otherwise,
 * the mnemonics are not underlined nor is the “&” character visible
 *
 * @note This function mimics Qt’s algorithm form mnemonic rendering quite
 * well, but there might be subtile differences in corner cases. Like Qt,
 * this function accepts multiple occurrences of "&" in the same string, even
 * before different characters, and underlines all of them, though
 * <tt>QKeySequence::mnemonic()</tt> will return only one of them as
 * shortcut. */
QString fromMnemonicToRichText(const QString &mnemonicText)
{
    QString result;
 
    const bool doUnderline = !QKeySequence::mnemonic(mnemonicText).isEmpty();
    const auto underlineStart = doUnderline ? QStringLiteral("<u>") : QString();
    const auto underlineStop = doUnderline ? QStringLiteral("</u>") : QString();
 
    bool underlineNextChar = false;
    for (int i = 0; i < mnemonicText.length(); ++i) {
        if (mnemonicText[i] == QStringLiteral("&")) {
            const auto nextChar = //
                (i + 1 < mnemonicText.length()) //
                ? mnemonicText[i + 1]
                : QChar();
            if (nextChar == QStringLiteral("&")) {
                // Double ampersand: Escape the "&"
                result.append(QStringLiteral("&"));
                i++; // Skip the second "&"
            } else {
                // Single ampersand: Start underline
                underlineNextChar = true;
            }
        } else {
            if (underlineNextChar) {
                // End underline
                result.append(underlineStart);
                result.append(mnemonicText[i]);
                result.append(underlineStop);
                underlineNextChar = false;
            } else {
                result.append(mnemonicText[i]);
            }
        }
    }
 
    return result;
}
 
/** @internal
 *
 * @brief Guess the actual @ref ColorSchemeType of a given widget.
 *
 * It guesses the color scheme type actually used by the current widget style,
 * and not the type of the current color palette. This makes a difference
 * for example on the Windows Vista style, which might ignore the palette and
 * use always a light theme instead.
 *
 * @param widget The widget to evaluate
 *
 * @returns The guessed schema, or <tt>std::nullopt</tt> if
 * nothing could be guessed.
 *
 * @note The exact implementation of the guess  might change over time.
 *
 * @internal
 *
 * The current implementation takes a screenshot of the widget and calculates
 * the average lightness of this screenshot and determines the color schema
 * type accordingly. It returns <tt>std::nullopt</tt> if the widget
 * is <tt>nullptr</tt> or its size is empty.
 *
 * @note With Qt 6.5, there is
 * <a href="https://www.qt.io/blog/dark-mode-on-windows-11-with-qt-6.5">
 * better access to color themes</a>. Apparently, the Windows Vista style
 * now seems to polish the widgets by setting a light color palette, so
 * also on Windows Vista style we could simply rely on the color palette
 * and test if the text color is lighter or darker than the background color
 * to determine the color scheme type. This would also give us more reliable
 * results with color schemes that have background colors around 50% lightness,
 * which our currently implementation has problems to get right. But on
 * the other hand, other styles like Kvantum might still chose to ignore
 * the color palette, so it seems safer to stay with the current
 * implementation. */
std::optional<ColorSchemeType> guessColorSchemeTypeFromWidget(QWidget *widget)
{
    if (widget == nullptr) {
        return std::nullopt;
    }
 
    // Take a screenshot of the widget
    const QImage screenshot = widget->grab().toImage();
    if (screenshot.size().isEmpty()) {
        return std::nullopt;
    }
 
    // Calculate the average lightness of the screenshot
    QColorFloatType lightnessSum = 0;
    for (int y = 0; y < screenshot.height(); ++y) {
        for (int x = 0; x < screenshot.width(); ++x) {
            lightnessSum += QColor(screenshot.pixel(x, y)).lightnessF();
        }
    }
    const auto pixelCount = screenshot.width() * screenshot.height();
    constexpr QColorFloatType threeshold = 0.5;
    const bool isDark = //
        (lightnessSum / static_cast<QColorFloatType>(pixelCount)) < threeshold;
    if (isDark) {
        return ColorSchemeType::Dark;
    }
    return ColorSchemeType::Light;
}
 
/** @brief Swatch grid derived from the basic colors as by WCS (World color
 * survey).
 *
 * The swatch grid contains various tints and shades of the
 * basic colors. The choice of the basic colors is based on the
 * <a href="https://en.wikipedia.org/wiki/Basic_Color_Terms:_Their_Universality_and_Evolution">
 * study by Brent Berlin and Paul Kay</a>, who suggest that the
 * basic color terms in almost all languages on earth follow a universal
 * pattern. They propose that there are eleven basic color terms that appear
 * in this order during the evolution of a language:
 *
 * 1. black, white
 * 2. red
 * 3. green, yellow
 * 4. blue
 * 5. brown
 * 6. purple, pink, orange, gray
 *
 * Additionally, people worldwide seem to agree quite well on the typical
 * values of each of these color terms. This theory is a fascinating one
 * and forms a good basis for choosing basic colors for this swatch grid.
 *
 * This widget's colors have been arranged largely according to the color
 * wheel of the perceptually uniform color space. We start with the saturated
 * basic colors: red, orange, yellow, green, blue, and purple in order of
 * their hue angles. Next, we have pink and brown, which have roughly the
 * same hue as red or orange but are less saturated. These are simply the
 * less chromatic parts of this hue but are nevertheless perceived by humans as
 * independent colors. For each of these basic colors, there are five variants
 * in the order of <a href="https://en.wikipedia.org/wiki/Tints_and_shades">
 * tint, pure color, and shade</a>. Following the saturated colors and
 * eventually the less saturated ones, the gray axis comes in last place.
 *
 * What exact colors are used? What exactly is a typical “red” or a
 * “green”? Doesn’t every human have a slightly different
 * feeling what a “typical” red or a “typical” blue is? We
 * need a <em>focal color</em>, which is, according to
 * <a href="https://www.oxfordreference.com/display/10.1093/oi/authority.20110803095825870">
 * Oxford Reference</a>:
 *
 * > “A colour that is a prototypical instance of a particular colour name,
 * > such as a shade of red that a majority of viewers consider to be the
 * > best example of a red colour.”
 *
 * The <a href="https://www1.icsi.berkeley.edu/wcs/">World Color Survey</a>
 * (WCS) is a significant study about focal colors of speakers of different
 * languages across the world. The data from this survey is available online,
 * and while it does not provide direct values for focal colors, various
 * studies have used this data to determine focal colors for some
 * <em>basic color terms</em> and a naming centroid for others.
 *
 * The table below shows the WCS grid coordinates for the basic color terms
 * along with the corresponding Cielab values for the focal color (where
 * available) or the naming centroid (where focal color data is unavailable).
 *
 * |Basic color term|WCS grid coordinates|Cielab³ L|Cielab³ a|Cielab³ b|
 * | :--------------| -----------------: | ------: | ------: | ------: |
 * | white¹         |                 A0 |   96.00 |   -0.06 |    0.06 |
 * | black¹         |                 J0 |   15.60 |   -0.02 |    0.02 |
 * | red¹           |                 G1 |   41.22 |   61.40 |   17.92 |
 * | yellow¹        |                 C9 |   81.35 |    7.28 |  109.12 |
 * | green¹         |                F17 |   51.57 |  -63.28 |   28.95 |
 * | blue¹          |                F29 |   51.57 |   -3.41 |  -48.08 |
 * | brown³         |                 G7 |   41.22 |   17.04 |   45.95 |
 * | purple³        |                G34 |   41.22 |   33.08 |  -30.50 |
 * | pink³          |                 E1 |   61.70 |   49.42 |   18.23 |
 * | orange³        |                 E6 |   61.70|    29.38 |   64.40 |
 * | gray           |      not available |         |         |         |
 *
 * ¹ Focal color as proposed by
 *   <a href="https://www.pnas.org/doi/10.1073/pnas.0503281102">Focal colors
 *   are universal after all</a>.
 *
 * ² Raw estimation of the naming centroid based on Fig. 4 of
 *   <a href="https://sites.socsci.uci.edu/~kjameson/ECST/Kay_Cook_WorldColorSurvey.pdf">
 *   this document</a>. (Fig. 5 would be the better choice, as it gives the
 *   focal color instead of the naming centroid, but unfortunately contains
 *   only red, yellow, green and blue, for which we have yet direct data.)
 *
 * ³ <a href="https://www1.icsi.berkeley.edu/wcs/data/cnum-maps/cnum-vhcm-lab-new.txt">
 *   Lookup table providing Lab values for WCS grid coordinates</a> and the
 *   <a href="https://www1.icsi.berkeley.edu/wcs/data/cnum-maps/cnum-vhcm-lab-new-README.txt">
 *   corresponding explanation</a>.
 *
 * From this data, the colors in our swatch grid have been derived as follows:
 * - The gray axis has been defined manually, ignoring the WCS data. Chroma
 *   is 0. The lightness is 100% for white, 0% for black, and 75%, 50%,
 *   and 25% for the intermediate grays.
 * - The other columns for chromatic colors use the WCS data for the swatch in
 *   the middle. Tints and shades are calculated by adding or reducing chroma
 *   and lightness within the Oklab color space. If the resulting color falls
 *   outside the color space, a nearby in-gamut color is chosen instead.
 *
 * @param colorSpace The color space in which the return value is calculated.
 *
 * @returns Swatch grid derived from the basic colors. Provides as a list of
 * basic colors (in this order: red, orange, yellow, green, blue, purple, pink,
 * brown, gray axis). Each basic color is a list of 5 swatches (starting with
 * the lightest and finishing with the darkest: 2 tints, the tone itself,
 * 2 shades).
 *
 * @note The RGB value is rounded to full integers in the range [0, 255]. */
Swatches wcsBasicColors(const QSharedPointer<PerceptualColor::RgbColorSpace> &colorSpace)
{
    constexpr GenericColor red{41.22, 61.40, 17.92};
    constexpr GenericColor orange{61.70, 29.38, 64.40};
    constexpr GenericColor yellow{81.35, 07.28, 109.12};
    constexpr GenericColor green{51.57, -63.28, 28.95};
    constexpr GenericColor blue{51.57, -03.41, -48.08};
    constexpr GenericColor purple{41.22, 33.08, -30.50};
    constexpr GenericColor pink{61.70, 49.42, 18.23};
    constexpr GenericColor brown{41.22, 17.04, 45.95};
    constexpr std::array<GenericColor, 8> chromaticCielabColors //
        {{red, orange, yellow, green, blue, purple, pink, brown}};
 
    // Lowest common denominator of QList‘s and std::array’s size types:
    using MySizeType = quint8;
 
    constexpr MySizeType columnCount = //
        chromaticCielabColors.size() + 1; // + 1 for gray axis
    constexpr auto rowCount = 5;
    Swatches wcsSwatches{columnCount, rowCount};
 
    // Chromatic colors
    constexpr double strongTint = 0.46;
    constexpr double weakTint = 0.23;
    constexpr double weakShade = 0.18;
    constexpr double strongShade = 0.36;
    std::array<GenericColor, rowCount> tintsAndShades;
    for (MySizeType i = 0; i < chromaticCielabColors.size(); ++i) { //
        const auto oklch = AbsoluteColor::convert( //
                               ColorModel::CielabD50, //
                               chromaticCielabColors.at(i),
                               ColorModel::OklchD65 //
                               )
                               .value_or(GenericColor());
        tintsAndShades[0] = GenericColor //
            {oklch.first + (1 - oklch.first) * strongTint, //
             oklch.second * (1 - strongTint), //
             oklch.third};
        tintsAndShades[1] = GenericColor //
            {oklch.first + (1 - oklch.first) * weakTint, //
             oklch.second * (1 - weakTint), //
             oklch.third};
        tintsAndShades[2] = oklch;
        tintsAndShades[3] = GenericColor //
            {oklch.first * (1 - weakShade), //
             oklch.second * (1 - weakShade), //
             oklch.third};
        tintsAndShades[4] = GenericColor //
            {oklch.first * (1 - strongShade), //
             oklch.second * (1 - strongShade), //
             oklch.third};
        for (MySizeType j = 0; j < rowCount; ++j) {
            const auto variationCielchD50 = AbsoluteColor::convert( //
                                                ColorModel::OklchD65, //
                                                tintsAndShades.at(j), //
                                                ColorModel::CielchD50 //
                                                )
                                                .value_or(GenericColor());
            const auto variationRgb = colorSpace->fromCielchD50ToQRgbBound( //
                variationCielchD50);
            wcsSwatches.setValue(i, //
                                 j,
                                 variationRgb);
        }
    }
 
    // Gray axis
    QList<double> lightnesses{1, 0.75, 0.5, 0.25, 0};
    for (int j = 0; j < lightnesses.count(); ++j) {
        const GenericColor myOklab{lightnesses.at(j), 0, 0};
        const auto cielchD50 = AbsoluteColor::convert( //
                                   ColorModel::OklabD65, //
                                   myOklab, //
                                   ColorModel::CielchD50 //
                                   )
                                   .value_or(GenericColor());
        const auto rgb = colorSpace->fromCielchD50ToQRgbBound(cielchD50);
        wcsSwatches.setValue(columnCount - 1, j, rgb);
    }
 
    return wcsSwatches;
}
 
} // namespace PerceptualColor