KConfigWidgets

kstatefulbrush.h
1 /*
2  SPDX-FileCopyrightText: 2007 Matthew Woehlke <[email protected]>
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 
14 class KStatefulBrushPrivate;
15 
16 /**
17  * @class KStatefulBrush kstatefulbrush.h KStatefulBrush
18  * A container for a "state-aware" brush.
19  *
20  * KStatefulBrush provides an easy and safe way to store a color for use in a
21  * user interface. It is "safe" both in that it will make it easy to deal with
22  * widget states in a correct manner, and that it insulates you against changes
23  * in QPalette::ColorGroup.
24  *
25  * Basically, a stateful brush is used to cache a particular "color" from the
26  * KDE system palette (usually, one which does not live in QPalette). When you
27  * are ready to draw using the brush, you use the current state to retrieve the
28  * appropriate brush.
29  *
30  * Stateful brushes can also be used to apply state effects to arbitrary
31  * brushes, for example when working with a application specific user-defined
32  * color palette.
33  *
34  * @note As of Qt 4.3, QPalette::ColorGroup is missing a state for disabled
35  * widgets in an inactive window. Hopefully Trolltech will fix this bug, at
36  * which point KColorScheme and KStatefulBrush will be updated to recognize the
37  * new state. Using KStatefulBrush will allow your application to inherit these
38  * changes "for free", without even recompiling.
39  */
40 class KCONFIGWIDGETS_EXPORT KStatefulBrush
41 {
42 public:
43  /**
44  * Construct a "default" stateful brush. For such an instance, all
45  * overloads of KStatefulBrush::brush will return a default brush (i.e.
46  * <tt>QBrush()</tt>).
47  */
48  explicit KStatefulBrush();
49 
50  /**
51  * Construct a stateful brush from given color set and foreground role,
52  * using the colors from the given KConfig.
53  * If null, the application's color scheme is used (either the system
54  * default, or one set by KColorSchemeManager).
55  */
56  explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::ForegroundRole, KSharedConfigPtr = KSharedConfigPtr());
57 
58  /**
59  * Construct a stateful brush from given color set and background role,
60  * using the colors from the given KConfig (if null, the application's
61  * colors are used).
62  */
63  explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::BackgroundRole, KSharedConfigPtr = KSharedConfigPtr());
64 
65  /**
66  * Construct a stateful brush from given color set and decoration role,
67  * using the colors from the given KConfig (if null, the application's
68  * colors are used).
69  */
70  explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::DecorationRole, KSharedConfigPtr = KSharedConfigPtr());
71 
72  /**
73  * Construct a stateful background brush from a specified QBrush (or
74  * QColor, via QBrush's implicit constructor). The various states are
75  * determined from the base QBrush (which fills in the Active state)
76  * according to the same rules used to build stateful color schemes from
77  * the system color scheme. The state effects from the given KConfig are
78  * used (if null, the application's state effects are used).
79  */
80  explicit KStatefulBrush(const QBrush &, KSharedConfigPtr = KSharedConfigPtr());
81 
82  /**
83  * Construct a stateful foreground/decoration brush from a specified
84  * QBrush (or QColor, via QBrush's implicit constructor). The various
85  * states are determined from the base QBrush (which fills in the Active
86  * state) according to the same rules used to build stateful color schemes
87  * from the system color scheme. The state effects from the given KConfig
88  * are used (if null, the application's state effects are used).
89  *
90  * @param background The background brush (or color) corresponding to the
91  * KColorScheme::NormalBackground role and QPalette::Active state for this
92  * foreground/decoration color.
93  */
94  explicit KStatefulBrush(const QBrush &, const QBrush &background, KSharedConfigPtr = KSharedConfigPtr());
95 
96  /** Construct a copy of another KStatefulBrush. */
98 
99  /** Destructor */
100  ~KStatefulBrush();
101 
102  /** Standard assignment operator */
103  KStatefulBrush &operator=(const KStatefulBrush &);
104 
105  /**
106  * Retrieve the brush for the specified widget state. This is used when you
107  * know explicitly what state is wanted. Otherwise one of overloads is
108  * often more convenient.
109  */
110  QBrush brush(QPalette::ColorGroup) const;
111 
112  /**
113  * Retrieve the brush, using a QPalette reference to determine the correct
114  * state. Use when your painting code has easy access to the QPalette that
115  * it is supposed to be using. The state used in this instance is the
116  * currentColorGroup of the palette.
117  */
118  QBrush brush(const QPalette &) const;
119 
120 #if KCONFIGWIDGETS_ENABLE_DEPRECATED_SINCE(5, 84)
121  /**
122  * Retrieve the brush, using a QWidget pointer to determine the correct
123  * state. Use when you have a pointer to the widget that you are painting.
124  * The state used is the current state of the widget.
125  *
126  * @note If you pass an invalid widget, you will get a default brush (i.e.
127  * <tt>QBrush()</tt>).
128  * @deprecated Since 5.84, use @ref brush(const QPalette &) instead.
129  * A typical replacement would be <tt>brush(widget->palette())</tt>
130  * (in case @c widget cannot be @c null in this context).
131  */
132  KCONFIGWIDGETS_DEPRECATED_VERSION(5, 84, "Use KStatefulBrush::brush(const QPalette&) instead")
133  QBrush brush(const QWidget *) const;
134 #endif
135 
136 private:
137  std::unique_ptr<KStatefulBrushPrivate> d;
138 };
139 
140 Q_DECLARE_METATYPE(KStatefulBrush) /* so we can pass it in QVariant's */
141 
142 #endif
ForegroundRole
This enumeration describes the foreground color being selected from the given set.
Definition: kcolorscheme.h:209
ColorSet
This enumeration describes the color set for which a color is being selected.
Definition: kcolorscheme.h:65
DecorationRole
This enumeration describes the decoration color being selected from the given set.
Definition: kcolorscheme.h:270
BackgroundRole
This enumeration describes the background color being selected from the given set.
Definition: kcolorscheme.h:135
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Feb 7 2023 03:54:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.