colordialog.h

// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
// SPDX-License-Identifier: BSD-2-Clause OR MIT
 
#ifndef COLORDIALOG_H
#define COLORDIALOG_H
 
#include "constpropagatinguniquepointer.h"
#include "importexport.h"
#include <qcolor.h>
#include <qcolordialog.h>
#include <qdialog.h>
#include <qglobal.h>
#include <qmetatype.h>
#include <qnamespace.h>
#include <qsharedpointer.h>
#include <qstring.h>
class QEvent;
class QObject;
class QShowEvent;
class QWidget;
 
#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
#include <qtmetamacros.h>
#else
#include <qobjectdefs.h>
#endif
 
namespace PerceptualColor
{
class ColorDialogPrivate;
 
class RgbColorSpace;
 
/** @brief A perceptually uniform color picker dialog
 *
 * The color dialog’s function is to allow users to choose colors intuitively.
 * For example, you might use this in a drawing program to allow the user to
 * set the brush color.
 *
 * At difference to QColorDialog, this
 * dialog’s graphical components are perceptually uniform and therefore more
 * intuitive. It’s internally based on the LCH color model, which does reflect
 * the human perception much better than RGB or its transforms like HSV. At
 * the same time, this dialog does not require the user itself to know
 * anything about LCH at all, because the graphical representations is
 * intuitive.
 *
 * @image html ColorDialog.png "ColorDialog" width=500
 * @image html ColorDialogTab1.png "ColorDialog" width=500
 * @image html ColorDialogTab2.png "ColorDialog" width=500
 *
 * It is an @ref qdialogsourceompatibility "mostly source-compatible"
 * replacement for QColorDialog. It also adds some extra functionality
 * that is not available in QColorDialog.
 *
 * Just as with QColorDialog, the static functions provide a modal color
 * dialog. The static getColor() function shows the dialog, and allows
 * the user to specify a color:
 *
 * @snippet testcolordialog.cpp ColorDialog Get color
 *
 * The function can also be used to let
 * users choose a color with a level of transparency: pass the alpha channel
 * option as an additional argument:
 *
 * @snippet testcolordialog.cpp ColorDialog Get color with alpha channel
 *
 * @image html ColorDialogAlpha.png "ColorDialog with alpha channel" width=500
 *
 * More features:
 *
 * - A screen color picker is provided on many platforms.
 *
 * - For a non-modal dialog, use the normal constructors of this class.
 *
 * - The default window title is <em>Select Color</em>, and not the title of
 * your application. It can of course be customized with
 * <tt>QWidget::setWindowTitle()</tt>. The window title will
 * <em>not</em> be updated on <tt>QEvent::LanguageChange</tt> events.
 *
 * - At difference to the usual native platform color dialog, <em>this</em>
 * dialog can be resized. That makes sense, because it allows to see better
 * the gamut image. Therefore, this dialog is by default bigger than the usual
 * native platform color dialog. You can of course customize the dialog
 * size with QWidget::resize() or force a more space-saving layout through
 * the @ref layoutDimensions property.
 *
 * - The @ref ColorPatch that indicates the selected color is placed prominently
 * at the top of the widget. That is also useful for touch screens as the
 * @ref ColorPatch will not be hidden by the hand of the user when the user
 * is touching the above color selection widgets.
 *
 * - This dialog uses icons. See @ref hidpisupport "High DPI support"
 * about how to enable support for high-DPI icons.
 *
 * @note @anchor qdialogsourceompatibility The API of this class is mostly
 * source-compatible to the API of QColorDialog. This is a list of
 * incompatibilities:
 * - The constructors and also @ref getColor() require a color space
 *   as argument.
 * - As this dialog does not provide functionality for custom colors and
 *   standard color, the corresponding static functions of QColorDialog are
 *   not available in this class.
 * - The option <tt>ColorDialogOption::DontUseNativeDialog</tt>
 *   will always remain <tt>false</tt> (even if set explicitly), because it’s
 *   just the point of this library to provide an own, non-native dialog.
 * - While the enum declaration @ref ColorDialogOption itself is aliased
 *   here, this isn't possible for the enum values itself. Therefor, when
 *   working with @ref options, you cannot use <tt>ShowAlphaChannel</tt> but
 *   you have to use the fully qualified identifier (either
 *   <tt>PerceptualColor::ColorDialog::ColorDialogOption::ShowAlphaChannel</tt>
 *   or <tt>QColorDialog::ShowAlphaChannel</tt>, at your option.
 * - Calling @ref setCurrentColor() with colors that
 *   are <em>not</em> <tt>QColor::Spec::Rgb</tt> will lead to an automatic
 *   conversion like QColorDialog does, but at difference to QColorDialog, it
 *   is done with more precision, therefor the resulting
 *   @ref currentColor() might be slightly different. The same is true
 *   for <tt>QColor::Spec::Rgb</tt> types with floating point precision:
 *   While QColorDialog would round to full integers, <em>this</em> dialog
 *   preserves the floating point precision.
 * - When the default constructor is used, unlike QColorDialog, the default
 *   color is <em>not</em> guaranteed to be <tt>Qt::white</tt>.
 *
 * @internal
 *
 * @note In the QColorDialog API, the function <tt>QColorDialog::getRgba()</tt>
 * has been deprecated during the Qt5 life cycle. This class does not provide
 * source compatibility with obsolete functions of the QColorDialog API.
 *
 * @todo The @ref ColorDialogPrivate::m_lchLightnessSelector has a different
 * scale than the @ref ColorDialogPrivate::m_chromaHueDiagram, but both are
 * directly side-by-side in the dialog. Would it make sense to use the
 * same scale for both?
 *
 * @todo Provide an option to enable labels for the
 * <a href="https://www.handprint.com/HP/WCL/color12.html">warm-cool</a>
 * contrast, maybe outside the wheel around the position 45° (warm) and
 * 135° (cool).
 *
 * @todo In web design, CSS4 is often used. CSS4 also supports the
 * <a href="https://www.w3.org/TR/css-color-4/#the-hsl-notation"> HSL</a> and
 * the  <a href="https://www.w3.org/TR/css-color-4/#the-hwb-notation">HBW</a>
 * color space. We should do the same.
 *
 * @todo Provide <tt>setResizable(bool resizable)</tt>. Do not provide
 * a property, because in the background this is setting <em>two</em>
 * different values, which might be conflicting in the moment when read
 * access is done. Code within ColorDialog to enable:
 * <tt><br/>
 *  layout()->setSizeConstraint(QLayout::SetFixedSize);
 * <br/>
 *  setSizeGripEnabled(false);
 * <br/></tt>
 * Document the performance impact: When resizing is allowed (which is the
 * default), the user can make the window very big, which might increase
 * the rendering time considerable.
 *
 * @todo Use <tt>QSignalBlocker</tt> instead of m_updateIsRunning in
 * ColorDialog. Attention: The connection alpha-slider and alpha-spinbox
 * is special and would not work anymore, which has to be fixed.
 *
 * @todo In KDE’s systemsettings, in the “Fonts” settings, there are small
 * buttons showing a “i” symbol (for “information”) that has no functionality,
 * but a tooltip for the widget at the left. Would this be also good for
 * @ref ColorDialog?
 *
 * @todo Recently KDE merged something that displays tooltips and integrates a
 * link that calls the <tt>QWhatsThis</tt> which has more information. Would
 * this be helpful here also?
 *
 * @todo Since August 2021 <a href="https://phabricator.kde.org/T9460">the
 * Breeze styling of spin boxes has changed</a>. Is or should be the
 * new default horizontal alignment “center”?
 *
 * @todo Make sure that @ref ChromaHueDiagram always shows at least at the
 * central physical pixel with an in-gamut color. Solution: Limit the range
 * of the lightness selector? Or a better algorithm in @ref ChromaHueDiagram?
 *
 * @todo Provide (on demand) two patches, like Scribus also does: One for the
 * old color (cannot be modified by the user) and another one for the new
 * color (same behavior as the yet existing color patch). One could be
 * named “before” and the other “after”. Or maybe make this configurable?
 * And put an arrow between the patches, from “before” to “after”. (Be aware:
 * RTL support necessary!)
 *
 * @section uireview Review of the user interface
 *
 * @todo The HLC widget accepts values that are out-of-gamut; the dialog
 * shows the nearest in-gamut color during this moment. Also, the RGB Hex
 * widget accepts intermediatly invalid values (for example, 4-digit-values);
 * the dialog displays the last previously displayed valid color during
 * this moment. Those two situations do not have consiteend behaviour,
 * but there are no good alternatives. However: Would it make sense to
 * keep this behaviour, but display in the @ref ColorPatch an empty
 * value during editing an out-of-gamut HLC value or an invalid RGB Hex values?
 *
 * @todo For the tab widget, use rather icons instead of the text “hue-baded”
 * and “lightness-based”!?
 *
 * @todo Provide more <tt>tooltip()</tt> help for widgets. For
 * @ref WheelColorPicker and @ref ChromaLightnessDiagram, this
 * help text could describe the keyboard controls and be integrated
 * as default value in the class itself. For the other widgets, a
 * help text could be defined here within <em>this</em> class,
 * if appropriate.
 *
 * @todo Touch screen compatibility: In general: What would mean better
 * support for touch-screen and convertible? More things to do? For example,
 * A spin box can also be used on mobile phone (putting the numbers
 * with on-screen keyboard). But the + and - button for increasing
 * or decreasing the values might be too small. And mobile UI uses
 * often wheels for this use case…
 *
 * @section additionalcolordialogfeatures Proposals for additional features
 *
 * @todo The QLineEdit for the hexadecimal RGB values should change lower-case
 * letters on-the-fly (as-you-type) to upper-case letters. And: Maybe it
 * could even be switched to @ref MultiSpinBox (but that would mean implement
 * support for hexadecimal digits in @ref MultiSpinBox).
 *
 * @todo Accept <tt>F5</tt> and <tt>Ctrl+R</tt> just with the same
 * functionality as the gamut button in the HCL @ref MultiSpinBox.
 * But attention: If a library user <em>embeds</em> the dialog, he does
 * not want his shortcuts to be intercepted!
 *
 * @todo It might be nice to support keyboard shortcuts for switching tabs
 * like in browsers, which is a concept many users might be familiar to.
 * Crtl+Tab to switch to the next tab in the list. Crtl+Shift+Tab to switch
 * to the previous tab in the list.
 *
 * @todo Start with dialog with Qt::yellow. You get HLC 100° 98% 95.
 * Push the apply button. Actual result: HLC 100° 98% 94 which has a slightly
 * different chroma value. Expected result: Ideally there would be no rounding
 * difference at all: Every once displayed value is always recognized as
 * valid. When the color space conversion takes place, we could (and should)
 * make this sure for HLC values. But then comes the also the rounding
 * in @ref MultiSpinBox. Is there any solution?
 *
 * @todo If there is no alpha widget <em>and</em> the actual layout is
 * expanded (either explicitly by @ref DialogLayoutDimensions::Expanded
 * or implicitly by @ref DialogLayoutDimensions::ScreenSizeDependent on
 * bigger screens) <em>than</em> it would make sense to move
 * the @ref ColorDialogPrivate::m_buttonBox into the same column as
 * the @ref ColorDialogPrivate::m_numericalWidget, namely <em>below</em>
 * the @ref ColorDialogPrivate::m_numericalWidget. This saves screen
 * space and does not confuse the user.
 *
 * @todo Provide an overloaded version of @ref open() that accepts
 * arguments for new-style connect statements, making use of compiler
 * checks.
 *
 * @todo Use the <em>actual</em> color profile of the monitor.
 *
 * @todo The LCh-hue (and so the graphical widgets) jumps forward and backward
 * when changing RGB-based values (also HSV) when entering and leaving the gray
 * axis, due to lack of hue information. Would it be an option to store the
 * old hue to get a meaningful hue?
 * Should it be only really for the gray axis, or allow a certain tolerance
 * around the gray axis is necessary to make this work well - and if so,
 * how much tolerance? Would it be useful to define a certain hue, for
 * example 0°, as default hue for when no old hue is available but the
 * new value is on the gray axis?
 *
 * @todo Custom layout management that has a specific height-per-width ratio
 * considering the @ref ChromaHueDiagram and and @ref WheelColorPicker
 * and <em>their</em> useful height-per-width ratio.
 *
 * @todo Support for other models like HSL (HSB is yet identical to HSV?),
 * Munsell? With an option to enable or disable them? (NCS not, because
 * it is not free…)
 *
 * @todo Would CMYK support make sense? Would it integrate intuitively into
 * the user interface? If we would have CMYK support, we would have two
 * different profiles (RGB and CMYK) active simultaniously. Which one is the
 * profile that defines the available color space? Would this be intuitive?
 * Also, when using two different profiles, it will be possible to have
 * out-of-gamut colors in one of the profiles. How to represent this in the
 * UI?
 *
 * @todo Provide more different swatch grids? Include there a swatch grid
 * with QColorDialog’s standard colors as RGB values without
 * a specific color space, with the name “Default”? Add
 * <a href="https://www.w3.org/TR/css-color-4/#named-colors">CSS colors</a>
 * as defined as sRGB values?
 * <a href="https://en.wikipedia.org/wiki/Web_colors#Web-safe_colors">
 * Web-safe colors</a> (but with another name, maybe “216 colors”)
 * as bigger swatch grid, without a specific color space – does
 * not make sense, since we provide a perceptual color dialog,
 * which allows things much beyond 216 colors, and 216 colors
 * isn’t a useful standard anymore, and not a nice swatch grid either.
 *
 * @todo Discrete widgets, that have
 * a fixed (quite limited) number of fields to chose for the user?
 */
class PERCEPTUALCOLOR_IMPORTEXPORT ColorDialog : public QDialog
{
    Q_OBJECT
 
    /** @brief Currently selected color in the dialog
     *
     * @invariant This property is provided as an RGB value.
     * <tt>QColor::isValid()</tt> is always <tt>true</tt> and
     * <tt>QColor::spec()</tt> is always <tt>QColor::Spec::Rgb</tt>.
     *
     * @invariant The signal @ref currentColorChanged() is emitted always and
     * only when the value of this property changes.
     *
     * @note The setter @ref setCurrentColor() does not accept all QColor
     * values. See its documentation for details.
     *
     * @sa READ @ref currentColor() const
     * @sa WRITE @ref setCurrentColor()
     * @sa NOTIFY @ref currentColorChanged()
     *
     * @internal
     *
     * @note This property does not have <tt>USER true</tt>. While it would
     * be nice to have it, we do not do this because of conformance with
     * QColorDialog, which doesn’t have it either. */
    Q_PROPERTY(QColor currentColor READ currentColor WRITE setCurrentColor NOTIFY currentColorChanged)
 
    /** @brief Layout dimensions
     *
     * Defines if the dialog uses a rather collapsed (small) or a rather
     * expanded (large) layout. In both cases, all elements are present.
     * But for the collapsed variant, more elements are put in
     * tab widgets, while for the expanded variant, more elements are
     * visible at the same time.
     *
     * @image html ColorDialogCollapsed.png "collapsed" height=300
     * @image html ColorDialogExpanded.png "expanded" height=300
     *
     * Default value:
     * @snippet src/colordialog_p.h layoutDimensionsDefaultValue
     *
     * When the layout dimension effectively changes, also the dialog size
     * is adapted.
     *
     * @sa @ref DialogLayoutDimensions
     * @sa READ @ref layoutDimensions() const
     * @sa WRITE @ref setLayoutDimensions()
     * @sa NOTIFY @ref layoutDimensionsChanged
     *
     * @internal
     *
     * @sa @ref ColorDialogPrivate::m_layoutDimensionsEffective
     *
     * @todo Remove this property? Instead, implement a truly convertible
     * layout: Show/hide the widget for numbers depending on dialog size,
     * and maybe even re-arrange even more of the widgets with varying
     * sizes. */
    Q_PROPERTY(DialogLayoutDimensions layoutDimensions READ layoutDimensions WRITE setLayoutDimensions NOTIFY layoutDimensionsChanged)
 
    /** @brief Various options that affect the look and feel of the dialog
     *
     * These are the same settings as for QColorDialog. For compatibility
     * reasons, they are also of the same type: @ref ColorDialogOptions
     *
     * | Option              | Default value | Description
     * | :------------------ | :------------ | :----------
     * | ShowAlphaChannel    | false         | Allow the user to select the alpha component of a color.
     * | NoButtons           | false         | Don't display OK and Cancel buttons. (Useful for “live dialogs”.)
     * | DontUseNativeDialog | true          | Use Qt’s standard color dialog instead of the operating system native color dialog.
     *
     *   @invariant The option <tt>ColorDialogOption::DontUseNativeDialog</tt>
     *   will always be <tt>true</tt> because it’s just the point of
     *   this library to provide an own, non-native dialog. (If you
     *   set  <tt>ColorDialogOption::DontUseNativeDialog</tt> explicitly
     *   to <tt>false</tt>, this will silently be ignored, while the
     *   other options that you might have set, will be correctly applied.)
     *
     * Example:
     * @snippet testcolordialog.cpp setOptionsWithLocalEnum
     * Or:
     * @snippet testcolordialog.cpp setOptionsWithQColorDialogEnum
     * @note At difference to QColorDialog, you need a fully qualified
     * identifier for the enum values. The following code would therefore
     * fail:<br/>
     * <tt>myDialog->setOption(ShowAlphaChannel, false);</tt>
     *
     * @sa READ @ref options() const
     * @sa @ref testOption()
     * @sa WRITE @ref setOptions()
     * @sa @ref setOption()
     * @sa NOTIFY @ref optionsChanged()*/
    Q_PROPERTY(ColorDialogOptions options READ options WRITE setOptions NOTIFY optionsChanged)
 
public:
    /** @brief Local alias for QColorDialog::ColorDialogOption
     *
     * This type is declared as type to Qt’s type system via
     * <tt>Q_DECLARE_METATYPE</tt>. Depending on your use case (for
     * example if you want to use for <em>queued</em> signal-slot connections),
     * you might consider calling <tt>qRegisterMetaType()</tt> for
     * this type, once you have a QApplication object. */
    typedef QColorDialog::ColorDialogOption ColorDialogOption;
    /** @brief Local alias for QColorDialog::ColorDialogOptions
     *
     * This type is declared as type to Qt’s type system via
     * <tt>Q_DECLARE_METATYPE</tt>. Depending on your use case (for
     * example if you want to use for <em>queued</em> signal-slot connections),
     * you might consider calling <tt>qRegisterMetaType()</tt> for
     * this type, once you have a QApplication object. */
    typedef QColorDialog::ColorDialogOptions ColorDialogOptions;
    /** @brief Layout dimensions
     *
     * This enum is declared to the meta-object system with <tt>Q_ENUM</tt>.
     * This happens automatically. You do not need to make any manual calls.
     *
     * This type is declared as type to Qt’s type system via
     * <tt>Q_DECLARE_METATYPE</tt>. Depending on your use case (for
     * example if you want to use for <em>queued</em> signal-slot connections),
     * you might consider calling <tt>qRegisterMetaType()</tt> for
     * this type, once you have a QApplication object. */
    enum class DialogLayoutDimensions {
        ScreenSizeDependent, /**< Decide automatically between
            <tt>collapsed</tt> and <tt>expanded</tt> layout: <tt>collapsed</tt>
            is used on small screens, and <tt>expanded</tt> on big screens. The
            decision is based on the screen size of the <em>default screen</em>
            of the widget (see <tt>QGuiApplication::primaryScreen()</tt> for
            details). The decision is evaluated at the moment when setting this
            value, and again each time the widget is shown again. It is
            <em>not</em> evaluated again when a yet existing dialog is just
            moved to another screen. */
        Collapsed, /**< Use the small, “collapsed“ layout of this dialog. */
        Expanded /**< Use the large, “expanded” layout of this dialog.  */
    };
    Q_ENUM(DialogLayoutDimensions)
    Q_INVOKABLE explicit ColorDialog(QWidget *parent = nullptr);
    Q_INVOKABLE explicit ColorDialog(const QColor &initial, QWidget *parent = nullptr);
    Q_INVOKABLE explicit ColorDialog(const QSharedPointer<PerceptualColor::RgbColorSpace> &colorSpace, QWidget *parent = nullptr);
    Q_INVOKABLE explicit ColorDialog(const QSharedPointer<PerceptualColor::RgbColorSpace> &colorSpace, const QColor &initial, QWidget *parent = nullptr);
    virtual ~ColorDialog() noexcept override;
    /** @brief Getter for property @ref currentColor
     *  @returns the property @ref currentColor */
    [[nodiscard]] QColor currentColor() const;
    [[nodiscard]] static QColor
    getColor(const QColor &initial = Qt::white, QWidget *parent = nullptr, const QString &title = QString(), ColorDialogOptions options = ColorDialogOptions());
    [[nodiscard]] static QColor getColor(const QSharedPointer<PerceptualColor::RgbColorSpace> &colorSpace,
                                         const QColor &initial = Qt::white,
                                         QWidget *parent = nullptr,
                                         const QString &title = QString(),
                                         ColorDialogOptions options = ColorDialogOptions());
    /** @brief Getter for property @ref layoutDimensions
     *  @returns the property @ref layoutDimensions */
    [[nodiscard]] ColorDialog::DialogLayoutDimensions layoutDimensions() const;
    // Make sure not to override the base class’s “open“ function:
    using QDialog::open;
    Q_INVOKABLE void open(QObject *receiver, const char *member);
    /** @brief Getter for property @ref options
     * @returns the current @ref options */
    [[nodiscard]] ColorDialogOptions options() const;
    [[nodiscard]] Q_INVOKABLE QColor selectedColor() const;
    virtual void setVisible(bool visible) override;
    [[nodiscard]] Q_INVOKABLE bool testOption(PerceptualColor::ColorDialog::ColorDialogOption option) const;
 
public Q_SLOTS:
    void setCurrentColor(const QColor &color);
    void setLayoutDimensions(const PerceptualColor::ColorDialog::DialogLayoutDimensions newLayoutDimensions);
    Q_INVOKABLE void setOption(PerceptualColor::ColorDialog::ColorDialogOption option, bool on = true);
    void setOptions(PerceptualColor::ColorDialog::ColorDialogOptions newOptions);
 
Q_SIGNALS:
    /** @brief This signal is emitted just after the user has clicked OK to
     * select a color to use.
     *  @param color the chosen color */
    void colorSelected(const QColor &color);
    /** @brief Notify signal for property @ref currentColor.
     *
     * This signal is emitted whenever the “current color” changes in the
     * dialog.
     * @param color the new “current color” */
    void currentColorChanged(const QColor &color);
    /** @brief Notify signal for property @ref layoutDimensions.
     * @param newLayoutDimensions the new layout dimensions */
    void layoutDimensionsChanged(const PerceptualColor::ColorDialog::DialogLayoutDimensions newLayoutDimensions);
    /** @brief Notify signal for property @ref options.
     * @param newOptions the new options */
    void optionsChanged(const PerceptualColor::ColorDialog::ColorDialogOptions newOptions);
 
protected:
    virtual void changeEvent(QEvent *event) override;
    virtual void done(int result) override;
    virtual void showEvent(QShowEvent *event) override;
 
private:
    Q_DISABLE_COPY(ColorDialog)
 
    /** @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 ColorDialogPrivate;
    /** @brief Pointer to implementation (pimpl) */
    ConstPropagatingUniquePointer<ColorDialogPrivate> d_pointer;
 
    /** @internal @brief Only for unit tests. */
    friend class TestColorDialog;
};
 
} // namespace PerceptualColor
 
Q_DECLARE_METATYPE(PerceptualColor::ColorDialog::ColorDialogOption)
Q_DECLARE_METATYPE(PerceptualColor::ColorDialog::ColorDialogOptions)
Q_DECLARE_METATYPE(PerceptualColor::ColorDialog::DialogLayoutDimensions)
 
#endif // COLORDIALOG_H