QColor Class Reference
^{[QtGui module]}

HSV Colors

Because many people don't know the HSV color model very well, we'll cover it briefly here.

The RGB model is hardware-oriented. Its representation is close to what most monitors show. In contrast, HSV represents color in a way more suited to the human perception of color. For example, the relationships "stronger than", "darker than", and "the opposite of" are easily expressed in HSV but are much harder to express in RGB.

HSV, like RGB, has three components:

• H, for hue, is in the range 0 to 359 if the color is chromatic (not gray), or meaningless if it is gray. It represents degrees on the color wheel familiar to most people. Red is 0 (degrees), green is 120, and blue is 240.
• S, for saturation, is in the range 0 to 255, and the bigger it is, the stronger the color is. Grayish colors have saturation near 0; very strong colors have saturation near 255.
• V, for value, is in the range 0 to 255 and represents lightness or brightness of the color. 0 is black; 255 is as far from black as possible.

Here are some examples: pure red is H=0, S=255, V=255; a dark red, moving slightly towards the magenta, could be H=350 (equivalent to -10), S=255, V=180; a grayish light red could have H about 0 (say 350-359 or 0-10), S about 50-100, and S=255.

Qt returns a hue value of -1 for achromatic colors. If you pass a hue value that is too large, Qt forces it into range. Hue 360 or 720 is treated as 0; hue 540 is treated as 180.

See also QPalette and QApplication::setColorSpec().

Member Type Documentation

enum QColor::Spec

The type of color specified, either RGB, HSV or CMYK.

Member Function Documentation

QColor::QColor ()

Constructs an invalid color with the RGB value (0, 0, 0). An invalid color is a color that is not properly set up for the underlying window system.

The alpha value of an invalid color is unspecified.

See also isValid().

QColor::QColor ( int r, int g, int b, int a = 255 )

Constructs a color with the RGB value r, g, b, and the alpha-channel (transparency) value of a, in the same way as setRgb().

The color is left invalid if any of the arguments are invalid.

See also setRgba().

QColor::QColor ( QRgb color )

Constructs a color with the value color. The alpha component is ignored and set to solid.

See also fromRgb().

QColor::QColor ( const QString & name )

Constructs a named color in the same way as setNamedColor() using the name given.

The color is left invalid if the name cannot be parsed.

See also setNamedColor().

QColor::QColor ( const char * name )

Constructs a named color in the same way as setNamedColor() using the name given.

The color is left invalid if the name cannot be parsed.

See also setNamedColor().

QColor::QColor ( const QColor & color )

Constructs a color that is a copy of color.

QColor::QColor ( Qt::GlobalColor color )

Constructs a new color with a color value of color.

int QColor::alpha () const

Returns the alpha color component of this color.

See also setAlpha(), alphaF(), red(), green(), and blue().

qreal QColor::alphaF () const

Returns the alpha color component of this color.

See also setAlphaF(), alpha(), redF(), greenF(), and blueF().

int QColor::black () const

Returns the black color component of this color.

See also blackF(), cyan(), magenta(), yellow(), and alpha().

qreal QColor::blackF () const

Returns the black color component of this color.

See also black(), cyanF(), magentaF(), yellowF(), and alphaF().

int QColor::blue () const

Returns the blue color component of this color.

See also setBlue(), blueF(), red(), green(), and alpha().

qreal QColor::blueF () const

Returns the blue color component of this color.

See also setBlueF(), blue(), redF(), greenF(), and alphaF().

QStringList QColor::colorNames ()   [static]

Returns a QStringList containing the color names Qt knows about.

QColor QColor::convertTo ( Spec colorSpec ) const

Converts the color to the color format specified by colorSpec

int QColor::cyan () const

Returns the cyan color component of this color.

See also cyanF(), black(), magenta(), yellow(), and alpha().

qreal QColor::cyanF () const

Returns the cyan color component of this color.

See also cyan(), blackF(), magentaF(), yellowF(), and alphaF().

QColor QColor::dark ( int factor = 200 ) const

Returns a darker (or lighter) color, but does not change this object.

Returns a darker color if factor is greater than 100. Setting factor to 300 returns a color that has one-third the brightness.

Returns a lighter color if factor is less than 100. We recommend using light() for this purpose. If factor is 0 or negative, the return value is unspecified.

(This function converts the current RGB color to HSV, divides V by factor and converts back to RGB.)

See also light().

QColor QColor::fromCmyk ( int c, int m, int y, int k, int a = 255 )   [static]

Static convenience function that returns a QColor constructed from the CMYK color values, c (cyan), m (magenta), y (yellow), k (black), and a (alpha-channel, i.e. transparency).

All the values must be in the range 0-255.

See also toCmyk(), fromHsv(), and fromRgb().

QColor QColor::fromCmykF ( qreal c, qreal m, qreal y, qreal k, qreal a = 1.0 )   [static]

Static convenience function that returns a QColor constructed from the CMYK color values, c (cyan), m (magenta), y (yellow), k (black), and a (alpha-channel, i.e. transparency).

All the values must be in the range 0.0-1.0.

See also toCmyk(), fromHsv(), and fromRgb().

QColor QColor::fromHsv ( int h, int s, int v, int a = 255 )   [static]

Static convenience function that returns a QColor constructed from the HSV color values, h (hue), s (saturation), v (value), and a (alpha-channel, i.e. transparency).

The value of s, v, and a must all be in the range 0-255; the value of h must be in the range 0-360.

See also toHsv(), fromCmyk(), and fromRgb().

QColor QColor::fromHsvF ( qreal h, qreal s, qreal v, qreal a = 1.0 )   [static]

Static convenience function that returns a QColor constructed from the HSV color values, h (hue), s (saturation), v (value), and a (alpha-channel, i.e. transparency).

The value of h, s and v must all be in the range 0.0-1.0.

See also toHsv(), fromCmyk(), and fromRgb().

QColor QColor::fromRgb ( QRgb rgb )   [static]

Creates a color from the argb value rgb.

The alpha component of rgb is ignored. For conversion from an RGBA value use fromRgba().

See also fromRgba().

QColor QColor::fromRgb ( int r, int g, int b, int a = 255 )   [static]

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Static convenience function that returns a QColor constructed from the RGB color values, r (red), g (green), b (blue), and a (alpha-channel, i.e. transparency).

All the values must be in the range 0-255.

See also toRgb(), fromCmyk(), and fromHsv().

QColor QColor::fromRgbF ( qreal r, qreal g, qreal b, qreal a = 1.0 )   [static]

Static convenience function that returns a QColor constructed from the RGB color values, r (red), g (green), b (blue), and a (alpha-channel, i.e. transparency).

All the values must be in the range 0.0-1.0.

See also toRgb(), fromCmyk(), and fromHsv().

QColor QColor::fromRgba ( QRgb rgba )   [static]

Creates a color from the rgba value rgba.

See also fromRgb().

void QColor::getCmyk ( int * c, int * m, int * y, int * k, int * a = 0 )

Sets the contents pointed to by c, m, y, k, and a, to the cyan, magenta, yellow, black, and alpha-channel (transparency) components of the CMYK value.

See also setCmyk(), getRgb(), and getHsv().

void QColor::getCmykF ( qreal * c, qreal * m, qreal * y, qreal * k, qreal * a = 0 )

Sets the contents pointed to by c, m, y, k, and a, to the cyan, magenta, yellow, black, and alpha-channel (transparency) components of the CMYK value.

See also setCmyk(), getRgb(), and getHsv().

void QColor::getHsv ( int * h, int * s, int * v, int * a = 0 ) const

Returns the current RGB value as HSV. The contents of the h, s, and v pointers are set to the HSV values, and the contents of a is set to the alpha-channel (transparency) value. If any of the pointers are null, the function does nothing.

The hue (which h points to) is set to -1 if the color is achromatic.

Warning: Colors are stored internally as RGB values, so getHSv() may return slightly different values to those set by setHsv().

See also setHsv() and rgb().

void QColor::getHsvF ( qreal * h, qreal * s, qreal * v, qreal * a = 0 ) const

Returns the current RGB value as HSV. The contents of the h, s, and v pointers are set to the HSV values, and the contents of a is set to the alpha-channel (transparency) value. If any of the pointers are null, the function does nothing.

See also setHsv() and rgb().

void QColor::getRgb ( int * r, int * g, int * b, int * a = 0 ) const

Sets the contents pointed to by r, g, b, and a, to the red, green, blue, and alpha-channel (transparency) components of the RGB value.

See also rgb(), setRgb(), and getHsv().

void QColor::getRgbF ( qreal * r, qreal * g, qreal * b, qreal * a = 0 ) const

Sets the contents pointed to by r, g, b, and a, to the red, green, blue, and alpha-channel (transparency) components of the RGB value.

See also rgb(), setRgb(), and getHsv().

int QColor::green () const

Returns the green color component of this color.

See also setGreen(), greenF(), red(), blue(), and alpha().

qreal QColor::greenF () const

Returns the green color component of this color.

See also setGreenF(), green(), redF(), blueF(), and alphaF().

int QColor::hue () const

Returns the hue color component of this color.

See also hueF(), saturation(), value(), and alpha().

qreal QColor::hueF () const

Returns the hue color component of this color.

See also hue(), saturationF(), valueF(), and alphaF().

bool QColor::isValid () const

Returns true if the color is valid; otherwise returns false.

If the color was constructed using the default constructor, false is returned.

QColor QColor::light ( int factor = 150 ) const

Returns a lighter (or darker) color, but does not change this object.

Returns a lighter color if factor is greater than 100. Setting factor to 150 returns a color that is 50% brighter.

Returns a darker color if factor is less than 100. We recommend using dark() for this purpose. If factor is 0 or negative, the return value is unspecified.

(This function converts the current RGB color to HSV, multiplies V by factor, and converts the result back to RGB.)

See also dark().

int QColor::magenta () const

Returns the magenta color component of this color.

See also magentaF(), cyan(), black(), yellow(), and alpha().

qreal QColor::magentaF () const

Returns the magenta color component of this color.

See also magenta(), cyanF(), blackF(), yellowF(), and alphaF().

QString QColor::name () const

Returns the name of the color in the format "#AARRGGBB"; i.e. a "#" character followed by three two-digit hexadecimal numbers.

See also setNamedColor().

int QColor::red () const

Returns the red color component of this color.

See also setRed(), redF(), green(), blue(), and alpha().

qreal QColor::redF () const

Returns the red color component of this color.

See also setRedF(), red(), greenF(), blueF(), and alphaF().

QRgb QColor::rgb () const

Returns the RGB value of the color. The alpha is stripped for compatibility.

The return type QRgb is equivalent to unsigned int.

For an invalid color, the alpha value of the returned color is unspecified.

See also setRgb(), getHsv(), qRed(), qBlue(), qGreen(), and isValid().

QRgb QColor::rgba () const

Returns the RGB value of the color. Note that unlike rgb(), the alpha is not stripped.

The return type QRgb is equivalent to unsigned int.

For an invalid color, the alpha value of the returned color is unspecified.

See also setRgb(), setRgba(), getHsv(), qRed(), qBlue(), qGreen(), and isValid().

int QColor::saturation () const

Returns the saturation color component of this color.

See also saturationF(), hue(), value(), and alpha().

qreal QColor::saturationF () const

Returns the saturation color component of this color.

See also saturation(), hueF(), valueF(), and alphaF().

void QColor::setAlpha ( int alpha )

Sets the alpha of this color to alpha. Integer alpha is specified in the range 0-255.

See also alpha().

void QColor::setAlphaF ( qreal alpha )

Sets the alpha of this color to alpha. Qreal alpha is specified in the range 0-1.

See also alphaF().

void QColor::setBlue ( int blue )

Sets the blue color component of this color to blue. Int components are specified in the range 0-255.

See also blue().

void QColor::setBlueF ( qreal blue )

Sets the blue color component of this color to blue. Float components are specified in the range 0-1.

See also blueF().

void QColor::setCmyk ( int c, int m, int y, int k, int a = 255 )

Sets the color to CMYK values, c (cyan), m (magenta), y (yellow), k (black), and a (alpha-channel, i.e. transparency).

All the values must be in the range 0-255.

See also getCmyk(), setRgb(), and setHsv().

void QColor::setCmykF ( qreal c, qreal m, qreal y, qreal k, qreal a = 1.0 )

Sets the color to CMYK values, c (cyan), m (magenta), y (yellow), k (black), and a (alpha-channel, i.e. transparency).

All the values must be in the range 0.0-1.0.

See also getCmyk(), setRgb(), and setHsv().

void QColor::setGreen ( int green )

Sets the green color component of this color to green. Int components are specified in the range 0-255.

See also green().

void QColor::setGreenF ( qreal green )

Sets the green color component of this color to green. Float components are specified in the range 0-1.

See also greenF().

void QColor::setHsv ( int h, int s, int v, int a = 255 )

Sets a HSV color value; h is the hue, s is the saturation, v is the value and a is the alpha component of the HSV color.

If s, v or a are not in the range 0 to 255, or h is < -1, the color is not changed.

See also hsv(), getHsv(), and setRgb().

void QColor::setHsvF ( qreal h, qreal s, qreal v, qreal a = 1.0 )

The value of h, s, v, and a must all be in the range 0.0-1.0.

void QColor::setNamedColor ( const QString & name )

Sets the RGB value to name, which may be in one of these formats:

• #RGB (each of R, G, and B is a single hex digit)
• #RRGGBB
• #RRRGGGBBB
• #RRRRGGGGBBBB
• A name from the X color database (rgb.txt) (e.g. "steelblue" or "gainsboro"). These color names work on all platforms.

The color is invalid if name cannot be parsed.

void QColor::setRed ( int red )

Sets the red color component of this color to red. Int components are specified in the range 0-255.

See also red().

void QColor::setRedF ( qreal red )

Sets the red color component of this color to red. Float components are specified in the range 0-1.

See also redF().

void QColor::setRgb ( int r, int g, int b, int a = 255 )

Sets the RGB value to r, g, b and the alpha value to a. The arguments, r, g, b and a must all be in the range 0 to 255. The color becomes invalid if any of them are outside the legal range.

See also rgb() and setHsv().

void QColor::setRgb ( QRgb rgb )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Sets the RGB value to rgb, ignoring the alpha.

The type QRgb is equivalent to unsigned int.

See also rgb() and setHsv().

void QColor::setRgbF ( qreal r, qreal g, qreal b, qreal a = 1.0 )

Sets the color channels of this color to r (red), g (green), b (blue) and a (alpha, transparency).

All values must be in the range 0.0-1.0.

void QColor::setRgba ( QRgb rgba )

Sets the RGBA value to rgba. Note that unlike setRgb(QRgb rgb), this function does not ignore the alpha.

The type QRgb is equivalent to unsigned int.

See also rgba().

Spec QColor::spec () const

Returns how the color was specified.

QColor QColor::toCmyk () const

Returns a CMYK QColor based on this color.

See also fromCmyk(), toHsv(), and toRgb().

QColor QColor::toHsv () const

Returns an HSV QColor based on this color.

See also fromHsv(), toCmyk(), and toRgb().

QColor QColor::toRgb () const

Returns an RGB QColor based on this color.

See also fromRgb(), toCmyk(), and toHsv().

int QColor::value () const

Returns the value color component of this color.

See also valueF(), hue(), saturation(), and alpha().

qreal QColor::valueF () const

Returns the value color component of this color.

See also value(), hueF(), saturationF(), and alphaF().

int QColor::yellow () const

Returns the yellow color component of this color.

See also yellowF(), cyan(), magenta(), black(), and alpha().

qreal QColor::yellowF () const

Returns the yellow color component of this color.

See also yellow(), cyanF(), magentaF(), blackF(), and alphaF().

QColor::operator QVariant () const

Returns the color as a QVariant

bool QColor::operator!= ( const QColor & color ) const

Returns true if this color has a different RGB value from the color color; otherwise returns false.

QColor & QColor::operator= ( const QColor & color )

Assigns a copy of the color color to this color, and returns a reference to it.

QColor & QColor::operator= ( Qt::GlobalColor color )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Assigns a copy of the color and returns a reference to this color.

bool QColor::operator== ( const QColor & color ) const

Returns true if this color has the same RGB value as the color color; otherwise returns false.

Related Non-Members

int qAlpha ( QRgb rgba )

Returns the alpha component of the RGBA quadruplet rgba.

int qBlue ( QRgb rgb )

Returns the blue component of the RGBA quadruplet rgb.

See also qRgb() and QColor::blue().

int qGray ( int r, int g, int b )

Returns a gray value (0 to 255) from the (r, g, b) triplet.

The gray value is calculated using the formula (r*11 + g*16 + b*5)/32.

int qGray ( QRgb rgb )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns a gray value (0 to 255) from the given RGB triplet rgb.

int qGreen ( QRgb rgb )

Returns the green component of the RGBA quadruplet rgb.

See also qRgb() and QColor::green().

int qRed ( QRgb rgb )

Returns the red component of the RGBA quadruplet rgb.

See also qRgb() and QColor::red().

QRgb qRgb ( int r, int g, int b )

Returns the RGB triplet (r, g, b).

The return type QRgb is equivalent to unsigned int.

See also qRgba(), qRed(), qGreen(), and qBlue().

QRgb qRgba ( int r, int g, int b, int a )

Returns the RGBA quadruplet (r, g, b, a).

The return type QRgba is equivalent to unsigned int.

See also qRgb(), qRed(), qGreen(), and qBlue().

QDataStream & operator<< ( QDataStream & stream, const QColor & color )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Writes the color to the stream.

See also Format of the QDataStream operators.

QDataStream & operator>> ( QDataStream & stream, QColor & color )

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Reads the color from the stream.

See also Format of the QDataStream operators.