• Skip to content
  • Skip to link menu
KDE 4.1 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KDEUI

KColorScheme Class Reference

#include <kcolorscheme.h>

List of all members.


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). As of KDE4, this class is the correct way to look up colors from the system palette, as opposed to KGlobalSettings (such usage is deprecated). It greatly expands on KGlobalSettings and 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:
Historically, it was not needed for applications to give much concern to the state of a widget (active, inactive, disabled) since only the disabled state was different, and only slightly. As a result, the old KGlobalSettings color getters did not care about the widget state. However, starting with KDE4, the color palettes for the various states 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 71 of file 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 (QPalette::ColorGroup, ColorSet=View, KSharedConfigPtr=KSharedConfigPtr())
 KColorScheme (const KColorScheme &)
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 QColor shade (const QColor &, ShadeRole, qreal contrast, qreal chromaAdjust=0.0)
static QColor shade (const QColor &, ShadeRole)

Member Enumeration 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.

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

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

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

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.

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.

VisitedText  Fifth color; used for (visited) links.

As with LinkText, may be used for clickable items that have been clicked, or otherwise accessed, already.

NegativeText  Sixth color; for example, errors, untrusted content, etc.
NeutralText  Seventh color; for example, warnings, secure/encrypted content.
PositiveText  Eigth color; for example, success messages, trusted content.

Definition at line 194 of file kcolorscheme.h.

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


Constructor & Destructor Documentation

KColorScheme::KColorScheme ( const KColorScheme &  other  ) 

Construct a copy of another KColorScheme.

Definition at line 400 of file kcolorscheme.cpp.

KColorScheme::~KColorScheme (  )  [virtual]

Destructor.

Definition at line 410 of file kcolorscheme.cpp.

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


Member Function Documentation

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

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

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

Retrieve the requested background brush.

Definition at line 448 of file kcolorscheme.cpp.

QBrush KColorScheme::decoration ( DecorationRole  role  )  const

Retrieve the requested decoration brush.

Definition at line 458 of file kcolorscheme.cpp.

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

Retrieve the requested foreground brush.

Definition at line 453 of file kcolorscheme.cpp.

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

Standard assignment operator.

Definition at line 404 of file kcolorscheme.cpp.

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:
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 KGlobalSettings::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 473 of file kcolorscheme.cpp.

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

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


The documentation for this class was generated from the following files:
  • kcolorscheme.h
  • kcolorscheme.cpp

KDEUI

Skip menu "KDEUI"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • KIO
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • Kross
  • KUtils
  • Nepomuk
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.5.4
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal