Correct names of parameters in wxAffineMatrix2D documentation.

[wxWidgets.git] / interface / wx / colour.h

diff --git a/interface/wx/colour.h b/interface/wx/colour.h
index 209929c39a68f325de5ef932182391117eb29b9d..bf051c3ff1fc9e85f1d5a3f617a980074b57becc 100644 (file)
--- a/interface/wx/colour.h
+++ b/interface/wx/colour.h
@@ -3,9 +3,27 @@
 // Purpose:     interface of wxColour
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // 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
 
 /**
     @class wxColour
 


@@ -23,10 +41,12 @@
 
     @stdobjects
     - ::wxNullColour - An empty, invalid colour.
 
     @stdobjects
     - ::wxNullColour - An empty, invalid colour.

+    - ::wxTransparentColour - Valid but fully transparent colour (new in 2.9.1).

     - ::wxBLACK
     - ::wxBLUE
     - ::wxCYAN
     - ::wxGREEN
     - ::wxBLACK
     - ::wxBLUE
     - ::wxCYAN
     - ::wxGREEN

+    - ::wxYELLOW

     - ::wxLIGHT_GREY
     - ::wxRED
     - ::wxWHITE
     - ::wxLIGHT_GREY
     - ::wxRED
     - ::wxWHITE


@@ -62,6 +82,12 @@ public:
     */
     wxColour(const wxString& colourName);
 
     */
     wxColour(const wxString& colourName);
 

+    /**
+        @param colRGB
+            A packed RGB value.
+    */
+    wxColour(unsigned long colRGB);
+    

     /**
         Copy constructor.
     */
     /**
         Copy constructor.
     */


@@ -81,29 +107,65 @@ public:
     /**
         Converts this colour to a wxString using the given flags.
 
     /**
         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
 
         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
     */
         specified in flags.
 
         @since 2.7.0
     */

-    wxString GetAsString(long flags);
+    virtual wxString GetAsString(long flags = wxC2S_NAME | wxC2S_CSS_SYNTAX) const;
+
+    //@{
+    /**
+        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.
+        Returns a pixel value which is platform-dependent.
+        On Windows, a COLORREF is returned.

         On X, an allocated pixel value 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.
 
     /**
         Returns the green intensity.


@@ -114,7 +176,7 @@ public:
         Returns @true if the colour object is valid (the colour has been initialised
         with RGB values).
     */
         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.
 
     /**
         Returns the red intensity.


@@ -125,13 +187,12 @@ public:
     /**
         Sets the RGB intensity values using the given values (first overload),
         extracting them from the packed long (second overload), using the given
     /**
         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
 
         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.
 
 
         Returns @true if the conversion was successful, @false otherwise.
 


@@ -148,33 +209,80 @@ public:
         Tests the inequality of two colours by comparing individual red, green, blue
         colours and alpha values.
     */
         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
     */
     /**
         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.
     */
 
     /**
         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);
+    
+    /**
+        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;
 };
 
 
 /** @name Predefined colors. */
 //@{
 wxColour wxNullColour;

+wxColour wxTransparentColour;

 wxColour* wxBLACK;
 wxColour* wxBLUE;
 wxColour* wxCYAN;
 wxColour* wxGREEN;
 wxColour* wxBLACK;
 wxColour* wxBLUE;
 wxColour* wxCYAN;
 wxColour* wxGREEN;

+wxColour* wxYELLOW;

 wxColour* wxLIGHT_GREY;
 wxColour* wxRED;
 wxColour* wxWHITE;
 wxColour* wxLIGHT_GREY;
 wxColour* wxRED;
 wxColour* wxWHITE;


@@ -186,7 +294,7 @@ wxColour* wxWHITE;
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_misc */
+/** @addtogroup group_funcmacro_misc */

 //@{
 
 /**
 //@{
 
 /**