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 bool 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 void frameContrastChanged(qreal contrast);
599
600protected:
601 /// To set in the constructors so the changes trackers can avoid emitting
602 void setConstructing(bool isConstructing);
603
604 // Setters, not accessible from QML but from implementations
605 void setSupportsIconColoring(bool support);
606
607 // foreground colors
608 void setTextColor(const QColor &color);
609 void setDisabledTextColor(const QColor &color);
610 void setHighlightedTextColor(const QColor &color);
611 void setActiveTextColor(const QColor &color);
612 void setLinkColor(const QColor &color);
613 void setVisitedLinkColor(const QColor &color);
614 void setNegativeTextColor(const QColor &color);
615 void setNeutralTextColor(const QColor &color);
616 void setPositiveTextColor(const QColor &color);
617
618 // background colors
619 void setBackgroundColor(const QColor &color);
620 void setAlternateBackgroundColor(const QColor &color);
621 void setHighlightColor(const QColor &color);
622 void setActiveBackgroundColor(const QColor &color);
623 void setLinkBackgroundColor(const QColor &color);
624 void setVisitedLinkBackgroundColor(const QColor &color);
625 void setNegativeBackgroundColor(const QColor &color);
626 void setNeutralBackgroundColor(const QColor &color);
627 void setPositiveBackgroundColor(const QColor &color);
628
629 // decoration colors
630 void setFocusColor(const QColor &color);
631 void setHoverColor(const QColor &color);
632
633 void setDefaultFont(const QFont &defaultFont);
634 void setSmallFont(const QFont &smallFont);
635 void setFixedWidthFont(const QFont &fixedWidthFont);
636 void setFrameContrast(qreal contrast);
637
638 bool event(QEvent *event) override;
639
640private:
641 KIRIGAMIPLATFORM_NO_EXPORT void update();
642 KIRIGAMIPLATFORM_NO_EXPORT void updateChildren(QObject *item);
643 KIRIGAMIPLATFORM_NO_EXPORT QObject *determineParent(QObject *object);
644 KIRIGAMIPLATFORM_NO_EXPORT void emitSignalsForChanges(int changes);
645
646 PlatformThemePrivate *d;
647 friend class PlatformThemePrivate;
648 friend class PlatformThemeData;
649 friend class PlatformThemeChangeTracker;
650};
651
652/*!
653 * \brief A class that tracks changes to PlatformTheme properties and emits signals at the right moment.
654 * \inheaderfile Kirigami/Platform/PlatformTheme
655 * \inmodule KirigamiPlatform
656 *
657 * This should be used by PlatformTheme implementations to ensure that multiple
658 * changes to a PlatformTheme's properties do not emit multiple change signals,
659 * instead batching all of them into a single signal emission. This then ensures
660 * things making use of PlatformTheme aren't needlessly redrawn or redrawn in a
661 * partially changed state.
662 *
663 * \since 6.7
664 *
665 */
666class KIRIGAMIPLATFORM_EXPORT PlatformThemeChangeTracker
667{
668public:
669 /*!
670 * \enum Kirigami::Platform::PlatformThemeChangeTracker::PropertyChange
671 * \brief Flags used to indicate changes made to certain properties.
672 *
673 * \value None
674 * \value ColorSet
675 * \value ColorGroup
676 * \value Color
677 * \value Palette
678 * \value Font
679 * \value Data
680 * \value FrameContrast
681 * \value All
682 */
683 enum class PropertyChange : uint8_t {
684 None = 0,
685 ColorSet = 1 << 0,
686 ColorGroup = 1 << 1,
687 Color = 1 << 2,
688 Palette = 1 << 3,
689 Font = 1 << 4,
690 Data = 1 << 5,
691 FrameContrast = 1 << 6,
692 All = ColorSet | ColorGroup | Color | Palette | Font | Data | FrameContrast,
693 };
694 Q_DECLARE_FLAGS(PropertyChanges, PropertyChange)
695
696 PlatformThemeChangeTracker(PlatformTheme *theme, PropertyChanges changes = PropertyChange::None);
697 ~PlatformThemeChangeTracker();
698
699 void markDirty(PropertyChanges changes);
700
701private:
702 PlatformTheme *m_theme;
703
704 // Per-PlatformTheme data that we need for PlatformThemeChangeBlocker.
705 // We don't want to store this in PlatformTheme since that would increase the
706 // size of every instance of PlatformTheme while it's only used when we want to
707 // block property change signal emissions. So instead we store it in a separate
708 // hash using the PlatformTheme as key.
709 struct Data {
710 PropertyChanges changes;
711 };
712
713 std::shared_ptr<Data> m_data;
714
715 inline static QHash<PlatformTheme *, std::weak_ptr<Data>> s_blockedChanges;
716};
717
718namespace PlatformThemeEvents
719{
720// TODO qdoc document this?
721// To avoid the overhead of Qt's signal/slot connections, we use custom events
722// to communicate with subclasses. This way, we can indicate what actually
723// changed without needing to add new virtual functions to PlatformTheme which
724// would break binary compatibility.
725//
726// To handle these events in your subclass, override QObject::event() and check
727// if you receive one of these events, then do what is needed. Finally, make
728// sure to call PlatformTheme::event() since that will also do some processing
729// of these events.
730
731template<typename T>
732class KIRIGAMIPLATFORM_EXPORT PropertyChangedEvent : public QEvent
733{
734public:
735 PropertyChangedEvent(PlatformTheme *theme, const T &previous, const T &current)
736 : QEvent(PropertyChangedEvent<T>::type)
737 , sender(theme)
738 , oldValue(previous)
739 , newValue(current)
740 {
741 }
742
743 PlatformTheme *sender;
744 T oldValue;
745 T newValue;
746
747 static QEvent::Type type;
748};
749
750using DataChangedEvent = PropertyChangedEvent<std::shared_ptr<PlatformThemeData>>;
751using ColorSetChangedEvent = PropertyChangedEvent<PlatformTheme::ColorSet>;
752using ColorGroupChangedEvent = PropertyChangedEvent<PlatformTheme::ColorGroup>;
753using ColorChangedEvent = PropertyChangedEvent<QColor>;
754using FontChangedEvent = PropertyChangedEvent<QFont>;
755using FrameContrastChangedEvent = PropertyChangedEvent<qreal>;
756}
757
758}
759} // namespace Kirigami
760
761Q_DECLARE_OPERATORS_FOR_FLAGS(Kirigami::Platform::PlatformThemeChangeTracker::PropertyChanges)
762
763#endif // PLATFORMTHEME_H
764

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