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 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();
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
This class is the base for color management in Kirigami, different platforms can reimplement this cla...
Definition: platformtheme.h:30
Color set used by buttons.
Definition: icon.h:18
Color set meant to be complementary to Window: usually is a dark theme for light themes.
Color set used by tooltips.
Color set to be used by heading areas of applications, such as toolbars.
Color set used by selectged areas.
Color set for item views, usually the lightest of all.
transparent
Default Color set for windows and "chrome" areas.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Jun 20 2021 22:38:04 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.