Kirigami2

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

KDE's Doxygen guidelines are available online.