KColorScheme Class Reference

from PyKDE4.kdeui import *

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

Enumerations
BackgroundRole	{ NormalBackground, AlternateBackground, ActiveBackground, LinkBackground, VisitedBackground, NegativeBackground, NeutralBackground, PositiveBackground }
ColorSet	{ View, Window, Button, Selection, Tooltip }
DecorationRole	{ FocusColor, HoverColor }
ForegroundRole	{ NormalText, InactiveText, ActiveText, LinkText, VisitedText, NegativeText, NeutralText, PositiveText }
ShadeRole	{ LightShade, MidlightShade, MidShade, DarkShade, ShadowShade }
Methods
	__init__ (self, KColorScheme a0)
	__init__ (self, QPalette::ColorGroup a0, KColorScheme.ColorSet a1=KColorScheme.View, KSharedPtr a2=KSharedConfigPtr())
QBrush	background (self, KColorScheme.BackgroundRole a0=KColorScheme.NormalBackground)
QBrush	decoration (self, KColorScheme.DecorationRole a0)
QBrush	foreground (self, KColorScheme.ForegroundRole a0=KColorScheme.NormalText)
QColor	shade (self, KColorScheme.ShadeRole a0)
Static Methods
	adjustBackground (QPalette a0, KColorScheme.BackgroundRole newRole=KColorScheme.NormalBackground, QPalette::ColorRole color=QPalette.Base, KColorScheme.ColorSet set=KColorScheme.View, KSharedPtr a4=KSharedConfigPtr())
	adjustForeground (QPalette a0, KColorScheme.ForegroundRole newRole=KColorScheme.NormalText, QPalette::ColorRole color=QPalette.Text, KColorScheme.ColorSet set=KColorScheme.View, KSharedPtr a4=KSharedConfigPtr())
QColor	shade (QColor a0, KColorScheme.ShadeRole a1)
QColor	shade (QColor a0, KColorScheme.ShadeRole a1, float contrast, float chromaAdjust=0.0)

Method Documentation

__init__	(	self,
		KColorScheme	a0
	)

Construct a copy of another KColorScheme.

__init__	(	self,
		QPalette::ColorGroup	a0,
		KColorScheme.ColorSet	a1=KColorScheme.View,
		KSharedPtr	a2=KSharedConfigPtr()
	)

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.

QBrush background	(	self,
		KColorScheme.BackgroundRole	a0=KColorScheme.NormalBackground
	)

Retrieve the requested background brush.

QBrush decoration	(	self,
		KColorScheme.DecorationRole	a0
	)

Retrieve the requested decoration brush.

QBrush foreground	(	self,
		KColorScheme.ForegroundRole	a0=KColorScheme.NormalText
	)

Retrieve the requested foreground brush.

QColor shade	(	self,
		KColorScheme.ShadeRole	a0
	)

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

Static Method Documentation

adjustBackground	(	QPalette	a0,
		KColorScheme.BackgroundRole	newRole=KColorScheme.NormalBackground,
		QPalette::ColorRole	color=QPalette.Base,
		KColorScheme.ColorSet	set=KColorScheme.View,
		KSharedPtr	a4=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".

adjustForeground	(	QPalette	a0,
		KColorScheme.ForegroundRole	newRole=KColorScheme.NormalText,
		QPalette::ColorRole	color=QPalette.Text,
		KColorScheme.ColorSet	set=KColorScheme.View,
		KSharedPtr	a4=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".

QColor shade	(	QColor	a0,
		KColorScheme.ShadeRole	a1
	)

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

QColor shade	(	QColor	a0,
		KColorScheme.ShadeRole	a1,
		float	contrast,
		float	chromaAdjust=0.0
	)

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

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 = 0
AlternateBackground = 1
ActiveBackground = 2
LinkBackground = 3
VisitedBackground = 4
NegativeBackground = 5
NeutralBackground = 6
PositiveBackground = 7

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
Window
Button
Selection
Tooltip

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
HoverColor

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 = 0
InactiveText = 1
ActiveText = 2
LinkText = 3
VisitedText = 4
NegativeText = 5
NeutralText = 6
PositiveText = 7

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
MidlightShade
MidShade
DarkShade
ShadowShade

KColorScheme Class Reference

Detailed Description

Enumerations

Methods

Static Methods

Method Documentation

Static Method Documentation

Enumeration Documentation

Modules