chromahuediagram.h

// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
// SPDX-License-Identifier: BSD-2-Clause OR MIT
 
#ifndef CHROMAHUEDIAGRAM_H
#define CHROMAHUEDIAGRAM_H
 
#include "abstractdiagram.h"
#include "constpropagatinguniquepointer.h"
#include "genericcolor.h"
#include "importexport.h"
#include <qglobal.h>
#include <qsharedpointer.h>
#include <qsize.h>
 
#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
#include <qtmetamacros.h>
#else
#include <qobjectdefs.h>
#include <qstring.h>
class QObject;
#endif
 
class QKeyEvent;
class QMouseEvent;
class QPaintEvent;
class QResizeEvent;
class QWheelEvent;
class QWidget;
 
namespace PerceptualColor
{
class ChromaHueDiagramPrivate;
}
namespace PerceptualColor
{
class RgbColorSpace;
}
 
namespace PerceptualColor
{
/** @brief A widget for selecting chroma and hue in LCH color space
 *
 * This widget displays the plan of chroma and hue
 * (that means a diagram of the radius and the angle of the
 * LCH color space respectively the a axis and the b axis of the
 * <a href="https://en.wikipedia.org/wiki/CIELAB_color_space">
 * Lab color model</a>) at a given lightness.
 *
 * @image html ChromaHueDiagram.png "ChromaHueDiagram" width=250
 *
 * The widget allows the user to select a color (chroma and hue) within the
 * specified gamut at a given lightness. It reacts on mouse events and on
 * keyboard events (see @ref keyPressEvent() for details).
 *
 * The form of the selection handle (that always indicates the distance from
 * the center of the diagram) and the circular form of the widget, all this
 * helps the user to understand intuitively that he is moving within a
 * polar coordinate system and to capture easily the current radius
 * and angle.
 *
 * Usage example: @snippet testchromahuediagram.cpp instantiate
 *
 * @note This widget <em>always</em> accepts focus by a mouse click within
 * the circle. This happens regardless of the <tt>QWidget::focusPolicy</tt>
 * property:
 * - If you set the <tt>QWidget::focusPolicy</tt> property to a
 *   value that does not accept focus by mouse click, the focus
 *   will nevertheless be accepted for clicks within the actual circle.
 *   (This is the default behavior.)
 * - If you set the <tt>QWidget::focusPolicy</tt> property to a
 *   value that accepts focus by mouse click, the focus will not only be
 *   accepted for clicks within the actual circle, but also for clicks
 *   anywhere within the (rectangular) widget.
 *
 * @internal
 *
 * @todo BUG Left-click in the gray area inside the wheel but outside
 * the displayed gamut; maintain the click button and do not move the
 * mouse. Actual behavior: Mouse cursor is invisible. Expected behaviour:
 * Mouse cursor stays visible (as it would be anyway after moving the mouse).
 *
 * @todo BUG Click on the wheel. Actual behaviour: Nothing. Expected behavior:
 * The selected color follows the cursor.
 *
 * @todo BUG Wide gamut RGB: RGB 51 255 51. Chroma-Hue-Diagram: The handle
 * is drawn outside the circle. This should never happen! See also
 * @ref PerceptualColor::CielchD50Values::maximumChroma
 *
 * @todo The hue circle around chroma-hue diagram might be confusing because
 * it is colored, but it is not a usable slider like all other colored
 * elements. We could remove it. But on the other hand, it is also useful
 * to have it. Maybe make it look different than for @ref WheelColorPicker,
 * for instance make it thinner and make it touch the gray diagram area?
 * Maybe make it react on mouse events just like the inner part of the diagram.
 *
 * @todo Add a circular indicator to the handle, indicating the values
 * with identical chroma? Only during mouse dragging? Or always? Or never?
 *
 * @todo Example code: How to create the widget at a given
 * lightness.
 *
 * @todo Allow to touch the widget on the color wheel (and have a reaction).
 *
 * @todo Use a cross cursor for better usability: The cross cursor indicates
 * to the user that an area can be clicked in. Do it only within the gamut
 * (where the color handle can actually go) or in the hole gray circle,
 * which is the mouse sensitive area (but out of the gamut the color
 * handle cannot follow)?
 *
 * @todo Support additional mouse buttons. For example, “forward” and
 * “backward” could be used to increase or decrease the radius.
 *
 * @todo What if black or white are out of gamut on L=0.1 or L=99.9? Where
 * are the handles placed? Visible or invisible? How to react? Should
 * there be always a physical pixel in the middle that is visible (black
 * or white) even when out of gamut?
 *
 * @todo Optimization: It might be possible to <em>not</em> store
 * both, @ref ChromaHueDiagramPrivate::m_chromaHueImage and
 * a @ref ChromaHueDiagramPrivate::m_wheelImage. Instead, both could
 * be combined into one single image. As long as there is a (big enough)
 * safety margin between the color wheel and the inner (circular) diagram
 * surface, it should be possible to erase the original data and paint
 * new data above without rendering artefacts for each of these two elements
 * of the image. */
class PERCEPTUALCOLOR_IMPORTEXPORT ChromaHueDiagram : public AbstractDiagram
{
    Q_OBJECT
 
    /** @brief Currently selected color
     *
     * The widget allows the user to change the LCH chroma and the LCH hue
     * values. However, the LCH lightness value cannot be changed by the
     * user, but only by the programmer through this property.
     *
     * The programmer can set this property to out-of-gamut values; the
     * user cannot.
     *
     * @sa READ @ref currentColorCielchD50() const
     * @sa WRITE @ref setCurrentColorCielchD50()
     * @sa NOTIFY @ref currentColorCielchD50Changed() */
    Q_PROPERTY(GenericColor currentColorCielchD50 READ currentColorCielchD50 WRITE setCurrentColorCielchD50 NOTIFY currentColorCielchD50Changed)
 
public:
    Q_INVOKABLE explicit ChromaHueDiagram(const QSharedPointer<PerceptualColor::RgbColorSpace> &colorSpace, QWidget *parent = nullptr);
    virtual ~ChromaHueDiagram() noexcept override;
    /** @brief Getter for property @ref currentColorCielchD50
     *  @returns the property @ref currentColorCielchD50 */
    [[nodiscard]] GenericColor currentColorCielchD50() const;
    [[nodiscard]] virtual QSize minimumSizeHint() const override;
    [[nodiscard]] virtual QSize sizeHint() const override;
 
public Q_SLOTS:
    void setCurrentColorCielchD50(const PerceptualColor::GenericColor &newCurrentColorCielchD50);
 
Q_SIGNALS:
    /** @brief Notify signal for property @ref currentColorCielchD50.
     *  @param newCurrentColorCielchD50 the new current color */
    void currentColorCielchD50Changed(const PerceptualColor::GenericColor &newCurrentColorCielchD50);
 
protected:
    virtual void keyPressEvent(QKeyEvent *event) override;
    virtual void mouseMoveEvent(QMouseEvent *event) override;
    virtual void mousePressEvent(QMouseEvent *event) override;
    virtual void mouseReleaseEvent(QMouseEvent *event) override;
    virtual void paintEvent(QPaintEvent *event) override;
    virtual void resizeEvent(QResizeEvent *event) override;
    virtual void wheelEvent(QWheelEvent *event) override;
 
private:
    Q_DISABLE_COPY(ChromaHueDiagram)
 
    /** @internal
     *
     * @brief Declare the private implementation as friend class.
     *
     * This allows the private class to access the protected members and
     * functions of instances of <em>this</em> class. */
    friend class ChromaHueDiagramPrivate;
    /** @brief Pointer to implementation (pimpl) */
    ConstPropagatingUniquePointer<ChromaHueDiagramPrivate> d_pointer;
 
    /** @internal @brief Only for unit tests. */
    friend class TestChromaHueDiagram;
};
 
} // namespace PerceptualColor
 
#endif // CHROMAHUEDIAGRAM_H