X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..de536319f16406adf967003637b2655c61f6cb09:/interface/colour.h diff --git a/interface/colour.h b/interface/colour.h index bc5673324d..52bc2f28d1 100644 --- a/interface/colour.h +++ b/interface/colour.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: colour.h -// Purpose: documentation for wxColour class +// Purpose: interface of wxColour // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,11 +10,10 @@ @class wxColour @wxheader{colour.h} - 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. + 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. Valid RGB values are in the range 0 to 255. @@ -24,136 +23,126 @@ @category{gdi} @stdobjects - Objects: - wxNullColour - Pointers: - wxBLACK - - wxWHITE - - wxRED - - wxBLUE - - wxGREEN - - wxCYAN - - wxLIGHT_GREY - - @seealso - wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings + - ::wxNullColour - An empty, invalid colour. + - ::wxBLACK + - ::wxBLUE + - ::wxCYAN + - ::wxGREEN + - ::wxLIGHT_GREY + - ::wxRED + - ::wxWHITE + + @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings */ class wxColour : public wxObject { public: - //@{ + + /** + Default constructor. + */ + wxColour(); + /** - Copy constructor. - @param red - The red value. - + The red value. @param green - The green value. - + The green value. @param blue - The blue value. - + The blue value. @param alpha - The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255 - (wxALPHA_OPAQUE). - + The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to + 255 (wxALPHA_OPAQUE). + */ + wxColour(unsigned char red, unsigned char green, unsigned char blue, + unsigned char alpha = wxALPHA_OPAQUE); + + /** @param colourName - The colour name. - - @param colour - The colour to copy. - - @sa wxColourDatabase + The colour name. + */ + wxColour(const wxString& colourName); + + /** + Copy constructor. */ - wxColour(); - wxColour(unsigned char red, unsigned char green, - unsigned char blue, - unsigned char alpha=wxALPHA_OPAQUE); - wxColour(const wxString& colourNname); wxColour(const wxColour& colour); - //@} /** Returns the alpha value, on platforms where alpha is not yet supported, this always returns wxALPHA_OPAQUE. */ - unsigned char Alpha(); + unsigned char Alpha() const; /** Returns the blue intensity. */ - unsigned char Blue(); + unsigned char Blue() const; - //@{ /** - is not + 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"). + + 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 specified in flags. - - This function is new since wxWidgets version 2.7.0 + + @since 2.7.0 */ wxString GetAsString(long flags); - wxC2S_NAME 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"). - 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(); - //@} /** 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). */ - long GetPixel(); + long GetPixel() const; /** Returns the green intensity. */ - unsigned char Green(); + unsigned char Green() const; /** Returns @true if the colour object is valid (the colour has been initialised with RGB values). */ -#define bool IsOk() /* implementation is private */ + bool IsOk() const; /** Returns the red intensity. */ -#define unsigned char Red() /* implementation is private */ + unsigned char Red() const; //@{ /** 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). - + extracting them from the packed long (second overload), using the given + string (third overloard). + 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). - + 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). + Returns @true if the conversion was successful, @false otherwise. - - This function is new since wxWidgets version 2.7.0 + + @since 2.7.0 */ void Set(unsigned char red, unsigned char green, unsigned char blue, - unsigned char alpha=wxALPHA_OPAQUE); + unsigned char alpha = wxALPHA_OPAQUE); void Set(unsigned long RGB); - bool Set(const wxString & str); + bool Set(const wxString& str); //@} /** @@ -165,8 +154,8 @@ public: //@{ /** Assignment operator, using a colour name to be found in the colour database. - - @sa wxColourDatabase + + @see wxColourDatabase */ wxColour operator =(const wxColour& colour); wxColour operator =(const wxString& colourName); @@ -178,3 +167,47 @@ public: */ bool operator ==(const wxColour& colour); }; + + +/** @name Predefined colors. */ +//@{ +wxColour wxNullColour; +wxColour* wxBLACK; +wxColour* wxBLUE; +wxColour* wxCYAN; +wxColour* wxGREEN; +wxColour* wxLIGHT_GREY; +wxColour* wxRED; +wxColour* wxWHITE; +//@} + + + +// ============================================================================ +// Global functions/macros +// ============================================================================ + +/** @ingroup group_funcmacro_misc */ +//@{ + +/** + Converts string to a wxColour best represented by the given string. Returns + @true on success. + + @see wxToString(const wxColour&) + + @header{wx/colour.h} +*/ +bool wxFromString(const wxString& string, wxColour* colour); + +/** + Converts the given wxColour into a string. + + @see wxFromString(const wxString&, wxColour*) + + @header{wx/colour.h} +*/ +wxString wxToString(const wxColour& colour); + +//@} +