From a2b8f891fa9a93229a8645d18617d6906aa88b88 Mon Sep 17 00:00:00 2001 From: Eirik Aavitsland Date: Mon, 21 Jan 2019 10:55:50 +0100 Subject: Doc: decrease confusion about HSV vs HSL in QColor The non-qualified hue() and saturation() etc. refers to those values in the HSV, not HSL, color model. Make this more explicit in the documentation to avoid confusion. Task-number: QTBUG-73129 Change-Id: Ief337672966ac72d0d0c3606d8d68acf01ffe7ee Reviewed-by: Venugopal Shivashankar --- src/gui/painting/qcolor.cpp | 66 +++++++++++++++++++++++++-------------------- 1 file changed, 37 insertions(+), 29 deletions(-) (limited to 'src') diff --git a/src/gui/painting/qcolor.cpp b/src/gui/painting/qcolor.cpp index 1f1835d5da..e5bac84df9 100644 --- a/src/gui/painting/qcolor.cpp +++ b/src/gui/painting/qcolor.cpp @@ -541,7 +541,15 @@ static QStringList get_colornames() \section1 The HSL Color Model HSL is similar to HSV, however instead of the Value parameter, HSL - specifies a Lightness parameter. + specifies a Lightness parameter which maps somewhat differently to the + brightness of the color. + + Similarly, the HSL saturation value is not in general the same as the HSV + saturation value for the same color. hslSaturation() provides the color's + HSL saturation value, while saturation() and hsvSaturation() provides the + HSV saturation value. + + The hue value is defined to be the same in HSL and HSV. \section1 The CMYK Color Model @@ -1098,7 +1106,7 @@ void QColor::setHsv(int h, int s, int v, int a) These components can be retrieved individually using the hslHueF(), hslSaturationF(), lightnessF() and alphaF() functions. - \sa setHsl() + \sa getHsl(), setHslF(), {QColor#The HSL Color Model}{The HSL Color Model} */ void QColor::getHslF(qreal *h, qreal *s, qreal *l, qreal *a) const { @@ -1128,7 +1136,7 @@ void QColor::getHslF(qreal *h, qreal *s, qreal *l, qreal *a) const These components can be retrieved individually using the hslHue(), hslSaturation(), lightness() and alpha() functions. - \sa setHsl() + \sa getHslF(), setHsl(), {QColor#The HSL Color Model}{The HSL Color Model} */ void QColor::getHsl(int *h, int *s, int *l, int *a) const { @@ -1619,11 +1627,11 @@ void QColor::setBlueF(qreal blue) } /*! - Returns the hue color component of this color. + Returns the HSV hue color component of this color. The color is implicitly converted to HSV. - \sa hsvHue(), hueF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} + \sa hsvHue(), hslHue(), hueF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} */ int QColor::hue() const Q_DECL_NOTHROW @@ -1632,9 +1640,9 @@ int QColor::hue() const Q_DECL_NOTHROW } /*! - Returns the hue color component of this color. + Returns the HSV hue color component of this color. - \sa hueF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} + \sa hueF(), hslHue(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} */ int QColor::hsvHue() const Q_DECL_NOTHROW { @@ -1644,11 +1652,11 @@ int QColor::hsvHue() const Q_DECL_NOTHROW } /*! - Returns the saturation color component of this color. + Returns the HSV saturation color component of this color. The color is implicitly converted to HSV. - \sa hsvSaturation(), saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color + \sa hsvSaturation(), hslSaturation(), saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} */ @@ -1658,9 +1666,9 @@ int QColor::saturation() const Q_DECL_NOTHROW } /*! - Returns the saturation color component of this color. + Returns the HSV saturation color component of this color. - \sa saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} + \sa saturationF(), hslSaturation(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} */ int QColor::hsvSaturation() const Q_DECL_NOTHROW { @@ -1682,11 +1690,11 @@ int QColor::value() const Q_DECL_NOTHROW } /*! - Returns the hue color component of this color. + Returns the HSV hue color component of this color. The color is implicitly converted to HSV. - \sa hsvHueF(), hue(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model} + \sa hsvHueF(), hslHueF(), hue(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model} */ qreal QColor::hueF() const Q_DECL_NOTHROW { @@ -1696,7 +1704,7 @@ qreal QColor::hueF() const Q_DECL_NOTHROW /*! Returns the hue color component of this color. - \sa hue(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color + \sa hue(), hslHueF(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model} */ qreal QColor::hsvHueF() const Q_DECL_NOTHROW @@ -1707,11 +1715,11 @@ qreal QColor::hsvHueF() const Q_DECL_NOTHROW } /*! - Returns the saturation color component of this color. + Returns the HSV saturation color component of this color. The color is implicitly converted to HSV. - \sa hsvSaturationF(), saturation(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color + \sa hsvSaturationF(), hslSaturationF(), saturation(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model} */ qreal QColor::saturationF() const Q_DECL_NOTHROW @@ -1720,9 +1728,9 @@ qreal QColor::saturationF() const Q_DECL_NOTHROW } /*! - Returns the saturation color component of this color. + Returns the HSV saturation color component of this color. - \sa saturation(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model} + \sa saturation(), hslSaturationF(), getHsvF(), {QColor#The HSV Color Model}{The HSV Color Model} */ qreal QColor::hsvSaturationF() const Q_DECL_NOTHROW { @@ -1746,9 +1754,9 @@ qreal QColor::valueF() const Q_DECL_NOTHROW /*! \since 4.6 - Returns the hue color component of this color. + Returns the HSL hue color component of this color. - \sa getHslF(), getHsl() + \sa hslHueF(), hsvHue(), getHsl(), {QColor#The HSL Color Model}{The HSL Color Model} */ int QColor::hslHue() const Q_DECL_NOTHROW { @@ -1760,9 +1768,9 @@ int QColor::hslHue() const Q_DECL_NOTHROW /*! \since 4.6 - Returns the saturation color component of this color. + Returns the HSL saturation color component of this color. - \sa saturationF(), getHsv(), {QColor#The HSV Color Model}{The HSV Color Model} + \sa hslSaturationF(), hsvSaturation(), getHsl(), {QColor#The HSL Color Model}{The HSL Color Model} */ int QColor::hslSaturation() const Q_DECL_NOTHROW { @@ -1788,9 +1796,9 @@ int QColor::lightness() const Q_DECL_NOTHROW /*! \since 4.6 - Returns the hue color component of this color. + Returns the HSL hue color component of this color. - \sa hue(), getHslF() + \sa hslHue(), hsvHueF(), getHslF() */ qreal QColor::hslHueF() const Q_DECL_NOTHROW { @@ -1802,9 +1810,9 @@ qreal QColor::hslHueF() const Q_DECL_NOTHROW /*! \since 4.6 - Returns the saturation color component of this color. + Returns the HSL saturation color component of this color. - \sa saturationF(), getHslF() + \sa hslSaturation(), hsvSaturationF(), getHslF(), {QColor#The HSL Color Model}{The HSL Color Model} */ qreal QColor::hslSaturationF() const Q_DECL_NOTHROW { @@ -2124,7 +2132,7 @@ QColor QColor::toHsv() const Q_DECL_NOTHROW /*! Creates and returns an HSL QColor based on this color. - \sa fromHsl(), convertTo(), isValid() + \sa fromHsl(), convertTo(), isValid(), {QColor#The HSL Color Model}{The HSL Color Model} */ QColor QColor::toHsl() const Q_DECL_NOTHROW { @@ -2436,7 +2444,7 @@ QColor QColor::fromHsvF(qreal h, qreal s, qreal v, qreal a) The value of \a s, \a l, and \a a must all be in the range 0-255; the value of \a h must be in the range 0-359. - \sa toHsl(), fromHslF(), isValid() + \sa toHsl(), fromHslF(), isValid(), {QColor#The HSL Color Model}{The HSL Color Model} */ QColor QColor::fromHsl(int h, int s, int l, int a) { @@ -2468,7 +2476,7 @@ QColor QColor::fromHsl(int h, int s, int l, int a) All the values must be in the range 0.0-1.0. - \sa toHsl(), fromHsl(), isValid() + \sa toHsl(), fromHsl(), isValid(), {QColor#The HSL Color Model}{The HSL Color Model} */ QColor QColor::fromHslF(qreal h, qreal s, qreal l, qreal a) { -- cgit v1.2.3