1/*
2 SPDX-FileCopyrightText: 2007 Matthew Woehlke <mw_triad@users.sourceforge.net>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#ifndef KSTATEFULBRUSH_H
8#define KSTATEFULBRUSH_H
9
10#include "kcolorscheme.h"
11
12#include <memory>
13
14class KStatefulBrushPrivate;
15
16/*!
17 * \class KStatefulBrush
18 * \inmodule KColorScheme
19 *
20 * \brief A container for a "state-aware" brush.
21 *
22 * KStatefulBrush provides an easy and safe way to store a color for use in a
23 * user interface. It is "safe" both in that it will make it easy to deal with
24 * widget states in a correct manner, and that it insulates you against changes
25 * in QPalette::ColorGroup.
26 *
27 * Basically, a stateful brush is used to cache a particular "color" from the
28 * KDE system palette (usually, one which does not live in QPalette). When you
29 * are ready to draw using the brush, you use the current state to retrieve the
30 * appropriate brush.
31 *
32 * Stateful brushes can also be used to apply state effects to arbitrary
33 * brushes, for example when working with a application specific user-defined
34 * color palette.
35 *
36 * \note As of Qt 4.3, QPalette::ColorGroup is missing a state for disabled
37 * widgets in an inactive window. Hopefully Trolltech will fix this bug, at
38 * which point KColorScheme and KStatefulBrush will be updated to recognize the
39 * new state. Using KStatefulBrush will allow your application to inherit these
40 * changes "for free", without even recompiling.
41 */
42class KCOLORSCHEME_EXPORT KStatefulBrush
43{
44public:
45 /*!
46 * Construct a "default" stateful brush. For such an instance, all
47 * overloads of KStatefulBrush::brush will return a default brush (i.e.
48 * QBrush()).
49 */
50 explicit KStatefulBrush();
51
52 /*!
53 * Construct a stateful brush from given color set and foreground role,
54 * using the colors from the given KConfig.
55 * If null, the application's color scheme is used (either the system
56 * default, or one set by KColorSchemeManager).
57 */
58 explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::ForegroundRole, KSharedConfigPtr = KSharedConfigPtr());
59
60 /*!
61 * Construct a stateful brush from given color set and background role,
62 * using the colors from the given KConfig (if null, the application's
63 * colors are used).
64 */
65 explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::BackgroundRole, KSharedConfigPtr = KSharedConfigPtr());
66
67 /*!
68 * Construct a stateful brush from given color set and decoration role,
69 * using the colors from the given KConfig (if null, the application's
70 * colors are used).
71 */
72 explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::DecorationRole, KSharedConfigPtr = KSharedConfigPtr());
73
74 /*!
75 * Construct a stateful background brush from a specified QBrush (or
76 * QColor, via QBrush's implicit constructor). The various states are
77 * determined from the base QBrush (which fills in the Active state)
78 * according to the same rules used to build stateful color schemes from
79 * the system color scheme. The state effects from the given KConfig are
80 * used (if null, the application's state effects are used).
81 */
82 explicit KStatefulBrush(const QBrush &, KSharedConfigPtr = KSharedConfigPtr());
83
84 /*!
85 * Construct a stateful foreground/decoration brush from a specified
86 * QBrush (or QColor, via QBrush's implicit constructor). The various
87 * states are determined from the base QBrush (which fills in the Active
88 * state) according to the same rules used to build stateful color schemes
89 * from the system color scheme. The state effects from the given KConfig
90 * are used (if null, the application's state effects are used).
91 *
92 * \param background The background brush (or color) corresponding to the
93 * KColorScheme::NormalBackground role and QPalette::Active state for this
94 * foreground/decoration color.
95 */
96 explicit KStatefulBrush(const QBrush &, const QBrush &background, KSharedConfigPtr = KSharedConfigPtr());
97
98 /*! Construct a copy of another KStatefulBrush. */
99 KStatefulBrush(const KStatefulBrush &);
100
101 ~KStatefulBrush();
102
103 /*! Standard assignment operator */
104 KStatefulBrush &operator=(const KStatefulBrush &);
105
106 /*!
107 * Retrieve the brush for the specified widget state. This is used when you
108 * know explicitly what state is wanted. Otherwise one of overloads is
109 * often more convenient.
110 */
111 QBrush brush(QPalette::ColorGroup) const;
112
113 /*!
114 * Retrieve the brush, using a QPalette reference to determine the correct
115 * state. Use when your painting code has easy access to the QPalette that
116 * it is supposed to be using. The state used in this instance is the
117 * QPalette::currentColorGroup().
118 */
119 QBrush brush(const QPalette &) const;
120
121private:
122 std::unique_ptr<KStatefulBrushPrivate> d;
123};
124
125Q_DECLARE_METATYPE(KStatefulBrush) /* so we can pass it in QVariant's */
126
127#endif
128

source code of kcolorscheme/src/kstatefulbrush.h