SchemeManager

Search for usage in LXR

#include <schememanager.h>

Public Types

enum  BackgroundRole {
  NormalBackground = 0, AlternateBackground = 1, ActiveBackground = 2, LinkBackground = 3,
  VisitedBackground = 4, NegativeBackground = 5, NeutralBackground = 6, PositiveBackground = 7
}
 
enum  ColorSet {
  View, Window, Button, Selection,
  Tooltip, Complementary
}
 
enum  DecorationRole { FocusColor, HoverColor }
 
enum  ForegroundRole {
  NormalText = 0, InactiveText = 1, ActiveText = 2, LinkText = 3,
  VisitedText = 4, NegativeText = 5, NeutralText = 6, PositiveText = 7
}
 
enum  ShadeRole {
  LightShade, MidlightShade, MidShade, DarkShade,
  ShadowShade
}
 

Public Member Functions

 SchemeManager (const SchemeManager &)
 
 SchemeManager (QPalette::ColorGroup, ColorSet=View, KSharedConfigPtr=KSharedConfigPtr())
 
QBrush background (BackgroundRole=NormalBackground) const
 
QBrush decoration (DecorationRole) const
 
QBrush foreground (ForegroundRole=NormalText) const
 
SchemeManageroperator= (const SchemeManager &)
 
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 int contrast ()
 
static qreal contrastF (const KSharedConfigPtr &config=KSharedConfigPtr())
 
static QPalette createApplicationPalette (const KSharedConfigPtr &config)
 
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.

SchemeManager 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 SchemeManager 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 SchemeManager constructor requires a QPalette::ColorGroup as an argument.

To facilitate working with potentially-varying states, two convenience API's are provided. These are SchemeManager::adjustBackground and its sister SchemeManager::adjustForeground, and the helper class KStatefulBrush.

See also
SchemeManager::ColorSet, SchemeManager::ForegroundRole, SchemeManager::BackgroundRole, SchemeManager::DecorationRole, SchemeManager::ShadeRole

Definition at line 52 of file schememanager.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 SchemeManager::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 

Eigth color; for example, success messages, trusted content.

Definition at line 123 of file schememanager.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.

Since
5.19

Definition at line 63 of file schememanager.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.

Enumerator
FocusColor 

Color used to draw decorations for items which have input focus.

HoverColor 

Color used to draw decorations for items which will be activated by clicking.

Definition at line 250 of file schememanager.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
Enumerator
NormalText 

Normal foreground.

InactiveText 

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.

ActiveText 

Third color; for example items which are new, active, requesting attention, etc.

May be used as a hover color for clickable items.

LinkText 

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.

VisitedText 

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.

NegativeText 

Sixth color; for example, errors, untrusted content, deletions, etc.

NeutralText 

Seventh color; for example, warnings, secure/encrypted content.

PositiveText 

Eigth color; for example, additions, success messages, trusted content.

Definition at line 193 of file schememanager.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.

Enumerator
LightShade 

The light color is lighter than dark() or shadow() and contrasts with the base color.

MidlightShade 

The midlight color is in between base() and light().

MidShade 

The mid color is in between base() and dark().

DarkShade 

The dark color is in between mid() and shadow().

ShadowShade 

The shadow color is darker than light() or midlight() and contrasts the base color.

Definition at line 271 of file schememanager.h.

Constructor & Destructor Documentation

◆ SchemeManager() [1/2]

SchemeManager::SchemeManager ( const SchemeManager other)

Construct a copy of another SchemeManager.

Definition at line 884 of file schememanager.cpp.

◆ SchemeManager() [2/2]

SchemeManager::SchemeManager ( QPalette::ColorGroup  state,
ColorSet  set = View,
KSharedConfigPtr  config = KSharedConfigPtr() 
)
explicit

Construct a palette from given color set and state, using the colors from the given KConfig (if null, the system colors are used).

Definition at line 898 of file schememanager.cpp.

Member Function Documentation

◆ adjustBackground()

void SchemeManager::adjustBackground ( QPalette palette,
BackgroundRole  newRole = NormalBackground,
QPalette::ColorRole  color = QPalette::Base,
ColorSet  set = View,
KSharedConfigPtr  config = KSharedConfigPtr() 
)
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 1051 of file schememanager.cpp.

◆ adjustForeground()

void SchemeManager::adjustForeground ( QPalette palette,
ForegroundRole  newRole = NormalText,
QPalette::ColorRole  color = QPalette::Text,
ColorSet  set = View,
KSharedConfigPtr  config = KSharedConfigPtr() 
)
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 1059 of file schememanager.cpp.

◆ background()

QBrush SchemeManager::background ( BackgroundRole  role = NormalBackground) const

Retrieve the requested background brush.

Definition at line 966 of file schememanager.cpp.

◆ contrast()

int SchemeManager::contrast ( )
static

Returns the contrast for borders.

Returns
the contrast (between 0 for minimum and 10 for maximum contrast)

Definition at line 947 of file schememanager.cpp.

◆ contrastF()

qreal SchemeManager::contrastF ( const KSharedConfigPtr &  config = KSharedConfigPtr())
static

Returns the contrast for borders as a floating point value.

Parameters
configpointer to the config from which to read the contrast setting (the default is to use KSharedConfig::openConfig())
Returns
the contrast (between 0.0 for minimum and 1.0 for maximum contrast)

Definition at line 954 of file schememanager.cpp.

◆ createApplicationPalette()

QPalette SchemeManager::createApplicationPalette ( const KSharedConfigPtr &  config)
static

Used to obtain the QPalette that will be used to set the application palette from KDE Platform theme.

Parameters
configKConfig from which to load the colors
Returns
the QPalette

Definition at line 1067 of file schememanager.cpp.

◆ decoration()

QBrush SchemeManager::decoration ( DecorationRole  role) const

Retrieve the requested decoration brush.

Definition at line 976 of file schememanager.cpp.

◆ foreground()

QBrush SchemeManager::foreground ( ForegroundRole  role = NormalText) const

Retrieve the requested foreground brush.

Definition at line 971 of file schememanager.cpp.

◆ operator=()

SchemeManager & SchemeManager::operator= ( const SchemeManager other)

Standard assignment operator.

Definition at line 892 of file schememanager.cpp.

◆ shade() [1/3]

QColor SchemeManager::shade ( const QColor color,
ShadeRole  role 
)
static

Retrieve the requested shade color, using the specified color as the base color and the system 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 986 of file schememanager.cpp.

◆ shade() [2/3]

QColor SchemeManager::shade ( const QColor color,
ShadeRole  role,
qreal  contrast,
qreal  chromaAdjust = 0.0 
)
static

Retrieve the requested shade color, using the specified color as the base color and the specified contrast.

Parameters
colorThe base color
roleThe shade role
contrastAmount 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 SchemeManager::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().

Definition at line 991 of file schememanager.cpp.

◆ shade() [3/3]

QColor SchemeManager::shade ( ShadeRole  role) const

Retrieve the requested shade color, using SchemeManager::background(SchemeManager::NormalBackground) as the base color and the contrast setting from the KConfig used to create this SchemeManager instance (the system contrast setting, if no KConfig was specified).

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 981 of file schememanager.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Thu Aug 18 2022 03:56:49 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.