KColorScheme
#include <KColorScheme>
Public Types | |
enum | BackgroundRole { NormalBackground , AlternateBackground , ActiveBackground , LinkBackground , VisitedBackground , NegativeBackground , NeutralBackground , PositiveBackground , NBackgroundRoles } |
enum | ColorSet { View , Window , Button , Selection , Tooltip , Complementary , Header , NColorSets } |
enum | DecorationRole { FocusColor , HoverColor , NDecorationRoles } |
enum | ForegroundRole { NormalText , InactiveText , ActiveText , LinkText , VisitedText , NegativeText , NeutralText , PositiveText , NForegroundRoles } |
enum | ShadeRole { LightShade , MidlightShade , MidShade , DarkShade , ShadowShade , NShadeRoles } |
Public Member Functions | |
KColorScheme (const KColorScheme &) | |
KColorScheme (KColorScheme &&) | |
KColorScheme (QPalette::ColorGroup=QPalette::Normal, ColorSet=View, KSharedConfigPtr=KSharedConfigPtr()) | |
virtual | ~KColorScheme () |
QBrush | background (BackgroundRole=NormalBackground) const |
QBrush | decoration (DecorationRole) const |
QBrush | foreground (ForegroundRole=NormalText) const |
KColorScheme & | operator= (const KColorScheme &) |
KColorScheme & | operator= (KColorScheme &&) |
bool | operator== (const KColorScheme &other) const |
QColor | shade (ShadeRole) const |
Static Public Member Functions | |
static void | adjustBackground (QPalette &, BackgroundRole newRole=NormalBackground, QPalette::ColorRole color=QPalette::Base, ColorSet set=View, KSharedConfigPtr=KSharedConfigPtr()) |
static void | adjustForeground (QPalette &, ForegroundRole newRole=NormalText, QPalette::ColorRole color=QPalette::Text, ColorSet set=View, KSharedConfigPtr=KSharedConfigPtr()) |
static qreal | contrastF (const KSharedConfigPtr &config=KSharedConfigPtr()) |
static QPalette | createApplicationPalette (const KSharedConfigPtr &config) |
static bool | isColorSetSupported (const KSharedConfigPtr &config, KColorScheme::ColorSet set) |
static QColor | shade (const QColor &, ShadeRole) |
static QColor | shade (const QColor &, ShadeRole, qreal contrast, qreal chromaAdjust=0.0) |
Detailed Description
A set of methods used to work with colors.
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, KColorScheme::ShadeRole
Definition at line 55 of file kcolorscheme.h.
Member Enumeration Documentation
◆ 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.
Enumerator | |
---|---|
NormalBackground | Normal background. |
AlternateBackground | Alternate background; for example, for use in lists. This color may be the same as BackgroundNormal, especially in sets other than View and Window. |
ActiveBackground | 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. |
LinkBackground | 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). |
VisitedBackground | 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". |
NegativeBackground | Sixth color; for example, errors, untrusted content, etc. |
NeutralBackground | Seventh color; for example, warnings, secure/encrypted content. |
PositiveBackground | Eighth color; for example, success messages, trusted content. |
NBackgroundRoles | Number of background roles.
|
Definition at line 135 of file kcolorscheme.h.
◆ 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.
Enumerator | |
---|---|
View | Views; for example, frames, input fields, etc. If it contains things that can be selected, it is probably a View. |
Window | Non-editable window elements; for example, menus. If it isn't a Button, View, or Tooltip, it is probably a Window. |
Button | 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. |
Selection | 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. |
Tooltip | 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). |
Complementary | 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.
|
Header | Colors for header areas that should be used both by the top toolbar and the titlebar.
|
NColorSets | Number of color sets. Note: don't use this
|
Definition at line 65 of file kcolorscheme.h.
◆ 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.
Definition at line 270 of file kcolorscheme.h.
◆ 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
Definition at line 209 of file kcolorscheme.h.
◆ 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.
Definition at line 295 of file kcolorscheme.h.
Constructor & Destructor Documentation
◆ ~KColorScheme()
|
virtualdefault |
Destructor.
◆ KColorScheme()
|
explicit |
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.
Definition at line 443 of file kcolorscheme.cpp.
Member Function Documentation
◆ adjustBackground()
|
static |
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".
Definition at line 540 of file kcolorscheme.cpp.
◆ adjustForeground()
|
static |
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".
Definition at line 548 of file kcolorscheme.cpp.
◆ background()
QBrush KColorScheme::background | ( | BackgroundRole | role = NormalBackground | ) | const |
Retrieve the requested background brush.
Definition at line 463 of file kcolorscheme.cpp.
◆ contrastF()
|
static |
Returns the contrast for borders as a floating point value.
- Parameters
-
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)
Definition at line 457 of file kcolorscheme.cpp.
◆ createApplicationPalette()
|
static |
Used to obtain the QPalette that will be used to set the application palette from KDE Platform theme.
- Parameters
-
config KConfig from which to load the colors
- Returns
- the QPalette
- Since
- 5.0
Definition at line 580 of file kcolorscheme.cpp.
◆ decoration()
QBrush KColorScheme::decoration | ( | DecorationRole | role | ) | const |
Retrieve the requested decoration brush.
Definition at line 473 of file kcolorscheme.cpp.
◆ foreground()
QBrush KColorScheme::foreground | ( | ForegroundRole | role = NormalText | ) | const |
Retrieve the requested foreground brush.
Definition at line 468 of file kcolorscheme.cpp.
◆ isColorSetSupported()
|
static |
Used to check if the color scheme has a given set.
- Parameters
-
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
- Since
- 5.75
Definition at line 556 of file kcolorscheme.cpp.
◆ operator==()
bool KColorScheme::operator== | ( | const KColorScheme & | other | ) | const |
- Since
- 5.92
Definition at line 448 of file kcolorscheme.cpp.
◆ shade() [1/3]
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 midlight() == shadow(). Conversely, if the base color is very light, the 'light' shades will be darker than the base color, with light() == mid().
Definition at line 483 of file kcolorscheme.cpp.
◆ shade() [2/3]
|
static |
Retrieve the requested shade color, using the specified color as the base color and the specified contrast.
- Parameters
-
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 midlight() == shadow(). Conversely, if the base color is very light, the 'light' shades will be darker than the base color, with light() == mid().
- See also
- KColorUtils::shade
Definition at line 488 of file kcolorscheme.cpp.
◆ shade() [3/3]
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 midlight() == shadow(). Conversely, if the base color is very light, the 'light' shades will be darker than the base color, with light() == mid().
Definition at line 478 of file kcolorscheme.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:05:51 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.