File indexing completed on 2024-05-12 04:44:33

 // SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
 // SPDX-License-Identifier: BSD-2-Clause OR MIT
 
 #ifndef HELPER_H
 #define HELPER_H
 
 #include "helpermath.h"
 #include "helperqttypes.h"
 #include <QtCore/qsharedpointer.h>
 #include <optional>
 #include <qcontainerfwd.h>
 #include <qcoreapplication.h>
 #include <qglobal.h>
 #include <qicon.h>
 #include <qimage.h>
 #include <qlist.h>
 #include <qmetaobject.h>
 #include <qpair.h>
 #include <qstring.h>
 #include <qstringliteral.h>
 #include <qthread.h>
 
 class QColor;
 class QWheelEvent;
 class QWidget;
 
 namespace PerceptualColor
 {
 
 class RgbColorSpace;
 
 /** @brief Represents the appearance of a theme. */
 enum class ColorSchemeType {
     Light, /**< Light theme. */
     Dark /**< Dark theme. */
 };
 
 void drawQWidgetStyleSheetAware(QWidget *widget);
 
 QString fromMnemonicToRichText(const QString &mnemonicText);
 
 std::optional<ColorSchemeType> guessColorSchemeTypeFromWidget(QWidget *widget);
 
 /** @internal
  *
  * @brief Convenience function template that tests if a value is in a list.
  *
  * @param first The value
  * @param t The list
  *
  * Usage:
  * @snippet testhelper.cpp isInUsage
  *
  * @returns <tt>true</tt> if “value” is in “list”. <tt>false</tt> otherwise. */
 template<typename First, typename... T>
 bool isIn(First &&first, T &&...t)
 {
     // Solution as proposed by Nikos C. in https://stackoverflow.com/a/15181949
     return ((first == t) || ...);
 }
 
 [[nodiscard]] qreal standardWheelStepCount(QWheelEvent *event);
 
 [[nodiscard]] QImage transparencyBackground(qreal devicePixelRatioF);
 
 /** @internal
  *
  * @brief Two-dimensional array */
 template<typename T>
 class Array2D
 {
 public:
     /** @brief Constructor.
      *
      * Constructs an array with the size 0 × 0. */
     Array2D()
         : m_iCount(0)
         , m_jCount(0)
     {
     }
 
     /** @brief Constructor.
      *
      * @param iCount size (first dimension)
      * @param jCount size (second dimension)
      *
      * The elements are initialized with default-constructed values. */
     Array2D(QListSizeType iCount, QListSizeType jCount)
         : m_iCount(iCount)
         , m_jCount(jCount)
     {
         if (m_iCount < 0) {
             m_iCount = 0;
         }
         if (m_jCount < 0) {
             m_jCount = 0;
         }
         const auto elementCount = m_iCount * m_jCount;
         m_data.reserve(elementCount);
         for (QListSizeType i = 0; i < elementCount; ++i) {
             m_data.append(T());
         }
     }
 
     /** @brief Constructor.
      *
      * @param iCount size (first dimension)
      * @param jCount size (second dimension)
      * @param init Initial values. Excess elements are ignored. Missing
      *        elements are initialized with default-constructed values. */
     Array2D(QListSizeType iCount, QListSizeType jCount, QList<T> init)
         : m_iCount(iCount)
         , m_jCount(jCount)
     {
         if (m_iCount < 0) {
             m_iCount = 0;
         }
         if (m_jCount < 0) {
             m_jCount = 0;
         }
         const auto elementCount = m_iCount * m_jCount;
         m_data.reserve(elementCount);
         for (QListSizeType i = 0; i < elementCount; ++i) {
             if (i < init.count()) {
                 m_data.append(init.value(i));
             } else {
                 m_data.append(T());
             }
         }
     }
 
     /** @brief Set value at a given index.
      *
      * @param i index (first dimension)
      * @param j index (second dimension)
      * @param value value to set */
     void setValue(QListSizeType i, QListSizeType j, const T &value)
     {
         if (isInRange<QListSizeType>(0, i, m_iCount - 1) //
             && isInRange<QListSizeType>(0, j, m_jCount - 1) //
         ) {
             m_data[i + m_iCount * j] = value;
         }
     }
 
     /** @brief Get value at a given index.
      *
      * @param i index (first dimension)
      * @param j index (second dimension)
      * @returns If the indices are valid, the value at the given indeces.
      * A default-constructed value otherwise. */
     T value(QListSizeType i, QListSizeType j) const
     {
         if (isInRange<QListSizeType>(0, i, m_iCount - 1) //
             && isInRange<QListSizeType>(0, j, m_jCount - 1) //
         ) {
             return m_data[i + m_iCount * j];
         }
         return T(); // Default value if indices are out of bounds
     }
 
     /** @brief Size of the first dimension.
      *
      * @returns Size of the first dimension. */
     QListSizeType iCount() const
     {
         return m_iCount;
     }
 
     /** @brief Size of the second dimension.
      *
      * @returns Size of the second dimension. */
     QListSizeType jCount() const
     {
         return m_jCount;
     }
 
 private:
     /** @brief Internal storage of the elements. */
     QList<T> m_data;
     /** @brief Internal storage of @ref iCount(). */
     QListSizeType m_iCount;
     /** @brief Internal storage of @ref jCount(). */
     QListSizeType m_jCount;
 };
 
 /** @internal
  *
  * @brief Force processing of events in a delayed fashion.
  *
  * When there is no running event loop (like in unit tests or in tools
  * like the screenshot generator), some parts of the asynchronous API
  * of this library does not work. Calling this function fixes this by
  * forcing the processing of pending events, but with some delay
  * in-between, so that maybe existing parallel threads have also
  * a chance to terminate their work.
  *
  * @param msecWaitInitially Delay before starting event processing.
  * @param msecWaitBetweenEventLoopPasses Delay before each pass through
  *        through the pending events.
  * @param numberEventLoopPasses Number of passes through the pending events.
  *
  * @internal
  *
  * @note This is declared as template to prevent that this code is compiled
  * into the library itself, which does <em>not</em> actually use it itself,
  * but includes this header file. */
 template<typename T = void>
 void delayedEventProcessing(unsigned long msecWaitInitially = 50, unsigned long msecWaitBetweenEventLoopPasses = 50, int numberEventLoopPasses = 3)
 {
     // Some OSes might round the sleep time up to 15 ms. We do it ourself
     // here to make the behaviour a little bit more predictable.
     msecWaitInitially = qMax<unsigned long>( //
         msecWaitInitially, //
         15);
     msecWaitBetweenEventLoopPasses = //
         qMax<unsigned long>(msecWaitBetweenEventLoopPasses, 15);
 
     QThread::msleep(msecWaitInitially);
     // Hopefully, now the render function has terminated…
     for (int i = 0; i < numberEventLoopPasses; ++i) {
         // Wait again (apparently, threaded event processing needs some time…)
         QThread::msleep(msecWaitBetweenEventLoopPasses);
         QCoreApplication::processEvents();
     }
 }
 
 [[nodiscard]] Array2D<QColor> wcsBasicColors(const QSharedPointer<PerceptualColor::RgbColorSpace> &colorSpace);
 
 [[nodiscard]] QIcon qIconFromTheme(const QStringList &names, const QString &fallback, ColorSchemeType type);
 
 [[nodiscard]] QPair<QString, QString> getPrefixSuffix(const QString &formatString);
 
 /** @brief The full-qualified C++ identifier as QString.
  *
  * This can be useful for debugging purposes.
  *
  * @tparam T The enumeration.
  *
  * @pre The enumeration type is declared with
  * Q_ENUM or Q_ENUM_NS.
  *
  * @returns The full-qualified C++ identifier as QString. */
 template<typename T>
 [[nodiscard]] QString enumerationToFullString()
 {
     const auto myMeta = QMetaEnum::fromType<T>();
     const auto scope = QString::fromUtf8(myMeta.scope());
     const auto name = QString::fromUtf8(myMeta.name());
     return QStringLiteral("%1::%2").arg(scope, name);
 }
 
 /** @brief The full-qualified C++ identifier as QString.
  *
  * This can be useful for debugging purposes.
  *
  * @tparam T The enumeration type. Can usually be omitted.
  *
  * @param enumerator An enumerator.
  *
  * @pre The enumeration type of the enumerator is declared with
  * Q_ENUM or Q_ENUM_NS.
  *
  * @returns The full-qualified C++ identifier as QString, followed by the
  * underlying integer value in parenthesis. If the enumerator does not
  * exist (for example because you have done a static_cast of an invalid
  * integer to  the enum class), an empty String is returned instead. If
  * the enumerator has synonyms (that means, there exist other enumerators
  * that share the same integer with the current enumerator), all synonym
  * enumerators are returned.
  *
  * @sa @ref enumeratorToString() */
 template<typename T>
 [[nodiscard]] QString enumeratorToFullString(const T &enumerator)
 {
     const auto value = static_cast<int>(enumerator);
     const auto myMeta = QMetaEnum::fromType<T>();
 
     // QMetaEnum::valueToKeys (identifier with a final s) returns all existing
     // (synonym) keys for a given value. But it also returns happily
     // fantasy strings for non-existing values. Therefore, we have check
     // first with QMetaEnum::valueToKeys (identifier with a final s) which
     // does only return one single key for each value, but is guaranteed to
     // return nullptr if the value has no key.
     if (!myMeta.valueToKey(value)) {
         return QString();
     }
 
     const auto scope = QString::fromUtf8(myMeta.scope());
     const auto name = QString::fromUtf8(myMeta.name());
     const auto keys = QString::fromUtf8(myMeta.valueToKeys(value));
     return QStringLiteral("%1::%2::%3(%4)").arg(scope, name, keys).arg(value);
 }
 
 /** @brief The C++ identifier as QString.
  *
  * This can be useful for debugging purposes.
  *
  * @tparam T The enumeration type. Can usually be omitted.
  *
  * @param enumerator An enumerator.
  *
  * @pre The enumeration type of the enumerator is declared with
  * Q_ENUM or Q_ENUM_NS.
  *
  * @returns The C++ identifier as QString, followed by the
  * underlying integer value in parenthesis. If the enumerator does not
  * exist (for example because you have done a static_cast of an invalid
  * integer to  the enum class), an empty String is returned instead. If
  * the enumerator has synonyms (that means, there exist other enumerators
  * that share the same integer with the current enumerator), all synonym
  * enumerators are returned.
  *
  * @sa @ref enumeratorToFullString() */
 template<typename T>
 [[nodiscard]] QString enumeratorToString(const T &enumerator)
 {
     const auto value = static_cast<int>(enumerator);
     const auto myMeta = QMetaEnum::fromType<T>();
 
     // QMetaEnum::valueToKeys (identifier with a final s) returns all existing
     // (synonym) keys for a given value. But it also returns happily
     // fantasy strings for non-existing values. Therefore, we have check
     // first with QMetaEnum::valueToKeys (identifier with a final s) which
     // does only return one single key for each value, but is guaranteed to
     // return nullptr if the value has no key.
     if (!myMeta.valueToKey(value)) {
         return QString();
     }
 
     const auto keys = QString::fromUtf8(myMeta.valueToKeys(value));
     return QStringLiteral("%1(%2)").arg(keys).arg(value);
 }
 
 } // namespace PerceptualColor
 
 #endif // HELPER_H