Perceptual Color

screencolorpicker.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef SCREENCOLORPICKER
5#define SCREENCOLORPICKER
6
7#include <optional>
8#include <qglobal.h>
9#include <qpointer.h>
10#include <qstring.h>
11#include <qwidget.h>
12class QColorDialog;
13class QPushButton;
14
15#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
16#include <qcontainerfwd.h>
17#include <qtmetamacros.h>
18#else
19#include <qmetatype.h>
20#include <qobjectdefs.h>
21class QObject;
22#endif
23
24namespace PerceptualColor
25{
26
27/** @internal
28 *
29 * @brief Pick a color from the screen.
30 *
31 * Provides an interface to let the user pick a color from the screen.
32 *
33 * This feature is not available on all platforms. Use @ref isAvailable()
34 * to check it.
35 *
36 * @warning On some platforms, QColorDialog is used to perform the color
37 * picking. This might mix up the default button setting of the parent dialog.
38 * Workaround: If using default buttons in a parent dialog, reimplement
39 * <tt>QWidget::setVisible()</tt> in this parent dialog: Call the
40 * parent’s class implementation, and <em>after</em> that, call
41 * <tt>QPushButton::setDefault(true)</tt> on the default button. */
42class ScreenColorPicker : public QWidget
43{
45
46public:
47 explicit ScreenColorPicker(QWidget *parent);
48 virtual ~ScreenColorPicker() override;
49 [[nodiscard]] bool isAvailable();
50
51public Q_SLOTS:
52 void startPicking(quint8 previousColorRed, quint8 previousColorGreen, quint8 previousColorBlue);
53
55 /** @brief A new color.
56 *
57 * Emitted when the user has clicked on the screen to select a new color.
58 *
59 * @note On some platforms, furthermore this signal is also emitted while
60 * the user hovers over the screen with the mouse. Than, if the user
61 * cancels with the ESC key, a new signal is emitted with the old color
62 * passed originally to @ref startPicking.
63 *
64 * @param red The <em>red</em> component of the new color.
65 * Range: <tt>[0, 255]</tt>
66 * @param green Same for green.
67 * @param blue Same for blue.
68 *
69 * @internal
70 *
71 * @note This signal uses integers with the range <tt>[0, 255]</tt> as
72 * return values because this is the maximum precision of the underlying
73 * implementation: The QColorDialog implementation rounds on this
74 * precision when the user pushes the ESC key, even if the previous
75 * value was more exact. */
76 // Choosing thre “double” values as return type, as it makes clear
77 // what data type returns and as “Portal” actually provides
78 // double-precision in its return values.
79 void newColor(double red, double green, double blue);
80
81private:
82 /** @internal @brief Only for unit tests. */
83 friend class TestScreenColorPicker;
84
85 void pickWithPortal();
86 [[nodiscard]] static bool hasPortalSupport();
87 void initializeQColorDialogSupport();
88 [[nodiscard]] static bool queryPortalSupport();
89 [[nodiscard]] static QString translateViaQColorDialog(const char *sourceText);
90 /** @brief If on the current platform there is support for
91 * QColorDialog-based screen color picking.
92 *
93 * Might hold an empty value if @ref initializeQColorDialogSupport has
94 * never been called.
95 *
96 * @warning The declaration as <tt>static in‍line</tt> can be problematic:
97 * At least when linking on MSVC against a shared/static library,
98 * apparently there are two instances of this variable: One that is used
99 * within the shared/dynamic library and another one that is used within
100 * the executable that links against this library. While on GCC and Clang
101 * this does not happen, maybe this behaviour is implementation-defined.
102 * And we do not want to rely on implementation-defined behaviour. However,
103 * because the variable is <tt>private</tt>, this won't make any problems
104 * under normal circumstances, because it's inaccessible anyway. Only when
105 * doing a whitebox test and bypass the private access modifier via the
106 * @ref ScreenColorPicker::TestScreenColorPicker "friend declaration" for
107 * unit tests, you might see the wrong variable and consequently possibly
108 * the wrong value. Therefore, unit tests should only access this variable
109 * when building against the static library. */
110 static inline std::optional<bool> m_hasQColorDialogSupport = std::nullopt;
111 /** @brief The hidden QColorDialog widget (if any).
112 *
113 * @sa @ref initializeQColorDialogSupport */
114 QPointer<QColorDialog> m_qColorDialog;
115 /** @brief The screen-color-picker button of the hidden QColorDialog widget
116 * (if any).
117 *
118 * @sa @ref initializeQColorDialogSupport */
119 QPointer<QPushButton> m_qColorDialogScreenButton;
120
121private Q_SLOTS:
122 void getPortalResponse(uint exitCode, const QVariantMap &responseArguments);
123};
124
125} // namespace PerceptualColor
126
127#endif // SCREENCOLORPICKER
The namespace of this library.
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
Q_SLOTSQ_SLOTS
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:20:36 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.