MauiKit Controls

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

KDE's Doxygen guidelines are available online.