MauiKit Controls

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