KDE 4.2 PyKDE API Reference

- KDE's Python API

# KColorUtils Namespace Reference

`from PyKDE4.kdeui.KColorUtils import *`

## Detailed Description

A set of methods used to work with colors.

## Functions

float | contrastRatio (QColor a0, QColor a1)
QColor | darken (QColor a0, float amount=0.5, float chromaGain=1.0)
QColor | lighten (QColor a0, float amount=0.5, float chromaInverseGain=1.0)
float | luma (QColor a0)
QColor | mix (QColor c1, QColor c2, float bias=0.5)
QColor | overlayColors (QColor base, QColor paint, QPainter.CompositionMode comp=QPainter.CompositionMode_SourceOver)
QColor | shade (QColor a0, float lumaAmount, float chromaAmount=0.0)
QColor | tint (QColor base, QColor color, float amount=0.3)

## Function Documentation

float contrastRatio | ( | QColor | a0,
|  | QColor | a1
| ) |  |  |

Calculate the contrast ratio between two colors, according to the W3C/WCAG2.0 algorithm, (Lmax + 0.05)/(Lmin + 0.05), where Lmax and Lmin are the luma values of the lighter color and the darker color, respectively.

A contrast ration of 5:1 (result == 5.0) is the minimum for "normal" text to be considered readable (large text can go as low as 3:1). The ratio ranges from 1:1 (result == 1.0) to 21:1 (result == 21.0).

See also:
  KColorUtils.luma

QColor darken | ( | QColor | a0,
|  | float | amount=0.5,
|  | float | chromaGain=1.0
| ) |  |  |

Adjust the luma of a color by changing its distance from black.

- amount == 1.0 gives black
- amount == 0.5 results in a color whose luma is halfway between 0.0
and that of the original color
- amount == 0.0 gives the original color
- amount == -1.0 gives a color that is 'twice as far from black' as
the original color, that is luma(result) == 2*luma(color)

Parameters:

  | amount | factor by which to adjust the luma component of the color
  | chromaGain | (optional) factor by which to adjust the chroma component of the color; 1.0 means no change, 0.0 minimizes chroma

See also:
  KColorUtils.shade

QColor lighten | ( | QColor | a0,
|  | float | amount=0.5,
|  | float | chromaInverseGain=1.0
| ) |  |  |

Adjust the luma of a color by changing its distance from white.

- amount == 1.0 gives white
- amount == 0.5 results in a color whose luma is halfway between 1.0
and that of the original color
- amount == 0.0 gives the original color
- amount == -1.0 gives a color that is 'twice as far from white' as
the original color, that is luma(result) == 1.0 - 2*(1.0 - luma(color))

Parameters:

  | amount | factor by which to adjust the luma component of the color
  | chromaInverseGain | (optional) factor by which to adjust the chroma component of the color; 1.0 means no change, 0.0 maximizes chroma

See also:
  KColorUtils.shade

float luma | ( | QColor | a0
| ) |  |  |

Calculate the luma of a color. Luma is weighted sum of gamma-adjusted R'G'B' components of a color. The result is similar to qGray. The range is from 0.0 (black) to 1.0 (white).

KColorUtils.darken(), KColorUtils.lighten() and KColorUtils.shade() operate on the luma of a color.

See also:
  http://en.wikipedia.org/wiki/Luma_(video)

QColor mix | ( | QColor | c1,
|  | QColor | c2,
|  | float | bias=0.5
| ) |  |  |

Blend two colors into a new color by linear combination.

    QColor lighter = KColorUtils.mix(myColor, Qt.white)

Parameters:

  | c1 | first color.
  | c2 | second color.
  | bias | weight to be used for the mix. bias <= 0 gives c1, bias >= 1 gives c2. bias == 0.5 gives a 50% blend of c1 and c2.

QColor overlayColors | ( | QColor | base,
|  | QColor | paint,
|  | QPainter.CompositionMode | comp=QPainter.CompositionMode_SourceOver
| ) |  |  |

Blend two colors into a new color by painting the second color over the first using the specified composition mode.

    QColor white(Qt.white);
    white.setAlphaF(0.5);
    QColor lighter = KColorUtils.overlayColors(myColor, white);

Parameters:

  | base | the base color (alpha channel is ignored).
  | paint | the color to be overlayed onto the base color.
  | comp | the CompositionMode used to do the blending.

QColor shade | ( | QColor | a0,
|  | float | lumaAmount,
|  | float | chromaAmount=0.0
| ) |  |  |

Adjust the luma and chroma components of a color. The amount is added to the corresponding component.

Parameters:

  | lumaAmount | amount by which to adjust the luma component of the color; 0.0 results in no change, -1.0 turns anything black, 1.0 turns anything white
  | chromaAmount | (optional) amount by which to adjust the chroma component of the color; 0.0 results in no change, -1.0 minimizes chroma, 1.0 maximizes chroma

See also:
  KColorUtils.luma

QColor tint | ( | QColor | base,
|  | QColor | color,
|  | float | amount=0.3
| ) |  |  |

Create a new color by tinting one color with another. This function is meant for creating additional colors withing the same class (background, foreground) from colors in a different class. Therefore when amount is low, the luma of base is mostly preserved, while the hue and chroma of color is mostly inherited.

Parameters:

  | base | color to be tinted
  | color | color with which to tint
  | amount | how strongly to tint the base; 0.0 gives base, 1.0 gives color