X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b7e94bd7ebc205ffba5e2729b0d465778d4e48c6..9e9574fe45b176ee74bba8fad7574cf9906145d1:/interface/wx/colour.h?ds=sidebyside diff --git a/interface/wx/colour.h b/interface/wx/colour.h index 209929c39a..09c1c242a6 100644 --- a/interface/wx/colour.h +++ b/interface/wx/colour.h @@ -2,10 +2,27 @@ // Name: colour.h // Purpose: interface of wxColour // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + + +/** + Flags for wxColour -> wxString conversion (see wxColour::GetAsString). + + @{ +*/ +enum { + wxC2S_NAME = 1, // return colour name, when possible + wxC2S_CSS_SYNTAX = 2, // return colour in rgb(r,g,b) syntax + wxC2S_HTML_SYNTAX = 4 // return colour in #rrggbb syntax +}; + +//@} + +const unsigned char wxALPHA_TRANSPARENT = 0; +const unsigned char wxALPHA_OPAQUE = 0xff; + /** @class wxColour @@ -23,10 +40,12 @@ @stdobjects - ::wxNullColour - An empty, invalid colour. + - ::wxTransparentColour - Valid but fully transparent colour (new in 2.9.1). - ::wxBLACK - ::wxBLUE - ::wxCYAN - ::wxGREEN + - ::wxYELLOW - ::wxLIGHT_GREY - ::wxRED - ::wxWHITE @@ -62,6 +81,12 @@ public: */ wxColour(const wxString& colourName); + /** + @param colRGB + A packed RGB value. + */ + wxColour(unsigned long colRGB); + /** Copy constructor. */ @@ -81,29 +106,65 @@ public: /** Converts this colour to a wxString using the given flags. - The supported flags are wxC2S_NAME, to obtain the colour name (e.g. - wxColour(255,0,0) == "red"), wxC2S_CSS_SYNTAX, to obtain the colour in - the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g. - wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and wxC2S_HTML_SYNTAX, - to obtain the colour as "#" followed by 6 hexadecimal digits (e.g. - wxColour(255,0,0) == "#FF0000"). + The supported flags are @c wxC2S_NAME, to obtain the colour name + (e.g. wxColour(255,0,0) == "red"), @c wxC2S_CSS_SYNTAX, to obtain + the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax + (e.g. wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and + @c wxC2S_HTML_SYNTAX, to obtain the colour as "#" followed by 6 + hexadecimal digits (e.g. wxColour(255,0,0) == "#FF0000"). This function never fails and always returns a non-empty string but asserts if the colour has alpha channel (i.e. is non opaque) but - wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not + @c wxC2S_CSS_SYNTAX (which is the only one supporting alpha) is not specified in flags. @since 2.7.0 */ - wxString GetAsString(long flags); + virtual wxString GetAsString(long flags = wxC2S_NAME | wxC2S_CSS_SYNTAX) const; + //@{ /** - Returns a pixel value which is platform-dependent. On Windows, a COLORREF is - returned. + Sets the RGB or RGBA colour values from a single 32 bit value. + + 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. + + Notice the right-to-left order of components! + + @see GetRGB(), GetRGBA() + + @since 2.9.1 + */ + void SetRGB(wxUint32 colRGB); + void SetRGBA(wxUint32 colRGBA); + //@} + + //@{ + /** + Gets the RGB or RGBA colour values as a single 32 bit value. + + The returned value is of the same form as expected by SetRGB() and + SetRGBA(). + + Notice that GetRGB() returns the value with 0 as its highest byte + independently of the value actually returned by Alpha(). So for a fully + opaque colour, the return value of GetRGBA() is @c 0xFFBBGGRR while + that of GetRGB() is @c 0x00BBGGRR. + + @since 2.9.1 + */ + wxUint32 GetRGB() const; + wxUint32 GetRGBA() const; + //@} + + /** + Returns a pixel value which is platform-dependent. + On Windows, a COLORREF is returned. On X, an allocated pixel value is returned. - -1 is returned if the pixel is invalid (on X, unallocated). + If the pixel is invalid (on X, unallocated), @c -1 is returned. */ - long GetPixel() const; + wxIntPtr GetPixel() const; /** Returns the green intensity. @@ -114,7 +175,7 @@ public: Returns @true if the colour object is valid (the colour has been initialised with RGB values). */ - bool IsOk() const; + virtual bool IsOk() const; /** Returns the red intensity. @@ -125,13 +186,12 @@ public: /** Sets the RGB intensity values using the given values (first overload), extracting them from the packed long (second overload), using the given - string (third overloard). + string (third overload). When using third form, Set() accepts: colour names (those listed in - wxTheColourDatabase()), the CSS-like @c "rgb(r,g,b)" or - @c "rgba(r,g,b,a)" syntax (case insensitive) and the HTML-like syntax - (i.e. @c "#" followed by 6 hexadecimal digits for red, green, blue - components). + wxColourDatabase), the CSS-like @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax + (case insensitive) and the HTML-like syntax: @c "#" followed by 6 hexadecimal + digits for red, green, blue components. Returns @true if the conversion was successful, @false otherwise. @@ -148,33 +208,89 @@ public: Tests the inequality of two colours by comparing individual red, green, blue colours and alpha values. */ - bool operator !=(const wxColour& colour); + bool operator !=(const wxColour& colour) const; - //@{ /** Assignment operator, using a colour name to be found in the colour database. @see wxColourDatabase */ - wxColour operator =(const wxColour& colour); - wxColour operator =(const wxString& colourName); - //@} + wxColour& operator=(const wxColour& colour); /** Tests the equality of two colours by comparing individual red, green, blue colours and alpha values. */ - bool operator ==(const wxColour& colour); + bool operator ==(const wxColour& colour) const; + + /** + Assign 0 or 255 to rgb out parameters. + @since 2.9.0 + */ + static void MakeMono(unsigned char* r, unsigned char* g, unsigned char* b, bool on); + + /** + Create a disabled (dimmed) colour from (in/out) rgb parameters. + @since 2.9.0 + */ + static void MakeDisabled(unsigned char* r, unsigned char* g, unsigned char* b, unsigned char brightness = 255); + + /** + Make a disabled version of this colour. + + This method modifies the object in place and returns the object itself. + + @since 2.9.5 + */ + wxColour& MakeDisabled(unsigned char brightness = 255); + + /** + Create a grey colour from (in/out) rgb parameters using integer arithmetic. + @since 2.9.0 + */ + static void MakeGrey(unsigned char* r, unsigned char* g, unsigned char* b); + + /** + Create a grey colour from (in/out) rgb parameters using floating point arithmetic. + Defaults to using the standard ITU-T BT.601 when converting to YUV, where every pixel equals + (R * @a weight_r) + (G * @a weight_g) + (B * @a weight_b). + @since 2.9.0 + */ + static void MakeGrey(unsigned char* r, unsigned char* g, unsigned char* b, + double weight_r, double weight_g, double weight_b); + + /** + Blend colour, taking alpha into account. + @since 2.9.0 + */ + 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 + @since 2.9.0 + */ + static void ChangeLightness(unsigned char* r, unsigned char* g, unsigned char* b, int ialpha); + + /** + wxColour wrapper for ChangeLightness(r,g,b,ialpha). + @since 2.9.0 + */ + wxColour ChangeLightness(int ialpha) const; }; /** @name Predefined colors. */ //@{ wxColour wxNullColour; +wxColour wxTransparentColour; wxColour* wxBLACK; wxColour* wxBLUE; wxColour* wxCYAN; wxColour* wxGREEN; +wxColour* wxYELLOW; wxColour* wxLIGHT_GREY; wxColour* wxRED; wxColour* wxWHITE; @@ -186,7 +302,7 @@ wxColour* wxWHITE; // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_misc */ +/** @addtogroup group_funcmacro_misc */ //@{ /**