Restore wxString::Printf() example showing position parameters in the docs.

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

diff --git a/interface/wx/colour.h b/interface/wx/colour.h
index 2a2193d9ff7e5a5197852d3097666bf3e0a32004..a4771ec582f4a2597218977c45f86f1a642d325a 100644 (file)
--- a/interface/wx/colour.h
+++ b/interface/wx/colour.h
@@ -37,10 +37,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
@@ -111,6 +113,42 @@ public:
     */
     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.
@@ -176,6 +214,54 @@ public:
         colours and alpha values.
     */
     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;
 };
 
 
@@ -186,6 +272,7 @@ wxColour* wxBLACK;
 wxColour* wxBLUE;
 wxColour* wxCYAN;
 wxColour* wxGREEN;
+wxColour* wxYELLOW;
 wxColour* wxLIGHT_GREY;
 wxColour* wxRED;
 wxColour* wxWHITE;