From 67361b89d59ce7c0bde325b4fc9a3005a558543d Mon Sep 17 00:00:00 2001 From: PB Date: Sat, 13 Jul 2019 11:01:57 +0200 Subject: [PATCH] Improve wxColour documentation In the class description mention that in addition to RGB, an alpha value is stored as well. Remove incorrect description of operator=(), clarify meaning of "on" parameter in MakeMono(), and make few minor text edits. Closes https://github.com/wxWidgets/wxWidgets/pull/1411 --- interface/wx/colour.h | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/interface/wx/colour.h b/interface/wx/colour.h index 7981e0208a..6fda827039 100644 --- a/interface/wx/colour.h +++ b/interface/wx/colour.h @@ -27,9 +27,9 @@ const unsigned char wxALPHA_OPAQUE = 0xff; @class wxColour A colour is an object representing a combination of Red, Green, and Blue - (RGB) intensity values, and is used to determine drawing colours. See the - entry for wxColourDatabase for how a pointer to a predefined, named colour - may be returned instead of creating a new colour. + (RGB) intensity values and an Alpha value, and is used to determine + drawing colours. See the entry for wxColourDatabase for how a pointer to a predefined, + named colour may be returned instead of creating a new colour. Valid RGB values are in the range 0 to 255. @@ -128,7 +128,7 @@ public: The arguments @a colRGB and @a colRGBA should be of the form 0x00BBGGRR and 0xAABBGGRR respectively where @c 0xRR, @c 0xGG, @c 0xBB and @c 0xAA - are the values of the red, blue, green and alpha components. + are the values of the red, green, blue and alpha components. Notice the right-to-left order of components! @@ -161,8 +161,8 @@ public: /** Return the perceived brightness of the colour. - This value is computed using the simple @code 0.299*R + 0.587*G + - 0.114*B @endcode formula with the coefficients taken from the RGB to + This value is computed using the simple @code 0.299*R + 0.587*G + 0.114*B @endcode + formula with the coefficients taken from the RGB to YIQ conversion formula and @c R, @c G and @c B being the values of the corresponding colour channels normalized to 0..1 range, so that the return value is 0 for black and 1 for white. @@ -196,7 +196,7 @@ public: virtual unsigned char Red() const; /** - Returns @true if the color can be described using RGB values, ie is solid, + Returns @true if the color can be described using RGB values, i.e. is solid, @false if it is a pattern (currently only possible on macOS) */ virtual bool IsSolid() const; @@ -224,12 +224,12 @@ public: /** Tests the inequality of two colours by comparing individual red, green, blue - colours and alpha values. + intensities and alpha values. */ bool operator !=(const wxColour& colour) const; /** - Assignment operator, using a colour name to be found in the colour database. + Assignment operator. @see wxColourDatabase */ @@ -237,12 +237,12 @@ public: /** Tests the equality of two colours by comparing individual red, green, blue - colours and alpha values. + intensities and alpha values. */ bool operator ==(const wxColour& colour) const; /** - Assign 0 or 255 to rgb out parameters. + Assigns the same value to @a r, @a g, @a b: 0 if @a on is @c false, 255 otherwise. @since 2.9.0 */ static void MakeMono(unsigned char* r, unsigned char* g, unsigned char* b, bool on); @@ -284,10 +284,9 @@ public: static unsigned char AlphaBlend(unsigned char fg, unsigned char bg, double alpha); /** - ChangeLightness() is a utility function that simply darkens - or lightens a color, based on the specified percentage - ialpha of 0 would be completely black, 200 completely white - an ialpha of 100 returns the same colour + Utility function that simply darkens or lightens a color, based on the specified + percentage @a ialpha. @a ialpha of 0 would be make the color completely black, + 200 completely white and 100 would not change the color. @since 2.9.0 */ static void ChangeLightness(unsigned char* r, unsigned char* g, unsigned char* b, int ialpha);