Kirigami2

platformtheme.h
1/*
2 * SPDX-FileCopyrightText: 2017 by Marco Martin <mart@kde.org>
3 *
4 * SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6
7#ifndef KIRIGAMI_PLATFORMTHEME_H
8#define KIRIGAMI_PLATFORMTHEME_H
9
10#include <QColor>
11#include <QIcon>
12#include <QObject>
13#include <QPalette>
14#include <QQuickItem>
15#include <qqmlregistration.h>
16
17#include "kirigamiplatform_export.h"
18
19namespace Kirigami
20{
21namespace Platform
22{
23class PlatformThemeData;
24class PlatformThemePrivate;
25
26/**
27 * @class PlatformTheme platformtheme.h <Kirigami/PlatformTheme>
28 *
29 * This class is the base for color management in Kirigami,
30 * different platforms can reimplement this class to integrate with
31 * system platform colors of a given platform
32 */
33class KIRIGAMIPLATFORM_EXPORT PlatformTheme : public QObject
34{
35 Q_OBJECT
36 QML_NAMED_ELEMENT(Theme)
38 QML_UNCREATABLE("Attached Property")
39
40 /**
41 * This enumeration describes the color set for which a color is being selected.
42 *
43 * Color sets define a color "environment", suitable for drawing all parts of a
44 * given region. Colors from different sets should not be combined.
45 */
46 Q_PROPERTY(ColorSet colorSet READ colorSet WRITE setColorSet NOTIFY colorSetChanged FINAL)
47
48 /**
49 * This enumeration describes the color group used to generate the colors.
50 * The enum value is based upon QPalette::ColorGroup and has the same values.
51 * It's redefined here in order to make it work with QML.
52 * @since 4.43
53 */
54 Q_PROPERTY(ColorGroup colorGroup READ colorGroup WRITE setColorGroup NOTIFY colorGroupChanged FINAL)
55
56 /**
57 * If true, the colorSet will be inherited from the colorset of a theme of one
58 * of the ancestor items
59 * default: true
60 */
61 Q_PROPERTY(bool inherit READ inherit WRITE setInherit NOTIFY inheritChanged FINAL)
62
63 // foreground colors
64 /**
65 * Color for normal foregrounds, usually text, but not limited to it,
66 * anything that should be painted with a clear contrast should use this color
67 */
68 Q_PROPERTY(QColor textColor READ textColor WRITE setCustomTextColor RESET setCustomTextColor NOTIFY colorsChanged FINAL)
69
70 /**
71 * Foreground color for disabled areas, usually a mid-gray
72 */
73 Q_PROPERTY(QColor disabledTextColor READ disabledTextColor WRITE setCustomDisabledTextColor RESET setCustomDisabledTextColor NOTIFY colorsChanged FINAL)
74
75 /**
76 * Color for text that has been highlighted, often is a light color while normal text is dark
77 */
78 Q_PROPERTY(
79 QColor highlightedTextColor READ highlightedTextColor WRITE setCustomHighlightedTextColor RESET setCustomHighlightedTextColor NOTIFY colorsChanged)
80
81 /**
82 * Foreground for areas that are active or requesting attention
83 */
84 Q_PROPERTY(QColor activeTextColor READ activeTextColor WRITE setCustomActiveTextColor RESET setCustomActiveTextColor NOTIFY colorsChanged FINAL)
85
86 /**
87 * Color for links
88 */
89 Q_PROPERTY(QColor linkColor READ linkColor WRITE setCustomLinkColor RESET setCustomLinkColor NOTIFY colorsChanged FINAL)
90
91 /**
92 * Color for visited links, usually a bit darker than linkColor
93 */
94 Q_PROPERTY(QColor visitedLinkColor READ visitedLinkColor WRITE setCustomVisitedLinkColor RESET setCustomVisitedLinkColor NOTIFY colorsChanged FINAL)
95
96 /**
97 * Foreground color for negative areas, such as critical error text
98 */
99 Q_PROPERTY(QColor negativeTextColor READ negativeTextColor WRITE setCustomNegativeTextColor RESET setCustomNegativeTextColor NOTIFY colorsChanged FINAL)
100
101 /**
102 * Foreground color for neutral areas, such as warning texts (but not critical)
103 */
104 Q_PROPERTY(QColor neutralTextColor READ neutralTextColor WRITE setCustomNeutralTextColor RESET setCustomNeutralTextColor NOTIFY colorsChanged FINAL)
105
106 /**
107 * Success messages, trusted content
108 */
109 Q_PROPERTY(QColor positiveTextColor READ positiveTextColor WRITE setCustomPositiveTextColor RESET setCustomPositiveTextColor NOTIFY colorsChanged FINAL)
110
111 // background colors
112 /**
113 * The generic background color
114 */
115 Q_PROPERTY(QColor backgroundColor READ backgroundColor WRITE setCustomBackgroundColor RESET setCustomBackgroundColor NOTIFY colorsChanged FINAL)
116
117 /**
118 * The generic background color
119 * Alternate background; for example, for use in lists.
120 * This color may be the same as BackgroundNormal,
121 * especially in sets other than View and Window.
122 */
123 Q_PROPERTY(QColor alternateBackgroundColor READ alternateBackgroundColor WRITE setCustomAlternateBackgroundColor RESET setCustomAlternateBackgroundColor
124 NOTIFY colorsChanged)
125
126 /**
127 * The background color for selected areas
128 */
129 Q_PROPERTY(QColor highlightColor READ highlightColor WRITE setCustomHighlightColor RESET setCustomHighlightColor NOTIFY colorsChanged FINAL)
130
131 /**
132 * Background for areas that are active or requesting attention
133 */
134 Q_PROPERTY(
135 QColor activeBackgroundColor READ activeBackgroundColor WRITE setCustomActiveBackgroundColor RESET setCustomActiveBackgroundColor NOTIFY colorsChanged)
136
137 /**
138 * Background color for links
139 */
140 Q_PROPERTY(
141 QColor linkBackgroundColor READ linkBackgroundColor WRITE setCustomLinkBackgroundColor RESET setCustomLinkBackgroundColor NOTIFY colorsChanged FINAL)
142
143 /**
144 * Background color for visited links, usually a bit darker than linkBackgroundColor
145 */
146 Q_PROPERTY(QColor visitedLinkBackgroundColor READ visitedLinkBackgroundColor WRITE setCustomVisitedLinkBackgroundColor RESET
147 setCustomVisitedLinkBackgroundColor NOTIFY colorsChanged)
148
149 /**
150 * Background color for negative areas, such as critical errors and destructive actions
151 */
152 Q_PROPERTY(QColor negativeBackgroundColor READ negativeBackgroundColor WRITE setCustomNegativeBackgroundColor RESET setCustomNegativeBackgroundColor NOTIFY
153 colorsChanged)
154
155 /**
156 * Background color for neutral areas, such as warnings (but not critical)
157 */
158 Q_PROPERTY(QColor neutralBackgroundColor READ neutralBackgroundColor WRITE setCustomNeutralBackgroundColor RESET setCustomNeutralBackgroundColor NOTIFY
159 colorsChanged)
160
161 /**
162 * Background color for positive areas, such as success messages and trusted content
163 */
164 Q_PROPERTY(QColor positiveBackgroundColor READ positiveBackgroundColor WRITE setCustomPositiveBackgroundColor RESET setCustomPositiveBackgroundColor NOTIFY
165 colorsChanged)
166
167 // decoration colors
168 /**
169 * A decoration color that indicates active focus
170 */
171 Q_PROPERTY(QColor focusColor READ focusColor WRITE setCustomFocusColor RESET setCustomFocusColor NOTIFY colorsChanged FINAL)
172
173 /**
174 * A decoration color that indicates mouse hovering
175 */
176 Q_PROPERTY(QColor hoverColor READ hoverColor WRITE setCustomHoverColor RESET setCustomHoverColor NOTIFY colorsChanged FINAL)
177
178 /**
179 * Hint for item views to actually make use of the alternate background color feature
180 */
181 Q_PROPERTY(
182 bool useAlternateBackgroundColor READ useAlternateBackgroundColor WRITE setUseAlternateBackgroundColor NOTIFY useAlternateBackgroundColorChanged FINAL)
183
184 // font and palette
185 Q_PROPERTY(QFont defaultFont READ defaultFont NOTIFY defaultFontChanged FINAL)
186
187 // small font
188 Q_PROPERTY(QFont smallFont READ smallFont NOTIFY smallFontChanged FINAL)
189
190 // Active palette
191 Q_PROPERTY(QPalette palette READ palette NOTIFY paletteChanged FINAL)
192
193 // Frame contrast value, usually used for separators and outlines
194 // Value is between 0.0 and 1.0
195 Q_PROPERTY(qreal frameContrast READ frameContrast CONSTANT FINAL)
196
197 // Returns half of the frameContrast value; used by Separator.Weight.Light
198 // Value is between 0.0 and 1.0
199 Q_PROPERTY(qreal lightFrameContrast READ lightFrameContrast CONSTANT FINAL)
200
201public:
202 enum ColorSet {
203 View = 0, /** Color set for item views, usually the lightest of all */
204 Window, /** Default Color set for windows and "chrome" areas */
205 Button, /** Color set used by buttons */
206 Selection, /** Color set used by selectged areas */
207 Tooltip, /** Color set used by tooltips */
208 Complementary, /** Color set meant to be complementary to Window: usually is a dark theme for light themes */
209 Header, /** Color set to be used by heading areas of applications, such as toolbars */
210
211 ColorSetCount, // Number of items in this enum, this should always be the last item.
212 };
213 Q_ENUM(ColorSet)
214
215 enum ColorGroup {
216 Disabled = QPalette::Disabled,
217 Active = QPalette::Active,
218 Inactive = QPalette::Inactive,
219 Normal = QPalette::Normal,
220
221 ColorGroupCount, // Number of items in this enum, this should always be the last item.
222 };
223 Q_ENUM(ColorGroup)
224
225 explicit PlatformTheme(QObject *parent = nullptr);
226 ~PlatformTheme() override;
227
228 void setColorSet(PlatformTheme::ColorSet);
229 PlatformTheme::ColorSet colorSet() const;
230
231 void setColorGroup(PlatformTheme::ColorGroup);
232 PlatformTheme::ColorGroup colorGroup() const;
233
234 bool inherit() const;
235 void setInherit(bool inherit);
236
237 // foreground colors
238 QColor textColor() const;
239 QColor disabledTextColor() const;
240 QColor highlightedTextColor() const;
241 QColor activeTextColor() const;
242 QColor linkColor() const;
243 QColor visitedLinkColor() const;
244 QColor negativeTextColor() const;
245 QColor neutralTextColor() const;
246 QColor positiveTextColor() const;
247
248 // background colors
249 QColor backgroundColor() const;
250 QColor alternateBackgroundColor() const;
251 QColor highlightColor() const;
252 QColor activeBackgroundColor() const;
253 QColor linkBackgroundColor() const;
254 QColor visitedLinkBackgroundColor() const;
255 QColor negativeBackgroundColor() const;
256 QColor neutralBackgroundColor() const;
257 QColor positiveBackgroundColor() const;
258
259 // decoration colors
260 QColor focusColor() const;
261 QColor hoverColor() const;
262
263 QFont defaultFont() const;
264 QFont smallFont() const;
265
266 // this may is used by the desktop QQC2 to set the styleoption palettes
267 QPalette palette() const;
268
269 qreal frameContrast() const;
270 qreal lightFrameContrast() const;
271
272 // this will be used by desktopicon to fetch icons with KIconLoader
273 virtual Q_INVOKABLE QIcon iconFromTheme(const QString &name, const QColor &customColor = Qt::transparent);
274
275 bool supportsIconColoring() const;
276
277 // foreground colors
278 void setCustomTextColor(const QColor &color = QColor());
279 void setCustomDisabledTextColor(const QColor &color = QColor());
280 void setCustomHighlightedTextColor(const QColor &color = QColor());
281 void setCustomActiveTextColor(const QColor &color = QColor());
282 void setCustomLinkColor(const QColor &color = QColor());
283 void setCustomVisitedLinkColor(const QColor &color = QColor());
284 void setCustomNegativeTextColor(const QColor &color = QColor());
285 void setCustomNeutralTextColor(const QColor &color = QColor());
286 void setCustomPositiveTextColor(const QColor &color = QColor());
287 // background colors
288 void setCustomBackgroundColor(const QColor &color = QColor());
289 void setCustomAlternateBackgroundColor(const QColor &color = QColor());
290 void setCustomHighlightColor(const QColor &color = QColor());
291 void setCustomActiveBackgroundColor(const QColor &color = QColor());
292 void setCustomLinkBackgroundColor(const QColor &color = QColor());
293 void setCustomVisitedLinkBackgroundColor(const QColor &color = QColor());
294 void setCustomNegativeBackgroundColor(const QColor &color = QColor());
295 void setCustomNeutralBackgroundColor(const QColor &color = QColor());
296 void setCustomPositiveBackgroundColor(const QColor &color = QColor());
297 // decoration colors
298 void setCustomFocusColor(const QColor &color = QColor());
299 void setCustomHoverColor(const QColor &color = QColor());
300
301 bool useAlternateBackgroundColor() const;
302 void setUseAlternateBackgroundColor(bool alternate);
303
304 // QML attached property
305 static PlatformTheme *qmlAttachedProperties(QObject *object);
306
307Q_SIGNALS:
308 void colorsChanged();
309 void defaultFontChanged(const QFont &font);
310 void smallFontChanged(const QFont &font);
311 void colorSetChanged(Kirigami::Platform::PlatformTheme::ColorSet colorSet);
312 void colorGroupChanged(Kirigami::Platform::PlatformTheme::ColorGroup colorGroup);
313 void paletteChanged(const QPalette &pal);
314 void inheritChanged(bool inherit);
315 void useAlternateBackgroundColorChanged(bool alternate);
316
317protected:
318 // Setters, not accessible from QML but from implementations
319 void setSupportsIconColoring(bool support);
320
321 // foreground colors
322 void setTextColor(const QColor &color);
323 void setDisabledTextColor(const QColor &color);
324 void setHighlightedTextColor(const QColor &color);
325 void setActiveTextColor(const QColor &color);
326 void setLinkColor(const QColor &color);
327 void setVisitedLinkColor(const QColor &color);
328 void setNegativeTextColor(const QColor &color);
329 void setNeutralTextColor(const QColor &color);
330 void setPositiveTextColor(const QColor &color);
331
332 // background colors
333 void setBackgroundColor(const QColor &color);
334 void setAlternateBackgroundColor(const QColor &color);
335 void setHighlightColor(const QColor &color);
336 void setActiveBackgroundColor(const QColor &color);
337 void setLinkBackgroundColor(const QColor &color);
338 void setVisitedLinkBackgroundColor(const QColor &color);
339 void setNegativeBackgroundColor(const QColor &color);
340 void setNeutralBackgroundColor(const QColor &color);
341 void setPositiveBackgroundColor(const QColor &color);
342
343 // decoration colors
344 void setFocusColor(const QColor &color);
345 void setHoverColor(const QColor &color);
346
347 void setDefaultFont(const QFont &defaultFont);
348 void setSmallFont(const QFont &smallFont);
349
350 bool event(QEvent *event) override;
351
352private:
353 KIRIGAMIPLATFORM_NO_EXPORT void update();
354 KIRIGAMIPLATFORM_NO_EXPORT void updateChildren(QObject *item);
355 KIRIGAMIPLATFORM_NO_EXPORT void emitSignals();
356 KIRIGAMIPLATFORM_NO_EXPORT void emitColorChanged();
357 KIRIGAMIPLATFORM_NO_EXPORT QObject *determineParent(QObject *object);
358
359 PlatformThemePrivate *d;
360 friend class PlatformThemePrivate;
361 friend class PlatformThemeData;
362};
363
364namespace PlatformThemeEvents
365{
366// To avoid the overhead of Qt's signal/slot connections, we use custom events
367// to communicate with subclasses. This way, we can indicate what actually
368// changed without needing to add new virtual functions to PlatformTheme which
369// would break binary compatibility.
370//
371// To handle these events in your subclass, override QObject::event() and check
372// if you receive one of these events, then do what is needed. Finally, make
373// sure to call PlatformTheme::event() since that will also do some processing
374// of these events.
375
376template<typename T>
377class KIRIGAMIPLATFORM_EXPORT PropertyChangedEvent : public QEvent
378{
379public:
380 PropertyChangedEvent(PlatformTheme *theme, const T &previous, const T &current)
381 : QEvent(PropertyChangedEvent<T>::type)
382 , sender(theme)
383 , oldValue(previous)
384 , newValue(current)
385 {
386 }
387
388 PlatformTheme *sender;
389 T oldValue;
390 T newValue;
391
392 static QEvent::Type type;
393};
394
395using DataChangedEvent = PropertyChangedEvent<std::shared_ptr<PlatformThemeData>>;
396using ColorSetChangedEvent = PropertyChangedEvent<PlatformTheme::ColorSet>;
397using ColorGroupChangedEvent = PropertyChangedEvent<PlatformTheme::ColorGroup>;
398using ColorChangedEvent = PropertyChangedEvent<QColor>;
399using FontChangedEvent = PropertyChangedEvent<QFont>;
400
401}
402
403}
404} // namespace Kirigami
405
406#endif // PLATFORMTHEME_H
This class is the base for color management in Kirigami, different platforms can reimplement this cla...
@ Tooltip
Color set used by selectged areas.
@ Button
Default Color set for windows and "chrome" areas.
@ Header
Color set meant to be complementary to Window: usually is a dark theme for light themes.
@ Window
Color set for item views, usually the lightest of all.
@ Selection
Color set used by buttons.
@ ColorSetCount
Color set to be used by heading areas of applications, such as toolbars.
@ Complementary
Color set used by tooltips.
Type type(const QSqlDatabase &db)
transparent
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:18:46 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.