1/*
2 * SPDX-FileCopyrightText: 2017 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 * \qmltype Theme
28 * \inqmlmodule org.kde.kirigami.platform
29 *
30 * \nativetype Kirigami::Platform::PlatformTheme
31 *
32 * \brief This class is the base for color management in Kirigami,
33 * different platforms can reimplement this class to integrate
34 * with system platform colors of a given platform.
35 */
36
37/*!
38 * \class Kirigami::Platform::PlatformTheme
39 * \inheaderfile Kirigami/Platform/PlatformTheme
40 * \inmodule KirigamiPlatform
41 *
42 * \brief This class is the base for color management in Kirigami,
43 * different platforms can reimplement this class to integrate with
44 * system platform colors of a given platform.
45 */
46class KIRIGAMIPLATFORM_EXPORT PlatformTheme : public QObject
47{
48 Q_OBJECT
49 QML_NAMED_ELEMENT(Theme)
50 QML_ATTACHED(Kirigami::Platform::PlatformTheme)
51 QML_UNCREATABLE("Attached Property")
52
53 /*!
54 * \qmlattachedproperty enumeration Theme::colorSet
55 * This enumeration describes the color set for which a color is being selected.
56 *
57 * Color sets define a color "environment", suitable for drawing all parts of a
58 * given region. Colors from different sets should not be combined.
59 */
60 /*!
61 * \property Kirigami::Platform::PlatformTheme::colorSet
62 * This enumeration describes the color set for which a color is being selected.
63 *
64 * Color sets define a color "environment", suitable for drawing all parts of a
65 * given region. Colors from different sets should not be combined.
66 */
67 Q_PROPERTY(ColorSet colorSet READ colorSet WRITE setColorSet NOTIFY colorSetChanged FINAL)
68
69 /*!
70 * \qmlattachedproperty enumeration Theme::colorGroup
71 *
72 * This enumeration describes the color group used to generate the colors.
73 * The enum value is based upon QPalette::ColorGroup and has the same values.
74 * It's redefined here in order to make it work with QML.
75 * \since 4.43
76 */
77 /*!
78 * \property Kirigami::Platform::PlatformTheme::colorGroup
79 *
80 * This enumeration describes the color group used to generate the colors.
81 * The enum value is based upon QPalette::ColorGroup and has the same values.
82 * It's redefined here in order to make it work with QML.
83 * \since 4.43
84 */
85 Q_PROPERTY(ColorGroup colorGroup READ colorGroup WRITE setColorGroup NOTIFY colorGroupChanged FINAL)
86
87 /*!
88 * \qmlattachedproperty bool Theme::inherit
89 *
90 * If true, the colorSet will be inherited from the colorset of a theme of one
91 * of the ancestor items.
92 *
93 * default: true
94 */
95 /*!
96 * \property Kirigami::Platform::PlatformTheme::inherit
97 *
98 * If true, the colorSet will be inherited from the colorset of a theme of one
99 * of the ancestor items.
100 *
101 * default: true
102 */
103 Q_PROPERTY(bool inherit READ inherit WRITE setInherit NOTIFY inheritChanged FINAL)
104
105 // foreground colors
106 /*!
107 * \qmlattachedproperty color Theme::textColor
108 * Color for normal foregrounds, usually text, but not limited to it,
109 * anything that should be painted with a clear contrast should use this color.
110 */
111 /*!
112 * \property Kirigami::Platform::PlatformTheme::textColor
113 * Color for normal foregrounds, usually text, but not limited to it,
114 * anything that should be painted with a clear contrast should use this color.
115 */
116 Q_PROPERTY(QColor textColor READ textColor WRITE setCustomTextColor RESET setCustomTextColor NOTIFY colorsChanged FINAL)
117
118 /*!
119 * \qmlattachedproperty color Theme::disabledTextColor
120 *
121 * Foreground color for disabled areas, usually a mid-gray.
122 * \note Depending on the implementation, the color used for this property may not be
123 * based on the disabled palette. For example, for the Plasma implementation,
124 * "Inactive Text Color" of the active palette is used.
125 */
126 /*!
127 * \property Kirigami::Platform::PlatformTheme::disabledTextColor
128 *
129 * Foreground color for disabled areas, usually a mid-gray.
130 * \note Depending on the implementation, the color used for this property may not be
131 * based on the disabled palette. For example, for the Plasma implementation,
132 * "Inactive Text Color" of the active palette is used.
133 */
134 Q_PROPERTY(QColor disabledTextColor READ disabledTextColor WRITE setCustomDisabledTextColor RESET setCustomDisabledTextColor NOTIFY colorsChanged FINAL)
135
136 /*!
137 * \qmlattachedproperty color Theme::highlightedTextColor
138 *
139 * Color for text that has been highlighted, often is a light color while normal text is dark.
140 */
141 /*!
142 * \property Kirigami::Platform::PlatformTheme::highlightedTextColor
143 *
144 * Color for text that has been highlighted, often is a light color while normal text is dark.
145 */
146 Q_PROPERTY(
147 QColor highlightedTextColor READ highlightedTextColor WRITE setCustomHighlightedTextColor RESET setCustomHighlightedTextColor NOTIFY colorsChanged)
148
149 /*!
150 * \qmlattachedproperty color Theme::activeTextColor
151 *
152 * Foreground for areas that are active or requesting attention.
153 */
154 /*!
155 * \property Kirigami::Platform::PlatformTheme::activeTextColor
156 *
157 * Foreground for areas that are active or requesting attention.
158 */
159 Q_PROPERTY(QColor activeTextColor READ activeTextColor WRITE setCustomActiveTextColor RESET setCustomActiveTextColor NOTIFY colorsChanged FINAL)
160
161 /*!
162 * \qmlattachedproperty color Theme::linkColor
163 *
164 * Color for links.
165 */
166 /*!
167 * \property Kirigami::Platform::PlatformTheme::linkColor
168 *
169 * Color for links.
170 */
171 Q_PROPERTY(QColor linkColor READ linkColor WRITE setCustomLinkColor RESET setCustomLinkColor NOTIFY colorsChanged FINAL)
172
173 /*!
174 * \qmlattachedproperty color Theme::visitedLinkColor
175 *
176 * Color for visited links, usually a bit darker than linkColor.
177 */
178 /*!
179 * \property Kirigami::Platform::PlatformTheme::visitedLinkColor
180 *
181 * Color for visited links, usually a bit darker than linkColor.
182 */
183 Q_PROPERTY(QColor visitedLinkColor READ visitedLinkColor WRITE setCustomVisitedLinkColor RESET setCustomVisitedLinkColor NOTIFY colorsChanged FINAL)
184
185 /*!
186 * \qmlattachedproperty color Theme::negativeTextColor
187 *
188 * Foreground color for negative areas, such as critical error text.
189 */
190 /*!
191 * \property Kirigami::Platform::PlatformTheme::negativeTextColor
192 *
193 * Foreground color for negative areas, such as critical error text.
194 */
195 Q_PROPERTY(QColor negativeTextColor READ negativeTextColor WRITE setCustomNegativeTextColor RESET setCustomNegativeTextColor NOTIFY colorsChanged FINAL)
196
197 /*!
198 * \qmlattachedproperty color Theme::neutralTextColor
199 *
200 * Foreground color for neutral areas, such as warning texts (but not critical).
201 */
202 /*!
203 * \property Kirigami::Platform::PlatformTheme::neutralTextColor
204 *
205 * Foreground color for neutral areas, such as warning texts (but not critical).
206 */
207 Q_PROPERTY(QColor neutralTextColor READ neutralTextColor WRITE setCustomNeutralTextColor RESET setCustomNeutralTextColor NOTIFY colorsChanged FINAL)
208
209 /*!
210 * \qmlattachedproperty color Theme::positiveTextColor
211 *
212 * Success messages, trusted content.
213 */
214 /*!
215 * \property Kirigami::Platform::PlatformTheme::positiveTextColor
216 *
217 * Success messages, trusted content.
218 */
219 Q_PROPERTY(QColor positiveTextColor READ positiveTextColor WRITE setCustomPositiveTextColor RESET setCustomPositiveTextColor NOTIFY colorsChanged FINAL)
220
221 // background colors
222 /*!
223 * \qmlattachedproperty color Theme::backgroundColor
224 *
225 * The generic background color.
226 */
227 /*!
228 * \property Kirigami::Platform::PlatformTheme::backgroundColor
229 *
230 * The generic background color.
231 */
232 Q_PROPERTY(QColor backgroundColor READ backgroundColor WRITE setCustomBackgroundColor RESET setCustomBackgroundColor NOTIFY colorsChanged FINAL)
233
234 /*!
235 * \qmlattachedproperty color Theme::alternateBackgroundColor
236 *
237 * The generic background color.
238 *
239 * Alternate background; for example, for use in lists.
240 *
241 * This color may be the same as BackgroundNormal,
242 * especially in sets other than View and Window.
243 */
244 /*!
245 * \property Kirigami::Platform::PlatformTheme::alternateBackgroundColor
246 *
247 * The generic background color.
248 *
249 * Alternate background; for example, for use in lists.
250 *
251 * This color may be the same as BackgroundNormal,
252 * especially in sets other than View and Window.
253 */
254 Q_PROPERTY(QColor alternateBackgroundColor READ alternateBackgroundColor WRITE setCustomAlternateBackgroundColor RESET setCustomAlternateBackgroundColor
255 NOTIFY colorsChanged)
256
257 /*!
258 * \qmlattachedproperty color Theme::highlightColor
259 *
260 * The background color for selected areas.
261 */
262 /*!
263 * \property Kirigami::Platform::PlatformTheme::highlightColor
264 *
265 * The background color for selected areas.
266 */
267 Q_PROPERTY(QColor highlightColor READ highlightColor WRITE setCustomHighlightColor RESET setCustomHighlightColor NOTIFY colorsChanged FINAL)
268
269 /*!
270 * \qmlattachedproperty color Theme::activeBackgroundColor
271 *
272 * Background for areas that are active or requesting attention.
273 */
274 /*!
275 * \property Kirigami::Platform::PlatformTheme::activeBackgroundColor
276 *
277 * Background for areas that are active or requesting attention.
278 */
279 Q_PROPERTY(
280 QColor activeBackgroundColor READ activeBackgroundColor WRITE setCustomActiveBackgroundColor RESET setCustomActiveBackgroundColor NOTIFY colorsChanged)
281
282 /*!
283 * \qmlattachedproperty color Theme::linkBackgroundColor
284 *
285 * Background color for links.
286 */
287 /*!
288 * \property Kirigami::Platform::PlatformTheme::linkBackgroundColor
289 *
290 * Background color for links.
291 */
292 Q_PROPERTY(
293 QColor linkBackgroundColor READ linkBackgroundColor WRITE setCustomLinkBackgroundColor RESET setCustomLinkBackgroundColor NOTIFY colorsChanged FINAL)
294
295 /*!
296 * \qmlattachedproperty color Theme::visitedLinkBackgroundColor
297 *
298 * Background color for visited links, usually a bit darker than linkBackgroundColor.
299 */
300 /*!
301 * \property Kirigami::Platform::PlatformTheme::visitedLinkBackgroundColor
302 *
303 * Background color for visited links, usually a bit darker than linkBackgroundColor.
304 */
305 Q_PROPERTY(QColor visitedLinkBackgroundColor READ visitedLinkBackgroundColor WRITE setCustomVisitedLinkBackgroundColor RESET
306 setCustomVisitedLinkBackgroundColor NOTIFY colorsChanged)
307
308 /*!
309 * \qmlattachedproperty color Theme::negativeBackgroundColor
310 *
311 * Background color for negative areas, such as critical errors and destructive actions.
312 */
313 /*!
314 * \property Kirigami::Platform::PlatformTheme::negativeBackgroundColor
315 *
316 * Background color for negative areas, such as critical errors and destructive actions.
317 */
318 Q_PROPERTY(QColor negativeBackgroundColor READ negativeBackgroundColor WRITE setCustomNegativeBackgroundColor RESET setCustomNegativeBackgroundColor NOTIFY
319 colorsChanged)
320
321 /*!
322 * \qmlattachedproperty color Theme::neutralBackgroundColor
323 *
324 * Background color for neutral areas, such as warnings (but not critical).
325 */
326 /*!
327 * \property Kirigami::Platform::PlatformTheme::neutralBackgroundColor
328 *
329 * Background color for neutral areas, such as warnings (but not critical).
330 */
331 Q_PROPERTY(QColor neutralBackgroundColor READ neutralBackgroundColor WRITE setCustomNeutralBackgroundColor RESET setCustomNeutralBackgroundColor NOTIFY
332 colorsChanged)
333
334 /*!
335 * \qmlattachedproperty color Theme::positiveBackgroundColor
336 *
337 * Background color for positive areas, such as success messages and trusted content.
338 */
339 /*!
340 * \property Kirigami::Platform::PlatformTheme::positiveBackgroundColor
341 *
342 * Background color for positive areas, such as success messages and trusted content.
343 */
344 Q_PROPERTY(QColor positiveBackgroundColor READ positiveBackgroundColor WRITE setCustomPositiveBackgroundColor RESET setCustomPositiveBackgroundColor NOTIFY
345 colorsChanged)
346
347 // decoration colors
348 /*!
349 * \qmlattachedproperty color Theme::focusColor
350 *
351 * A decoration color that indicates active focus.
352 */
353 /*!
354 * \property Kirigami::Platform::PlatformTheme::focusColor
355 *
356 * A decoration color that indicates active focus.
357 */
358 Q_PROPERTY(QColor focusColor READ focusColor WRITE setCustomFocusColor RESET setCustomFocusColor NOTIFY colorsChanged FINAL)
359
360 /*!
361 * \qmlattachedproperty color Theme::hoverColor
362 *
363 * A decoration color that indicates mouse hovering.
364 */
365 /*!
366 * \property Kirigami::Platform::PlatformTheme::hoverColor
367 *
368 * A decoration color that indicates mouse hovering.
369 */
370 Q_PROPERTY(QColor hoverColor READ hoverColor WRITE setCustomHoverColor RESET setCustomHoverColor NOTIFY colorsChanged FINAL)
371
372 /*!
373 * \qmlattachedproperty color Theme::useAlternateBackgroundColor
374 *
375 * Hint for item views to actually make use of the alternate background color feature.
376 */
377 /*!
378 * \property Kirigami::Platform::PlatformTheme::useAlternateBackgroundColor
379 *
380 * Hint for item views to actually make use of the alternate background color feature.
381 */
382 Q_PROPERTY(
383 bool useAlternateBackgroundColor READ useAlternateBackgroundColor WRITE setUseAlternateBackgroundColor NOTIFY useAlternateBackgroundColorChanged FINAL)
384
385 /*!
386 * \qmlattachedproperty font Theme::defaultFont
387 *
388 * The default font.
389 */
390 /*!
391 * \property Kirigami::Platform::PlatformTheme::defaultFont
392 *
393 * The default font.
394 */
395 Q_PROPERTY(QFont defaultFont READ defaultFont NOTIFY defaultFontChanged FINAL)
396
397 /*!
398 * \qmlattachedproperty font Theme::smallFont
399 *
400 * Small font.
401 */
402 /*!
403 * \property Kirigami::Platform::PlatformTheme::smallFont
404 *
405 * Small font.
406 */
407 Q_PROPERTY(QFont smallFont READ smallFont NOTIFY smallFontChanged FINAL)
408
409 /*!
410 * \qmlattachedproperty font Theme::fixedWidthFont
411 *
412 * Fixed width font.
413 */
414 /*!
415 * \property Kirigami::Platform::PlatformTheme::fixedWidthFont
416 *
417 * Fixed width font.
418 */
419 Q_PROPERTY(QFont fixedWidthFont READ fixedWidthFont NOTIFY fixedWidthFontChanged FINAL)
420
421 // Active palette
422 /*!
423 * \qmlattachedproperty QPalette Theme::palette
424 *
425 * Palette.
426 */
427 /*!
428 * \property Kirigami::Platform::PlatformTheme::palette
429 *
430 * Palette.
431 */
432 Q_PROPERTY(QPalette palette READ palette NOTIFY paletteChanged FINAL)
433
434 /*!
435 * \qmlattachedproperty real Theme::frameContrast
436 *
437 * Frame contrast value, usually used for separators and outlines
438 * Value is between 0.0 and 1.0.
439 */
440 /*!
441 * \property Kirigami::Platform::PlatformTheme::frameContrast
442 *
443 * Frame contrast value, usually used for separators and outlines
444 * Value is between 0.0 and 1.0.
445 */
446 Q_PROPERTY(qreal frameContrast READ frameContrast CONSTANT FINAL)
447
448 /*!
449 * \qmlattachedproperty real Theme::lightFrameContrast
450 *
451 * Returns half of the frameContrast value; used by Separator.Weight.Light
452 * Value is between 0.0 and 1.0.
453 */
454 /*!
455 * \property Kirigami::Platform::PlatformTheme::lightFrameContrast
456 *
457 * Returns half of the frameContrast value; used by Separator.Weight.Light
458 * Value is between 0.0 and 1.0.
459 */
460 Q_PROPERTY(qreal lightFrameContrast READ lightFrameContrast CONSTANT FINAL)
461
462public:
463 /*!
464 * \value View Color set for item views, usually the lightest of all
465 * \value Window Default Color set for windows and "chrome" areas
466 * \value Button Color set used by buttons
467 * \value Selection Color set used by selected areas
468 * \value Tooltip Color set used by tooltips
469 * \value Complementary Color set meant to be complementary to Window: usually is a dark theme for light themes
470 * \value Header Color set to be used by heading areas of applications, such as toolbars
471 * \omitvalue ColorSetCount
472 */
473 enum ColorSet {
474 View = 0,
475 Window,
476 Button,
477 Selection,
478 Tooltip,
479 Complementary,
480 Header,
481 // Number of items in this enum, this should always be the last item.
482 ColorSetCount,
483 };
484 Q_ENUM(ColorSet)
485
486 /*!
487 * \value Disabled
488 * \value Active
489 * \value Inactive
490 * \value Normal
491 * \omitvalue ColorGroupCount
492 */
493 enum ColorGroup {
494 Disabled = QPalette::Disabled,
495 Active = QPalette::Active,
496 Inactive = QPalette::Inactive,
497 Normal = QPalette::Normal,
498
499 ColorGroupCount, // Number of items in this enum, this should always be the last item.
500 };
501 Q_ENUM(ColorGroup)
502
503 explicit PlatformTheme(QObject *parent = nullptr);
504 ~PlatformTheme() override;
505
506 void setColorSet(PlatformTheme::ColorSet);
507 PlatformTheme::ColorSet colorSet() const;
508
509 void setColorGroup(PlatformTheme::ColorGroup);
510 PlatformTheme::ColorGroup colorGroup() const;
511
512 bool inherit() const;
513 void setInherit(bool inherit);
514
515 // foreground colors
516 QColor textColor() const;
517 QColor disabledTextColor() const;
518 QColor highlightedTextColor() const;
519 QColor activeTextColor() const;
520 QColor linkColor() const;
521 QColor visitedLinkColor() const;
522 QColor negativeTextColor() const;
523 QColor neutralTextColor() const;
524 QColor positiveTextColor() const;
525
526 // background colors
527 QColor backgroundColor() const;
528 QColor alternateBackgroundColor() const;
529 QColor highlightColor() const;
530 QColor activeBackgroundColor() const;
531 QColor linkBackgroundColor() const;
532 QColor visitedLinkBackgroundColor() const;
533 QColor negativeBackgroundColor() const;
534 QColor neutralBackgroundColor() const;
535 QColor positiveBackgroundColor() const;
536
537 // decoration colors
538 QColor focusColor() const;
539 QColor hoverColor() const;
540
541 QFont defaultFont() const;
542 QFont smallFont() const;
543 QFont fixedWidthFont() const;
544
545 // this may is used by the desktop QQC2 to set the styleoption palettes
546 QPalette palette() const;
547
548 qreal frameContrast() const;
549 qreal lightFrameContrast() const;
550
551 /*!
552 * This will be used by desktopicon to fetch icons with KIconLoader.
553 */
554 virtual Q_INVOKABLE QIcon iconFromTheme(const QString &name, const QColor &customColor = Qt::transparent);
555
556 bool supportsIconColoring() const;
557
558 // foreground colors
559 void setCustomTextColor(const QColor &color = QColor());
560 void setCustomDisabledTextColor(const QColor &color = QColor());
561 void setCustomHighlightedTextColor(const QColor &color = QColor());
562 void setCustomActiveTextColor(const QColor &color = QColor());
563 void setCustomLinkColor(const QColor &color = QColor());
564 void setCustomVisitedLinkColor(const QColor &color = QColor());
565 void setCustomNegativeTextColor(const QColor &color = QColor());
566 void setCustomNeutralTextColor(const QColor &color = QColor());
567 void setCustomPositiveTextColor(const QColor &color = QColor());
568 // background colors
569 void setCustomBackgroundColor(const QColor &color = QColor());
570 void setCustomAlternateBackgroundColor(const QColor &color = QColor());
571 void setCustomHighlightColor(const QColor &color = QColor());
572 void setCustomActiveBackgroundColor(const QColor &color = QColor());
573 void setCustomLinkBackgroundColor(const QColor &color = QColor());
574 void setCustomVisitedLinkBackgroundColor(const QColor &color = QColor());
575 void setCustomNegativeBackgroundColor(const QColor &color = QColor());
576 void setCustomNeutralBackgroundColor(const QColor &color = QColor());
577 void setCustomPositiveBackgroundColor(const QColor &color = QColor());
578 // decoration colors
579 void setCustomFocusColor(const QColor &color = QColor());
580 void setCustomHoverColor(const QColor &color = QColor());
581
582 bool useAlternateBackgroundColor() const;
583 void setUseAlternateBackgroundColor(bool alternate);
584
585 // QML attached property
586 static PlatformTheme *qmlAttachedProperties(QObject *object);
587
588Q_SIGNALS:
589 void colorsChanged();
590 void defaultFontChanged(const QFont &font);
591 void smallFontChanged(const QFont &font);
592 void fixedWidthFontChanged(const QFont &font);
593 void colorSetChanged(Kirigami::Platform::PlatformTheme::ColorSet colorSet);
594 void colorGroupChanged(Kirigami::Platform::PlatformTheme::ColorGroup colorGroup);
595 void paletteChanged(const QPalette &pal);
596 void inheritChanged(bool inherit);
597 void useAlternateBackgroundColorChanged(bool alternate);
598
599protected:
600 /// To set in the constructors so the changes trackers can avoid emitting
601 void setConstructing(bool isConstructing);
602
603 // Setters, not accessible from QML but from implementations
604 void setSupportsIconColoring(bool support);
605
606 // foreground colors
607 void setTextColor(const QColor &color);
608 void setDisabledTextColor(const QColor &color);
609 void setHighlightedTextColor(const QColor &color);
610 void setActiveTextColor(const QColor &color);
611 void setLinkColor(const QColor &color);
612 void setVisitedLinkColor(const QColor &color);
613 void setNegativeTextColor(const QColor &color);
614 void setNeutralTextColor(const QColor &color);
615 void setPositiveTextColor(const QColor &color);
616
617 // background colors
618 void setBackgroundColor(const QColor &color);
619 void setAlternateBackgroundColor(const QColor &color);
620 void setHighlightColor(const QColor &color);
621 void setActiveBackgroundColor(const QColor &color);
622 void setLinkBackgroundColor(const QColor &color);
623 void setVisitedLinkBackgroundColor(const QColor &color);
624 void setNegativeBackgroundColor(const QColor &color);
625 void setNeutralBackgroundColor(const QColor &color);
626 void setPositiveBackgroundColor(const QColor &color);
627
628 // decoration colors
629 void setFocusColor(const QColor &color);
630 void setHoverColor(const QColor &color);
631
632 void setDefaultFont(const QFont &defaultFont);
633 void setSmallFont(const QFont &smallFont);
634 void setFixedWidthFont(const QFont &fixedWidthFont);
635
636 bool event(QEvent *event) override;
637
638private:
639 KIRIGAMIPLATFORM_NO_EXPORT void update();
640 KIRIGAMIPLATFORM_NO_EXPORT void updateChildren(QObject *item);
641 KIRIGAMIPLATFORM_NO_EXPORT QObject *determineParent(QObject *object);
642 KIRIGAMIPLATFORM_NO_EXPORT void emitSignalsForChanges(int changes);
643
644 PlatformThemePrivate *d;
645 friend class PlatformThemePrivate;
646 friend class PlatformThemeData;
647 friend class PlatformThemeChangeTracker;
648};
649
650/*!
651 * \brief A class that tracks changes to PlatformTheme properties and emits signals at the right moment.
652 * \inheaderfile Kirigami/Platform/PlatformTheme
653 * \inmodule KirigamiPlatform
654 *
655 * This should be used by PlatformTheme implementations to ensure that multiple
656 * changes to a PlatformTheme's properties do not emit multiple change signals,
657 * instead batching all of them into a single signal emission. This then ensures
658 * things making use of PlatformTheme aren't needlessly redrawn or redrawn in a
659 * partially changed state.
660 *
661 * \since 6.7
662 *
663 */
664class KIRIGAMIPLATFORM_EXPORT PlatformThemeChangeTracker
665{
666public:
667 /*!
668 * \enum Kirigami::Platform::PlatformThemeChangeTracker::PropertyChange
669 * \brief Flags used to indicate changes made to certain properties.
670 *
671 * \value None
672 * \value ColorSet
673 * \value ColorGroup
674 * \value Color
675 * \value Palette
676 * \value Font
677 * \value Data
678 * \value All
679 */
680 enum class PropertyChange : uint8_t {
681 None = 0,
682 ColorSet = 1 << 0,
683 ColorGroup = 1 << 1,
684 Color = 1 << 2,
685 Palette = 1 << 3,
686 Font = 1 << 4,
687 Data = 1 << 5,
688 All = ColorSet | ColorGroup | Color | Palette | Font | Data,
689 };
690 Q_DECLARE_FLAGS(PropertyChanges, PropertyChange)
691
692 PlatformThemeChangeTracker(PlatformTheme *theme, PropertyChanges changes = PropertyChange::None);
693 ~PlatformThemeChangeTracker();
694
695 void markDirty(PropertyChanges changes);
696
697private:
698 PlatformTheme *m_theme;
699
700 // Per-PlatformTheme data that we need for PlatformThemeChangeBlocker.
701 // We don't want to store this in PlatformTheme since that would increase the
702 // size of every instance of PlatformTheme while it's only used when we want to
703 // block property change signal emissions. So instead we store it in a separate
704 // hash using the PlatformTheme as key.
705 struct Data {
706 PropertyChanges changes;
707 };
708
709 std::shared_ptr<Data> m_data;
710
711 inline static QHash<PlatformTheme *, std::weak_ptr<Data>> s_blockedChanges;
712};
713
714namespace PlatformThemeEvents
715{
716// TODO qdoc document this?
717// To avoid the overhead of Qt's signal/slot connections, we use custom events
718// to communicate with subclasses. This way, we can indicate what actually
719// changed without needing to add new virtual functions to PlatformTheme which
720// would break binary compatibility.
721//
722// To handle these events in your subclass, override QObject::event() and check
723// if you receive one of these events, then do what is needed. Finally, make
724// sure to call PlatformTheme::event() since that will also do some processing
725// of these events.
726
727template<typename T>
728class KIRIGAMIPLATFORM_EXPORT PropertyChangedEvent : public QEvent
729{
730public:
731 PropertyChangedEvent(PlatformTheme *theme, const T &previous, const T &current)
732 : QEvent(PropertyChangedEvent<T>::type)
733 , sender(theme)
734 , oldValue(previous)
735 , newValue(current)
736 {
737 }
738
739 PlatformTheme *sender;
740 T oldValue;
741 T newValue;
742
743 static QEvent::Type type;
744};
745
746using DataChangedEvent = PropertyChangedEvent<std::shared_ptr<PlatformThemeData>>;
747using ColorSetChangedEvent = PropertyChangedEvent<PlatformTheme::ColorSet>;
748using ColorGroupChangedEvent = PropertyChangedEvent<PlatformTheme::ColorGroup>;
749using ColorChangedEvent = PropertyChangedEvent<QColor>;
750using FontChangedEvent = PropertyChangedEvent<QFont>;
751
752}
753
754}
755} // namespace Kirigami
756
757Q_DECLARE_OPERATORS_FOR_FLAGS(Kirigami::Platform::PlatformThemeChangeTracker::PropertyChanges)
758
759#endif // PLATFORMTHEME_H
760

source code of kirigami/src/platform/platformtheme.h