File indexing completed on 2024-07-21 12:06:41

0001 /*
0002     SPDX-FileCopyrightText: 2007 Matthew Woehlke <mw_triad@users.sourceforge.net>
0003 
0004     SPDX-License-Identifier: LGPL-2.0-or-later
0005 */
0006 
0007 #ifndef KSTATEFULBRUSH_H
0008 #define KSTATEFULBRUSH_H
0009 
0010 #include "kcolorscheme.h"
0011 
0012 #include <memory>
0013 
0014 class KStatefulBrushPrivate;
0015 
0016 /**
0017  * @class KStatefulBrush kstatefulbrush.h KStatefulBrush
0018  * A container for a "state-aware" brush.
0019  *
0020  * KStatefulBrush provides an easy and safe way to store a color for use in a
0021  * user interface. It is "safe" both in that it will make it easy to deal with
0022  * widget states in a correct manner, and that it insulates you against changes
0023  * in QPalette::ColorGroup.
0024  *
0025  * Basically, a stateful brush is used to cache a particular "color" from the
0026  * KDE system palette (usually, one which does not live in QPalette). When you
0027  * are ready to draw using the brush, you use the current state to retrieve the
0028  * appropriate brush.
0029  *
0030  * Stateful brushes can also be used to apply state effects to arbitrary
0031  * brushes, for example when working with a application specific user-defined
0032  * color palette.
0033  *
0034  * @note As of Qt 4.3, QPalette::ColorGroup is missing a state for disabled
0035  * widgets in an inactive window. Hopefully Trolltech will fix this bug, at
0036  * which point KColorScheme and KStatefulBrush will be updated to recognize the
0037  * new state. Using KStatefulBrush will allow your application to inherit these
0038  * changes "for free", without even recompiling.
0039  */
0040 class KCONFIGWIDGETS_EXPORT KStatefulBrush
0041 {
0042 public:
0043     /**
0044      * Construct a "default" stateful brush. For such an instance, all
0045      * overloads of KStatefulBrush::brush will return a default brush (i.e.
0046      * <tt>QBrush()</tt>).
0047      */
0048     explicit KStatefulBrush();
0049 
0050     /**
0051      * Construct a stateful brush from given color set and foreground role,
0052      * using the colors from the given KConfig.
0053      * If null, the application's color scheme is used (either the system
0054      * default, or one set by KColorSchemeManager).
0055      */
0056     explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::ForegroundRole, KSharedConfigPtr = KSharedConfigPtr());
0057 
0058     /**
0059      * Construct a stateful brush from given color set and background role,
0060      * using the colors from the given KConfig (if null, the application's
0061      * colors are used).
0062      */
0063     explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::BackgroundRole, KSharedConfigPtr = KSharedConfigPtr());
0064 
0065     /**
0066      * Construct a stateful brush from given color set and decoration role,
0067      * using the colors from the given KConfig (if null, the application's
0068      * colors are used).
0069      */
0070     explicit KStatefulBrush(KColorScheme::ColorSet, KColorScheme::DecorationRole, KSharedConfigPtr = KSharedConfigPtr());
0071 
0072     /**
0073      * Construct a stateful background brush from a specified QBrush (or
0074      * QColor, via QBrush's implicit constructor). The various states are
0075      * determined from the base QBrush (which fills in the Active state)
0076      * according to the same rules used to build stateful color schemes from
0077      * the system color scheme. The state effects from the given KConfig are
0078      * used (if null, the application's state effects are used).
0079      */
0080     explicit KStatefulBrush(const QBrush &, KSharedConfigPtr = KSharedConfigPtr());
0081 
0082     /**
0083      * Construct a stateful foreground/decoration brush from a specified
0084      * QBrush (or QColor, via QBrush's implicit constructor). The various
0085      * states are determined from the base QBrush (which fills in the Active
0086      * state) according to the same rules used to build stateful color schemes
0087      * from the system color scheme. The state effects from the given KConfig
0088      * are used (if null, the application's state effects are used).
0089      *
0090      * @param background The background brush (or color) corresponding to the
0091      * KColorScheme::NormalBackground role and QPalette::Active state for this
0092      * foreground/decoration color.
0093      */
0094     explicit KStatefulBrush(const QBrush &, const QBrush &background, KSharedConfigPtr = KSharedConfigPtr());
0095 
0096     /** Construct a copy of another KStatefulBrush. */
0097     KStatefulBrush(const KStatefulBrush &);
0098 
0099     /** Destructor */
0100     ~KStatefulBrush();
0101 
0102     /** Standard assignment operator */
0103     KStatefulBrush &operator=(const KStatefulBrush &);
0104 
0105     /**
0106      * Retrieve the brush for the specified widget state. This is used when you
0107      * know explicitly what state is wanted. Otherwise one of overloads is
0108      * often more convenient.
0109      */
0110     QBrush brush(QPalette::ColorGroup) const;
0111 
0112     /**
0113      * Retrieve the brush, using a QPalette reference to determine the correct
0114      * state. Use when your painting code has easy access to the QPalette that
0115      * it is supposed to be using. The state used in this instance is the
0116      * currentColorGroup of the palette.
0117      */
0118     QBrush brush(const QPalette &) const;
0119 
0120 #if KCONFIGWIDGETS_ENABLE_DEPRECATED_SINCE(5, 84)
0121     /**
0122      * Retrieve the brush, using a QWidget pointer to determine the correct
0123      * state. Use when you have a pointer to the widget that you are painting.
0124      * The state used is the current state of the widget.
0125      *
0126      * @note If you pass an invalid widget, you will get a default brush (i.e.
0127      * <tt>QBrush()</tt>).
0128      * @deprecated Since 5.84, use @ref brush(const QPalette &) instead.
0129      * A typical replacement would be <tt>brush(widget->palette())</tt>
0130      * (in case @c widget cannot be @c null in this context).
0131      */
0132     KCONFIGWIDGETS_DEPRECATED_VERSION(5, 84, "Use KStatefulBrush::brush(const QPalette&) instead")
0133     QBrush brush(const QWidget *) const;
0134 #endif
0135 
0136 private:
0137     std::unique_ptr<KStatefulBrushPrivate> d;
0138 };
0139 
0140 Q_DECLARE_METATYPE(KStatefulBrush) /* so we can pass it in QVariant's */
0141 
0142 #endif