Kirigami2

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

KDE's Doxygen guidelines are available online.