KColorScheme Class
A set of methods used to work with colors. More...
| Header: | #include <KColorScheme> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS ColorScheme)target_link_libraries(mytarget PRIVATE KF6::ColorScheme) |
Public Types
| enum | BackgroundRole { NormalBackground, AlternateBackground, ActiveBackground, LinkBackground, VisitedBackground, …, PositiveBackground } |
| enum | ColorSet { View, Window, Button, Selection, Tooltip, Complementary } |
| enum | DecorationRole { FocusColor, HoverColor } |
| enum | ForegroundRole { NormalText, InactiveText, ActiveText, LinkText, VisitedText, …, PositiveText } |
| enum | ShadeRole { LightShade, MidlightShade, MidShade, DarkShade, ShadowShade } |
Public Functions
| KColorScheme(QPalette::ColorGroup = QPalette::Normal, KColorScheme::ColorSet = View, KSharedConfigPtr = KSharedConfigPtr()) | |
| virtual | ~KColorScheme() |
| QBrush | background(KColorScheme::BackgroundRole = NormalBackground) const |
| QBrush | decoration(KColorScheme::DecorationRole) const |
| QBrush | foreground(KColorScheme::ForegroundRole = NormalText) const |
| QColor | shade(KColorScheme::ShadeRole) const |
(since 5.92) bool | operator==(const KColorScheme &other) const |
Static Public Members
| void | adjustBackground(QPalette &, KColorScheme::BackgroundRole newRole = NormalBackground, QPalette::ColorRole color = QPalette::Base, KColorScheme::ColorSet set = View, KSharedConfigPtr = KSharedConfigPtr()) |
| void | adjustForeground(QPalette &, KColorScheme::ForegroundRole newRole = NormalText, QPalette::ColorRole color = QPalette::Text, KColorScheme::ColorSet set = View, KSharedConfigPtr = KSharedConfigPtr()) |
| qreal | contrastF(const KSharedConfigPtr &config = KSharedConfigPtr()) |
(since 5.0) QPalette | createApplicationPalette(const KSharedConfigPtr &config) |
(since 5.75) bool | isColorSetSupported(const KSharedConfigPtr &config, KColorScheme::ColorSet set) |
| QColor | shade(const QColor &, KColorScheme::ShadeRole) |
| QColor | shade(const QColor &, KColorScheme::ShadeRole, qreal contrast, qreal chromaAdjust = 0.0) |
Detailed Description
KColorScheme currently provides access to the system color palette that the user has selected (in the future, it is expected to do more). It greatly expands on QPalette by providing five distinct "sets" with several color choices each, covering background, foreground, and decoration colors.
A KColorScheme instance represents colors corresponding to a "set", where a set consists of those colors used to draw a particular type of element, such as a menu, button, view, selected text, or tooltip. Each set has a distinct set of colors, so you should always use the correct set for drawing and never assume that a particular foreground for one set is the same as the foreground for any other set. Individual colors may be quickly referenced by creating an anonymous instance and invoking a lookup member.
Note: The color palettes for the various states of a widget (active, inactive, disabled) may be wildly different. Therefore, it is important to take the state into account. This is why the KColorScheme constructor requires a QPalette::ColorGroup as an argument.
To facilitate working with potentially-varying states, two convenience API's are provided. These are KColorScheme::adjustBackground and its sister KColorScheme::adjustForeground, and the helper class KStatefulBrush.
See also KColorScheme::ColorSet, KColorScheme::ForegroundRole, KColorScheme::BackgroundRole, KColorScheme::DecorationRole, and KColorScheme::ShadeRole.
Member Type Documentation
enum KColorScheme::BackgroundRole
This enumeration describes the background color being selected from the given set.
Background colors are suitable for drawing under text, and should never be used to draw text. In combination with one of the overloads of KColorScheme::shade, they may be used to generate colors for drawing frames, bevels, and similar decorations.
| Constant | Value | Description |
|---|---|---|
KColorScheme::NormalBackground | 0 | Normal background. |
KColorScheme::AlternateBackground | 1 | Alternate background; for example, for use in lists. This color may be the same as BackgroundNormal, especially in sets other than View and Window. |
KColorScheme::ActiveBackground | 2 | Third color; for example, items which are new, active, requesting attention, etc. Alerting the user that a certain field must be filled out would be a good usage (although NegativeBackground could be used to the same effect, depending on what you are trying to achieve). Unlike ActiveText, this should not be used for mouseover effects. |
KColorScheme::LinkBackground | 3 | Fourth color; corresponds to (unvisited) links. Exactly what this might be used for is somewhat harder to qualify; it might be used for bookmarks, as a 'you can click here' indicator, or to highlight recent content (i.e. in a most-recently-accessed list). |
KColorScheme::VisitedBackground | 4 | Fifth color; corresponds to visited links. This can also be used to indicate "not recent" content, especially when a color is needed to denote content which is "old" or "archival". |
KColorScheme::NegativeBackground | 5 | Sixth color; for example, errors, untrusted content, etc. |
KColorScheme::NeutralBackground | 6 | Seventh color; for example, warnings, secure/encrypted content. |
KColorScheme::PositiveBackground | 7 | Eighth color; for example, success messages, trusted content. |
enum KColorScheme::ColorSet
This enumeration describes the color set for which a color is being selected.
Color sets define a color "environment", suitable for drawing all parts of a given region. Colors from different sets should not be combined.
| Constant | Value | Description |
|---|---|---|
KColorScheme::View | 0 | Views; for example, frames, input fields, etc. If it contains things that can be selected, it is probably a View. |
KColorScheme::Window | 1 | Non-editable window elements; for example, menus. If it isn't a Button, View, or Tooltip, it is probably a Window. |
KColorScheme::Button | 2 | Buttons and button-like controls. In addition to buttons, "button-like" controls such as non-editable dropdowns, scrollbar sliders, slider handles, etc. should also use this role. |
KColorScheme::Selection | 3 | Selected items in views. Note that unfocused or disabled selections should use the Window role. This makes it more obvious to the user that the view containing the selection does not have input focus. |
KColorScheme::Tooltip | 4 | Tooltips. The tooltip set can often be substituted for the view set when editing is not possible, but the Window set is deemed inappropriate. "What's This" help is an excellent example, another might be pop-up notifications (depending on taste). |
KColorScheme::Complementary (since KColorScheme 5.19) | 5 | Complementary areas. Some applications want some areas to have a different color scheme. Usually dark areas over a light theme. For instance the fullscreen UI of a picture viewer, or the logout/lock screen of the plasma workspace ask for a dark color scheme even on light themes. |
enum KColorScheme::DecorationRole
This enumeration describes the decoration color being selected from the given set.
Decoration colors are used to draw decorations (such as frames) for special purposes. Like color shades, they are neither foreground nor background colors. Text should not be painted over a decoration color, and decoration colors should not be used to draw text.
| Constant | Value | Description |
|---|---|---|
KColorScheme::FocusColor | 0 | Color used to draw decorations for items which have input focus. |
KColorScheme::HoverColor | 1 | Color used to draw decorations for items which will be activated by clicking. |
enum KColorScheme::ForegroundRole
This enumeration describes the foreground color being selected from the given set.
Foreground colors are suitable for drawing text or glyphs (such as the symbols on window decoration buttons, assuming a suitable background brush is used), and should never be used to draw backgrounds.
For window decorations, the following is suggested, but not set in stone:
- Maximize -
PositiveText - Minimize -
NeutralText - Close -
NegativeText - WhatsThis -
LinkText - Sticky -
ActiveText
| Constant | Value | Description |
|---|---|---|
KColorScheme::NormalText | 0 | Normal foreground. |
KColorScheme::InactiveText | 1 | Second color; for example, comments, items which are old, inactive or disabled. Generally used for things that are meant to be "less important". InactiveText is not the same role as NormalText in the inactive state. |
KColorScheme::ActiveText | 2 | Third color; for example items which are new, active, requesting attention, etc. May be used as a hover color for clickable items. |
KColorScheme::LinkText | 3 | Fourth color; use for (unvisited) links. May also be used for other clickable items or content that indicates relationships, items that indicate somewhere the user can visit, etc. |
KColorScheme::VisitedText | 4 | Fifth color; used for (visited) links. As with LinkText, may be used for items that have already been "visited" or accessed. May also be used to indicate "historical" (i.e. "old") items or information, especially if InactiveText is being used in the same context to express something different. |
KColorScheme::NegativeText | 5 | Sixth color; for example, errors, untrusted content, deletions, etc. |
KColorScheme::NeutralText | 6 | Seventh color; for example, warnings, secure/encrypted content. |
KColorScheme::PositiveText | 7 | Eighth color; for example, additions, success messages, trusted content. |
enum KColorScheme::ShadeRole
This enumeration describes the color shade being selected from the given set.
Color shades are used to draw "3d" elements, such as frames and bevels. They are neither foreground nor background colors. Text should not be painted over a shade, and shades should not be used to draw text.
| Constant | Value | Description |
|---|---|---|
KColorScheme::LightShade | 0 | The light color is lighter than QPalette::dark() or QPalette::shadow() and contrasts with the base color. |
KColorScheme::MidlightShade | 1 | The midlight color is in between base() and QPalette::light(). |
KColorScheme::MidShade | 2 | The mid color is in between QPalette::base() and QPalette::dark(). |
KColorScheme::DarkShade | 3 | The dark color is in between QPalette::mid() and QPalette::shadow(). |
KColorScheme::ShadowShade | 4 | The shadow color is darker than QPalette::light() or QPalette::midlight() and contrasts the base color. |
Member Function Documentation
[explicit] KColorScheme::KColorScheme(QPalette::ColorGroup = QPalette::Normal, KColorScheme::ColorSet = View, KSharedConfigPtr = KSharedConfigPtr())
Construct a palette from given color set and state. Colors are taken from the given KConfig. If null, the application's color scheme is used (either the system default or one set by KColorSchemeManager).
Note: KColorScheme provides direct access to the color scheme for users that deal directly with widget states. Unless you are a low-level user or have a legitimate reason to only care about a fixed, limited number of states (e.g. windows that cannot be inactive), consider using a KStatefulBrush instead.
[virtual noexcept] KColorScheme::~KColorScheme()
Destructor
[static] void KColorScheme::adjustBackground(QPalette &, KColorScheme::BackgroundRole newRole = NormalBackground, QPalette::ColorRole color = QPalette::Base, KColorScheme::ColorSet set = View, KSharedConfigPtr = KSharedConfigPtr())
Adjust a QPalette by replacing the specified QPalette::ColorRole with the requested background color for all states. Using this method is safer than replacing individual states, as it insulates you against changes in QPalette::ColorGroup.
Note: Although it is possible to replace a foreground color using this method, it's bad usability to do so. Just say "no".
[static] void KColorScheme::adjustForeground(QPalette &, KColorScheme::ForegroundRole newRole = NormalText, QPalette::ColorRole color = QPalette::Text, KColorScheme::ColorSet set = View, KSharedConfigPtr = KSharedConfigPtr())
Adjust a QPalette by replacing the specified QPalette::ColorRole with the requested foreground color for all states. Using this method is safer than replacing individual states, as it insulates you against changes in QPalette::ColorGroup.
Note: Although it is possible to replace a background color using this method, it's bad usability to do so. Just say "no".
QBrush KColorScheme::background(KColorScheme::BackgroundRole = NormalBackground) const
Retrieve the requested background brush.
[static] qreal KColorScheme::contrastF(const KSharedConfigPtr &config = KSharedConfigPtr())
Returns the contrast for borders as a floating point value.
config pointer to the config from which to read the contrast setting. If null, the application's color scheme will be used (either the system default or one set by KColorSchemeManager).
Returns the contrast (between 0.0 for minimum and 1.0 for maximum contrast)
[static, since 5.0] QPalette KColorScheme::createApplicationPalette(const KSharedConfigPtr &config)
Used to obtain the QPalette that will be used to set the application palette from KDE Platform theme.
config KConfig from which to load the colors
Returns the QPalette
This function was introduced in 5.0.
QBrush KColorScheme::decoration(KColorScheme::DecorationRole) const
Retrieve the requested decoration brush.
QBrush KColorScheme::foreground(KColorScheme::ForegroundRole = NormalText) const
Retrieve the requested foreground brush.
[static, since 5.75] bool KColorScheme::isColorSetSupported(const KSharedConfigPtr &config, KColorScheme::ColorSet set)
Used to check if the color scheme has a given set.
config KConfig from which to load the colors
set The color set to check for.
Returns whether the color scheme has a given color set
This function was introduced in 5.75.
QColor KColorScheme::shade(KColorScheme::ShadeRole) const
Retrieve the requested shade color, using KColorScheme::background(KColorScheme::NormalBackground) as the base color and the contrast setting from the KConfig used to create this KColorScheme instance.
Note: Shades are chosen such that all shades would contrast with the base color. This means that if base is very dark, the 'dark' shades will be lighter than the base color, with QPalette::midlight() == QPalette::shadow(). Conversely, if the base color is very light, the 'light' shades will be darker than the base color, with QPalette::light() == QPalette::mid().
[static] QColor KColorScheme::shade(const QColor &, KColorScheme::ShadeRole)
Retrieve the requested shade color, using the specified color as the base color and the application's contrast setting.
Note: Shades are chosen such that all shades would contrast with the base color. This means that if base is very dark, the 'dark' shades will be lighter than the base color, with QPalette::midlight() == QPalette::shadow(). Conversely, if the base color is very light, the 'light' shades will be darker than the base color, with QPalette::light() == QPalette::mid().
[static] QColor KColorScheme::shade(const QColor &, KColorScheme::ShadeRole, qreal contrast, qreal chromaAdjust = 0.0)
Retrieve the requested shade color, using the specified color as the base color and the specified contrast.
contrast Amount roughly specifying the contrast by which to adjust the base color, between -1.0 and 1.0 (values between 0.0 and 1.0 correspond to the value from KColorScheme::contrastF)
chromaAdjust (optional) Amount by which to adjust the chroma of the shade (1.0 means no adjustment)
Note: Shades are chosen such that all shades would contrast with the base color. This means that if base is very dark, the 'dark' shades will be lighter than the base color, with QPalette::midlight() == QPalette::shadow(). Conversely, if the base color is very light, the 'light' shades will be darker than the base color, with QPalette::light() == QPalette::mid().
See also KColorUtils::shade.
[since 5.92] bool KColorScheme::operator==(const KColorScheme &other) const
This function was introduced in 5.92.