Kirigami2

colorutils.h
1 /*
2  * SPDX-FileCopyrightText: 2020 Carson Black <[email protected]>
3  *
4  * SPDX-License-Identifier: LGPL-2.0-or-later
5  */
6 
7 #pragma once
8 
9 #include <QColor>
10 #include <QJSValue>
11 #include <QObject>
12 #include <QQuickItem>
13 
14 /**
15  * Utilities for processing items to obtain colors and information useful for
16  * UIs that need to adjust to variable elements.
17  */
18 class ColorUtils : public QObject
19 {
20  Q_OBJECT
21 public:
22  /**
23  * Describes the contrast of an item.
24  */
25  enum Brightness {
26  Dark, /**< The item is dark and requires a light foreground color to achieve readable contrast. */
27  Light, /**< The item is light and requires a dark foreground color to achieve readable contrast. */
28  };
30 
31  explicit ColorUtils(QObject *parent = nullptr);
32 
33  /**
34  * Returns whether a color is bright or dark.
35  *
36  * @code{.qml}
37  * import QtQuick 2.0
38  * import org.kde.kirigami 2.12 as Kirigami
39  *
40  * Kirigami.Heading {
41  * text: {
42  * if (Kirigami.ColorUtils.brightnessForColor("pink") == Kirigami.ColorUtils.Light) {
43  * return "The color is light"
44  * } else {
45  * return "The color is dark"
46  * }
47  * }
48  * }
49  * @endcode
50  *
51  * @since 5.69
52  * @since org.kde.kirigami 2.12
53  */
55 
56  /**
57  * Same Algorithm as brightnessForColor but returns a 0 to 1 value for an
58  * estimate of the equivalent gray light value (luma).
59  * 0 as full black, 1 as full white and 0.5 equivalent to a 50% gray.
60  *
61  * @since 5.81
62  * @since org.kde.kirigami 2.16
63  */
64  Q_INVOKABLE qreal grayForColor(const QColor &color);
65 
66  /**
67  * Returns the result of overlaying the foreground color on the background
68  * color.
69  *
70  * @param foreground The color to overlay on the background.
71  *
72  * @param background The color to overlay the foreground on.
73  *
74  * @code{.qml}
75  * import QtQuick 2.0
76  * import org.kde.kirigami 2.12 as Kirigami
77  *
78  * Rectangle {
79  * color: Kirigami.ColorUtils.alphaBlend(Qt.rgba(0, 0, 0, 0.5), Qt.rgba(1, 1, 1, 1))
80  * }
81  * @endcode
82  *
83  * @since 5.69
84  * @since org.kde.kirigami 2.12
85  */
86  Q_INVOKABLE QColor alphaBlend(const QColor &foreground, const QColor &background);
87 
88  /**
89  * Returns a linearly interpolated color between color one and color two.
90  *
91  * @param one The color to linearly interpolate from.
92  *
93  * @param two The color to linearly interpolate to.
94  *
95  * @param balance The balance between the two colors. 0.0 will return the
96  * first color, 1.0 will return the second color. Values beyond these bounds
97  * are valid, and will result in extrapolation.
98  *
99  * @code{.qml}
100  * import QtQuick 2.0
101  * import org.kde.kirigami 2.12 as Kirigami
102  *
103  * Rectangle {
104  * color: Kirigami.ColorUtils.linearInterpolation("black", "white", 0.5)
105  * }
106  * @endcode
107  *
108  * @since 5.69
109  * @since org.kde.kirigami 2.12
110  */
111  Q_INVOKABLE QColor linearInterpolation(const QColor &one, const QColor &two, double balance);
112 
113  /**
114  * Increases or decreases the properties of `color` by fixed amounts.
115  *
116  * @param color The color to adjust.
117  *
118  * @param adjustments The adjustments to apply to the color.
119  *
120  * @note `value` and `lightness` are aliases for the same value.
121  *
122  * @code{.js}
123  * {
124  * red: null, // Range: -255 to 255
125  * green: null, // Range: -255 to 255
126  * blue: null, // Range: -255 to 255
127  * hue: null, // Range: -360 to 360
128  * saturation: null, // Range: -255 to 255
129  * value: null // Range: -255 to 255
130  * lightness: null, // Range: -255 to 255
131  * alpha: null, // Range: -255 to 255
132  * }
133  * @endcode
134  *
135  * @warning It is an error to adjust both RGB and HSL properties.
136  *
137  * @since 5.69
138  * @since org.kde.kirigami 2.12
139  */
140  Q_INVOKABLE QColor adjustColor(const QColor &color, const QJSValue &adjustments);
141 
142  /**
143  * Smoothly scales colors.
144  *
145  * @param color The color to adjust.
146  *
147  * @param adjustments The adjustments to apply to the color. Each value must
148  * be between `-100.0` and `100.0`. This indicates how far the property should
149  * be scaled from its original to the maximum if positive or to the minimum if
150  * negative.
151  *
152  * @note `value` and `lightness` are aliases for the same value.
153  *
154  * @code{.js}
155  * {
156  * red: null
157  * green: null
158  * blue: null
159  * saturation: null
160  * lightness: null
161  * value: null
162  * alpha: null
163  * }
164  * @endcode
165  *
166  * @warning It is an error to scale both RGB and HSL properties.
167  *
168  * @since 5.69
169  * @since org.kde.kirigami 2.12
170  */
171  Q_INVOKABLE QColor scaleColor(const QColor &color, const QJSValue &adjustments);
172 
173  /**
174  * Tint a color using a separate alpha value.
175  *
176  * This does the same as Qt.tint() except that rather than using the tint
177  * color's alpha value, it uses a separate value that gets multiplied with
178  * the tint color's alpha. This avoids needing to create a new color just to
179  * adjust an alpha value.
180  *
181  * \param targetColor The color to tint.
182  * \param tintColor The color to tint with.
183  * \param alpha The amount of tinting to apply.
184  *
185  * \return The tinted color.
186  *
187  * \sa Qt.tint()
188  */
189  Q_INVOKABLE QColor tintWithAlpha(const QColor &targetColor, const QColor &tintColor, double alpha);
190 
191  /**
192  * Returns the CIELAB chroma of the given color.
193  *
194  * CIELAB chroma may give a better quantification of how vibrant a color is compared to HSV saturation.
195  *
196  * \sa https://en.wikipedia.org/wiki/Colorfulness
197  * \sa https://en.wikipedia.org/wiki/CIELAB_color_space
198  */
199  Q_INVOKABLE static qreal chroma(const QColor &color);
200 
201  struct XYZColor {
202  qreal x = 0;
203  qreal y = 0;
204  qreal z = 0;
205  };
206 
207  struct LabColor {
208  qreal l = 0;
209  qreal a = 0;
210  qreal b = 0;
211  };
212 
213  // Not for QML, returns the comvertion from srgb of a QColor and XYZ colorspace
214  static ColorUtils::XYZColor colorToXYZ(const QColor &color);
215 
216  // Not for QML, returns the comvertion from srgb of a QColor and Lab colorspace
217  static ColorUtils::LabColor colorToLab(const QColor &color);
218 
219  static qreal luminance(const QColor &color);
220 };
Q_OBJECTQ_OBJECT
Q_INVOKABLE qreal grayForColor(const QColor &color)
Same Algorithm as brightnessForColor but returns a 0 to 1 value for an estimate of the equivalent gra...
Definition: colorutils.cpp:29
Q_ENUM(...)
@ Light
The item is light and requires a dark foreground color to achieve readable contrast.
Definition: colorutils.h:27
Q_INVOKABLE ColorUtils::Brightness brightnessForColor(const QColor &color)
Returns whether a color is bright or dark.
Definition: colorutils.cpp:20
Q_INVOKABLE QColor alphaBlend(const QColor &foreground, const QColor &background)
Returns the result of overlaying the foreground color on the background color.
Definition: colorutils.cpp:34
@ Dark
The item is dark and requires a light foreground color to achieve readable contrast.
Definition: colorutils.h:26
Utilities for processing items to obtain colors and information useful for UIs that need to adjust to...
Definition: colorutils.h:18
Q_INVOKABLE QColor adjustColor(const QColor &color, const QJSValue &adjustments)
Increases or decreases the properties of color by fixed amounts.
Definition: colorutils.cpp:134
Q_INVOKABLE QColor scaleColor(const QColor &color, const QJSValue &adjustments)
Smoothly scales colors.
Definition: colorutils.cpp:180
Q_INVOKABLEQ_INVOKABLE
static Q_INVOKABLE qreal chroma(const QColor &color)
Returns the CIELAB chroma of the given color.
Definition: colorutils.cpp:301
Q_INVOKABLE QColor tintWithAlpha(const QColor &targetColor, const QColor &tintColor, double alpha)
Tint a color using a separate alpha value.
Definition: colorutils.cpp:227
Q_INVOKABLE QColor linearInterpolation(const QColor &one, const QColor &two, double balance)
Returns a linearly interpolated color between color one and color two.
Definition: colorutils.cpp:60
Brightness
Describes the contrast of an item.
Definition: colorutils.h:25
QObject * parent() const const
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Jan 29 2023 04:11:03 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.