KColorScheme Class Reference

#include <kcolorscheme.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 }
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
QBrush	background (BackgroundRole=NormalBackground) const
QBrush	decoration (DecorationRole) const
QBrush	foreground (ForegroundRole=NormalText) const
	KColorScheme (const KColorScheme &)
	KColorScheme (QPalette::ColorGroup, ColorSet=View, KSharedConfigPtr=KSharedConfigPtr())
KColorScheme &	operator= (const KColorScheme &)
QColor	shade (ShadeRole) const
virtual	~KColorScheme ()

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)

Private Attributes
QExplicitlySharedDataPointer< KColorSchemePrivate >	d

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 52 of file kcolorscheme.h.

Member Enumeration Documentation

BackgroundRole

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.

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.

Definition at line 112 of file kcolorscheme.h.

                        {
        NormalBackground = 0,
        AlternateBackground = 1,
        ActiveBackground = 2,
        LinkBackground = 3,
        VisitedBackground = 4,
        NegativeBackground = 5,
        NeutralBackground = 6,
        PositiveBackground = 7
    };

ColorSet

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.

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).

Definition at line 63 of file kcolorscheme.h.

                  {
        View,
        Window,
        Button,
        Selection,
        Tooltip
    };

DecorationRole

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.

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 237 of file kcolorscheme.h.

                        {
        FocusColor,
        HoverColor
    };

ForegroundRole

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

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	Eighth color; for example, additions, success messages, trusted content.

Definition at line 181 of file kcolorscheme.h.

                        {
        NormalText = 0,
        InactiveText = 1,
        ActiveText = 2,
        LinkText = 3,
        VisitedText = 4,
        NegativeText = 5,
        NeutralText = 6,
        PositiveText = 7
    };

ShadeRole

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.

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 257 of file kcolorscheme.h.

                   {
        LightShade,
        MidlightShade,
        MidShade,
        DarkShade,
        ShadowShade
    };

Constructor & Destructor Documentation

KColorScheme() [1/2]

KColorScheme::KColorScheme

(

const KColorScheme &

other

)

Construct a copy of another KColorScheme.

Definition at line 390 of file kcolorscheme.cpp.

                                                    : d(other.d)
{
}

~KColorScheme()

KColorScheme::~KColorScheme ( )

virtual

Destructor

Definition at line 400 of file kcolorscheme.cpp.

{
}

KColorScheme() [2/2]

KColorScheme::KColorScheme ( 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).

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 404 of file kcolorscheme.cpp.

{
    if (!config) {
        config = KSharedConfig::openConfig();
    }
 
    switch (set) {
    case Window:
        d = new KColorSchemePrivate(config, state, "Colors:Window", defaultWindowColors);
        break;
    case Button:
        d = new KColorSchemePrivate(config, state, "Colors:Button", defaultButtonColors);
        break;
    case Selection: {
        KConfigGroup group(config, "ColorEffects:Inactive");
        // NOTE: keep this in sync with kdebase/workspace/kcontrol/colors/colorscm.cpp
        bool inactiveSelectionEffect = group.readEntry("ChangeSelectionColor", group.readEntry("Enable", true));
        // if enabled, inactiver/disabled uses Window colors instead, ala gtk
        // ...except tinted with the Selection:NormalBackground color so it looks more like selection
        if (state == QPalette::Active || (state == QPalette::Inactive && !inactiveSelectionEffect)) {
            d = new KColorSchemePrivate(config, state, "Colors:Selection", defaultSelectionColors);
        } else if (state == QPalette::Inactive)
            d = new KColorSchemePrivate(config, state, "Colors:Window", defaultWindowColors,
                                        KColorScheme(QPalette::Active, Selection, config).background());
        else { // disabled (...and still want this branch when inactive+disabled exists)
            d = new KColorSchemePrivate(config, state, "Colors:Window", defaultWindowColors);
        }
    } break;
    case Tooltip:
        d = new KColorSchemePrivate(config, state, "Colors:Tooltip", defaultTooltipColors);
        break;
    default:
        d = new KColorSchemePrivate(config, state, "Colors:View", defaultViewColors);
    }
}

References background(), Button, d, defaultButtonColors, defaultSelectionColors, defaultTooltipColors, defaultViewColors, defaultWindowColors, KColorScheme(), Selection, Tooltip, and Window.

Member Function Documentation

adjustBackground()

void KColorScheme::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 533 of file kcolorscheme.cpp.

{
    palette.setBrush(QPalette::Active,   color, KColorScheme(QPalette::Active,   set, config).background(newRole));
    palette.setBrush(QPalette::Inactive, color, KColorScheme(QPalette::Inactive, set, config).background(newRole));
    palette.setBrush(QPalette::Disabled, color, KColorScheme(QPalette::Disabled, set, config).background(newRole));
}

References background(), KColorScheme(), and palette.

adjustForeground()

void KColorScheme::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 541 of file kcolorscheme.cpp.

{
    palette.setBrush(QPalette::Active,   color, KColorScheme(QPalette::Active,   set, config).foreground(newRole));
    palette.setBrush(QPalette::Inactive, color, KColorScheme(QPalette::Inactive, set, config).foreground(newRole));
    palette.setBrush(QPalette::Disabled, color, KColorScheme(QPalette::Disabled, set, config).foreground(newRole));
}

References foreground(), KColorScheme(), and palette.

background()

QBrush KColorScheme::background

(

BackgroundRole

role = NormalBackground

)

const

Retrieve the requested background brush.

Definition at line 457 of file kcolorscheme.cpp.

{
    return d->background(role);
}

References d.

contrast()

int KColorScheme::contrast ( )

static

Returns the contrast for borders.

Returns

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

Definition at line 441 of file kcolorscheme.cpp.

{
    KConfigGroup g(KSharedConfig::openConfig(), "KDE");
    return g.readEntry("contrast", 7);
}

contrastF()

qreal KColorScheme::contrastF ( const KSharedConfigPtr & config = KSharedConfigPtr() )

static

Returns the contrast for borders as a floating point value.

Parameters

config

pointer 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 448 of file kcolorscheme.cpp.

{
    if (config) {
        KConfigGroup g(config, "KDE");
        return 0.1 * g.readEntry("contrast", 7);
    }
    return 0.1 * (qreal)contrast();
}

References contrast().

createApplicationPalette()

QPalette KColorScheme::createApplicationPalette ( const KSharedConfigPtr & config )

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 549 of file kcolorscheme.cpp.

{
    QPalette palette;
 
    static const QPalette::ColorGroup states[3] = { QPalette::Active, QPalette::Inactive, QPalette::Disabled };
 
    // TT thinks tooltips shouldn't use active, so we use our active colors for all states
    KColorScheme schemeTooltip(QPalette::Active, KColorScheme::Tooltip, config);
 
    for (int i = 0; i < 3; i++) {
        QPalette::ColorGroup state = states[i];
        KColorScheme schemeView(state, KColorScheme::View, config);
        KColorScheme schemeWindow(state, KColorScheme::Window, config);
        KColorScheme schemeButton(state, KColorScheme::Button, config);
        KColorScheme schemeSelection(state, KColorScheme::Selection, config);
 
        palette.setBrush(state, QPalette::WindowText, schemeWindow.foreground());
        palette.setBrush(state, QPalette::Window, schemeWindow.background());
        palette.setBrush(state, QPalette::Base, schemeView.background());
        palette.setBrush(state, QPalette::Text, schemeView.foreground());
        palette.setBrush(state, QPalette::Button, schemeButton.background());
        palette.setBrush(state, QPalette::ButtonText, schemeButton.foreground());
        palette.setBrush(state, QPalette::Highlight, schemeSelection.background());
        palette.setBrush(state, QPalette::HighlightedText, schemeSelection.foreground());
        palette.setBrush(state, QPalette::ToolTipBase, schemeTooltip.background());
        palette.setBrush(state, QPalette::ToolTipText, schemeTooltip.foreground());
 
        palette.setColor(state, QPalette::Light, schemeWindow.shade(KColorScheme::LightShade));
        palette.setColor(state, QPalette::Midlight, schemeWindow.shade(KColorScheme::MidlightShade));
        palette.setColor(state, QPalette::Mid, schemeWindow.shade(KColorScheme::MidShade));
        palette.setColor(state, QPalette::Dark, schemeWindow.shade(KColorScheme::DarkShade));
        palette.setColor(state, QPalette::Shadow, schemeWindow.shade(KColorScheme::ShadowShade));
 
        palette.setBrush(state, QPalette::AlternateBase, schemeView.background(KColorScheme::AlternateBackground));
        palette.setBrush(state, QPalette::Link, schemeView.foreground(KColorScheme::LinkText));
        palette.setBrush(state, QPalette::LinkVisited, schemeView.foreground(KColorScheme::VisitedText));
    }
 
    return palette;
}

References AlternateBackground, background(), Button, DarkShade, foreground(), LightShade, LinkText, MidlightShade, MidShade, palette, Selection, shade(), ShadowShade, Tooltip, View, VisitedText, and Window.

decoration()

QBrush KColorScheme::decoration

(

DecorationRole

role

)

const

Retrieve the requested decoration brush.

Definition at line 467 of file kcolorscheme.cpp.

{
    return d->decoration(role);
}

References d.

foreground()

QBrush KColorScheme::foreground

(

ForegroundRole

role = NormalText

)

const

Retrieve the requested foreground brush.

Definition at line 462 of file kcolorscheme.cpp.

{
    return d->foreground(role);
}

References d.

operator=()

KColorScheme & KColorScheme::operator=

(

const KColorScheme &

other

)

Standard assignment operator

Definition at line 394 of file kcolorscheme.cpp.

{
    d = other.d;
    return *this;
}

References d.

shade() [1/3]

QColor KColorScheme::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 477 of file kcolorscheme.cpp.

{
    return shade(color, role, KColorScheme::contrastF());
}

References contrastF(), and shade().

shade() [2/3]

QColor KColorScheme::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

color	the shade color
role	the shade role
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 482 of file kcolorscheme.cpp.

{
    // nan -> 1.0
    contrast = (1.0 > contrast ? (-1.0 < contrast ? contrast : -1.0) : 1.0);
    qreal y = KColorUtils::luma(color), yi = 1.0 - y;
 
    // handle very dark colors (base, mid, dark, shadow == midlight, light)
    if (y < 0.006) {
        switch (role) {
        case KColorScheme::LightShade:
            return KColorUtils::shade(color, 0.05 + 0.95 * contrast, chromaAdjust);
        case KColorScheme::MidShade:
            return KColorUtils::shade(color, 0.01 + 0.20 * contrast, chromaAdjust);
        case KColorScheme::DarkShade:
            return KColorUtils::shade(color, 0.02 + 0.40 * contrast, chromaAdjust);
        default:
            return KColorUtils::shade(color, 0.03 + 0.60 * contrast, chromaAdjust);
        }
    }
 
    // handle very light colors (base, midlight, light == mid, dark, shadow)
    if (y > 0.93) {
        switch (role) {
        case KColorScheme::MidlightShade:
            return KColorUtils::shade(color, -0.02 - 0.20 * contrast, chromaAdjust);
        case KColorScheme::DarkShade:
            return KColorUtils::shade(color, -0.06 - 0.60 * contrast, chromaAdjust);
        case KColorScheme::ShadowShade:
            return KColorUtils::shade(color, -0.10 - 0.90 * contrast, chromaAdjust);
        default:
            return KColorUtils::shade(color, -0.04 - 0.40 * contrast, chromaAdjust);
        }
    }
 
    // handle everything else
    qreal lightAmount = (0.05 + y * 0.55) * (0.25 + contrast * 0.75);
    qreal darkAmount = (- y) * (0.55 + contrast * 0.35);
    switch (role) {
    case KColorScheme::LightShade:
        return KColorUtils::shade(color, lightAmount, chromaAdjust);
    case KColorScheme::MidlightShade:
        return KColorUtils::shade(color, (0.15 + 0.35 * yi) * lightAmount, chromaAdjust);
    case KColorScheme::MidShade:
        return KColorUtils::shade(color, (0.35 + 0.15 * y) * darkAmount, chromaAdjust);
    case KColorScheme::DarkShade:
        return KColorUtils::shade(color, darkAmount, chromaAdjust);
    default:
        return KColorUtils::darken(KColorUtils::shade(color, darkAmount, chromaAdjust), 0.5 + 0.3 * y);
    }
}

References contrast(), DarkShade, LightShade, MidlightShade, MidShade, and ShadowShade.

shade() [3/3]

QColor KColorScheme::shade

(

ShadeRole

role

)

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 (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 472 of file kcolorscheme.cpp.

{
    return shade(background().color(), role, d->contrast());
}

References background(), d, and shade().

Member Data Documentation

d

QExplicitlySharedDataPointer<KColorSchemePrivate> KColorScheme::d

private

Definition at line 427 of file kcolorscheme.h.

---

The documentation for this class was generated from the following files:

• libs/widgetutils/config/kcolorscheme.h
• libs/widgetutils/config/kcolorscheme.cpp