.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.Colour:

==========================================================================================================================================
|phoenix_title|  **wx.Colour**
==========================================================================================================================================

A colour is an object representing a combination of Red, Green, and Blue (``RGB``) intensity values and an Alpha value, and is used to determine drawing colours.          

See the entry for :ref:`wx.ColourDatabase`  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. 

You can retrieve the current system colour settings with :ref:`wx.SystemSettings`. 









         



.. seealso:: :ref:`wx.ColourDatabase`, :ref:`wx.Pen`, :ref:`wx.Brush`, :ref:`wx.ColourDialog`, :ref:`wx.SystemSettings`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>Colour</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.Colour_inheritance.png" alt="Inheritance diagram of Colour" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Colour.html" title="wx.Colour" alt="" coords="5,83,92,112"/> <area shape="rect" id="node2" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,92,35"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.Colour.__init__`                                                      Default constructor.
:meth:`~wx.Colour.Alpha`                                                         Returns the alpha value, on platforms where alpha is not yet supported, this always returns ``wx.ALPHA_OPAQUE``.
:meth:`~wx.Colour.AlphaBlend`                                                    Blend colour, taking alpha into account.
:meth:`~wx.Colour.Blue`                                                          Returns the blue intensity.
:meth:`~wx.Colour.ChangeLightness`                                               :ref:`wx.Colour`  wrapper for ChangeLightness(r,g,b,ialpha).
:meth:`~wx.Colour.Get`                                                           Returns the ``RGB`` intensity values as a tuple, optionally the alpha value as well.
:meth:`~wx.Colour.GetAsString`                                                   Converts this colour to a :ref:`String`  using the given flags.
:meth:`~wx.Colour.GetIM`                                                         Returns an immutable representation of the ``wx.Colour`` object, based on ``namedtuple``.
:meth:`~wx.Colour.GetLuminance`                                                  Return the perceived brightness of the colour.
:meth:`~wx.Colour.GetPixel`                                                      
:meth:`~wx.Colour.GetRGB`                                                        Gets the ``RGB`` or ``RGBA`` colour values as a single 32 bit value.
:meth:`~wx.Colour.GetRGBA`                                                       Gets the ``RGB`` or ``RGBA`` colour values as a single 32 bit value.
:meth:`~wx.Colour.Green`                                                         Returns the green intensity.
:meth:`~wx.Colour.IsOk`                                                          Returns ``True`` if the colour object is valid (the colour has been initialised with ``RGB`` values).
:meth:`~wx.Colour.IsSolid`                                                       Returns ``True`` if the color can be described using ``RGB`` values, i.e.
:meth:`~wx.Colour.MakeDisabled`                                                  Make a disabled version of this colour.
:meth:`~wx.Colour.MakeGrey`                                                      Create a grey colour from (in/out) rgb parameters using integer arithmetic.
:meth:`~wx.Colour.MakeMono`                                                      Assigns the same value to `r`, `g`, `b:`  0 if `on`  is  ``false`` , 255 otherwise.
:meth:`~wx.Colour.Red`                                                           Returns the red intensity.
:meth:`~wx.Colour.Set`                                                           Sets the ``RGB`` intensity values using the given values (first overload), extracting them from the packed long (second overload), using the given string (third overload).
:meth:`~wx.Colour.SetRGB`                                                        Sets the ``RGB`` or ``RGBA`` colour values from a single 32 bit value.
:meth:`~wx.Colour.SetRGBA`                                                       Sets the ``RGB`` or ``RGBA`` colour values from a single 32 bit value.
:meth:`~wx.Colour.__bool__`                                                      
:meth:`~wx.Colour.__getitem__`                                                   
:meth:`~wx.Colour.__len__`                                                       
:meth:`~wx.Colour.__nonzero__`                                                   
:meth:`~wx.Colour.__reduce__`                                                    
:meth:`~wx.Colour.__repr__`                                                      
:meth:`~wx.Colour.__setitem__`                                                   
:meth:`~wx.Colour.__str__`                                                       
:meth:`~wx.Colour._copyFrom`                                                     For internal use only.
:meth:`~wx.Colour.__ne__`                                                        Tests the inequality of two colours by comparing individual red, green, blue intensities and alpha values.
:meth:`~wx.Colour.__eq__`                                                        Tests the equality of two colours by comparing individual red, green, blue intensities and alpha values.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.Colour.Pixel`                                                         See :meth:`~wx.Colour.GetPixel`
:attr:`~wx.Colour.RGB`                                                           See :meth:`~wx.Colour.GetRGB` and :meth:`~wx.Colour.SetRGB`
:attr:`~wx.Colour.RGBA`                                                          See :meth:`~wx.Colour.GetRGBA` and :meth:`~wx.Colour.SetRGBA`
:attr:`~wx.Colour.alpha`                                                         See :meth:`~wx.Colour.Alpha`
:attr:`~wx.Colour.blue`                                                          See :meth:`~wx.Colour.Blue`
:attr:`~wx.Colour.green`                                                         See :meth:`~wx.Colour.Green`
:attr:`~wx.Colour.red`                                                           See :meth:`~wx.Colour.Red`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.Colour(Object)

   **Possible constructors**::

       Colour()
       
       Colour(red, green, blue, alpha=ALPHA_OPAQUE)
       
       Colour(colRGB)
       
       Colour(colour)
       
   
   A colour is an object representing a combination of Red, Green, and
   Blue (``RGB``) intensity values and an Alpha value, and is used to
   determine drawing colours.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, red, green, blue, alpha=ALPHA_OPAQUE)`
      
      
      
      
      
      
      :param `red`: The red value.   
      :type `red`: int
      :param `green`: The green value.   
      :type `green`: int
      :param `blue`: The blue value.   
      :type `blue`: int
      :param `alpha`: The alpha value. Alpha values range from 0 (wx``wx.ALPHA_TRANSPARENT``) to 255 (wx``wx.ALPHA_OPAQUE``).   
      :type `alpha`: int
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, colRGB)`
      
      
      
      
      
      
      :param `colRGB`: A packed ``RGB`` value.   
      :type `colRGB`: long
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, colour)`
      
      Copy constructor.                  
      
      
      :param `colour`: 
      :type `colour`: wx.Colour
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Alpha(self)

      Returns the alpha value, on platforms where alpha is not yet supported, this always returns ``wx.ALPHA_OPAQUE``.                  

      :rtype: `int`








   .. staticmethod:: AlphaBlend(fg, bg, alpha)

      Blend colour, taking alpha into account.                  

                


      :param `fg`: 
      :type `fg`: int
      :param `bg`: 
      :type `bg`: int
      :param `alpha`: 
      :type `alpha`: float




      :rtype: `int`







      .. versionadded:: 2.9.0 
     








   .. method:: Blue(self)

      Returns the blue intensity.                  

      :rtype: `int`








   .. method:: ChangeLightness(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **ChangeLightness** `(self, ialpha)`
      
      :ref:`wx.Colour`  wrapper for ChangeLightness(r,g,b,ialpha).                  
      
                      
      
      
      :param `ialpha`: 
      :type `ialpha`: int
      
      
      
      
      :rtype: :ref:`wx.Colour`
      
      
      
      
      
      
      
      .. versionadded:: 2.9.0 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **ChangeLightness** `(r, g, b, ialpha)`
      
      Utility function that simply darkens or lightens a color, based on the specified percentage `ialpha`.                  
      
      `ialpha`  of 0 would be make the color completely black, 200 completely white and 100 would not change the color.                  
      
      
      :param `r`: 
      :type `r`: int
      :param `g`: 
      :type `g`: int
      :param `b`: 
      :type `b`: int
      :param `ialpha`: 
      :type `ialpha`: int
      
      
      
      
      :rtype: `tuple`
      
      
      
      
      
      
      
      :returns: 
      
         ( `r`, `g`, `b` ) 
      
      
      
      
      
      
      
      .. versionadded:: 2.9.0 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Get(self, includeAlpha=True)

                      Returns the ``RGB`` intensity values as a tuple, optionally the alpha value as well. 

      :rtype: `tuple`







      :returns: 

         ( `r`, `g`, `b) or (r`, `g`, `b`, `a` ) 








   .. method:: GetAsString(self, flags=C2S_NAME|C2S_CSS_SYNTAX)

      Converts this colour to a :ref:`String`  using the given flags.                  

      The supported flags are  ``C2S_NAME`` , to obtain the colour name (e.g.  :ref:`wx.Colour`  == "red"),  ``C2S_CSS_SYNTAX`` , to obtain the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g.  :ref:`wx.Colour`  == "rgba(255,0,0,0.333)"), and  ``C2S_HTML_SYNTAX`` , to obtain the colour as "#" followed by 6 hexadecimal digits (e.g.  :ref:`wx.Colour`  == "#``FF0000``"). 

      This function returns empty string if the colour is not initialized (see :meth:`IsOk` ). Otherwise, the returned string is always non-empty, but the function asserts if the colour has alpha channel (i.e. is non opaque) but  ``C2S_CSS_SYNTAX``   (which is the only one supporting alpha) is not specified in  `flags`. 

                


      :param `flags`: 
      :type `flags`: long




      :rtype: `string`







      .. versionadded:: 2.7.0 
     







      .. note:: 

         For non-solid (i.e. non-RGB) colour this function returns "rgb(??, ?? ??)" or "#??????".  








   .. method:: GetIM(self)

      Returns an immutable representation of the ``wx.Colour`` object, based on ``namedtuple``.
      
      This new object is hashable and can be used as a dictionary key,
      be added to sets, etc.  It can be converted back into a real ``wx.Colour``
      with a simple statement like this: ``obj = wx.Colour(imObj)``.



   .. method:: GetLuminance(self)

      Return the perceived brightness of the colour.                  

      This value is computed using the simple::

          ( 0.299*R + 0.587*G + 0.114*B )

      formula with the coefficients taken from the ``RGB`` to ``YIQ`` conversion formula and  ``R`` ,   ``G``   and   ``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. 

                

      :rtype: `float`







      .. versionadded:: 4.1/wxWidgets-3.1.3  
     








   .. method:: GetPixel(self)



      :rtype: :ref:`wx.IntPtr`








   .. method:: GetRGB(self)

      Gets the ``RGB`` or ``RGBA`` colour values as a single 32 bit value.                  

      The returned value is of the same form as expected by :meth:`SetRGB`   and :meth:`SetRGBA` . 

      Notice that :meth:`GetRGB`   returns the value with 0 as its highest byte independently of the value actually returned by :meth:`Alpha` . So for a fully opaque colour, the return value of :meth:`GetRGBA`   is  ``0xFFBBGGRR``   while that of  :meth:`GetRGB`   is  ``0x00BBGGRR`` . 

                

      :rtype: :ref:`wx.int`







      .. versionadded:: 2.9.1 
     








   .. method:: GetRGBA(self)

      Gets the ``RGB`` or ``RGBA`` colour values as a single 32 bit value.                  

      The returned value is of the same form as expected by :meth:`SetRGB`   and :meth:`SetRGBA` . 

      Notice that :meth:`GetRGB`   returns the value with 0 as its highest byte independently of the value actually returned by :meth:`Alpha` . So for a fully opaque colour, the return value of :meth:`GetRGBA`   is  ``0xFFBBGGRR``   while that of  :meth:`GetRGB`   is  ``0x00BBGGRR`` . 

                

      :rtype: :ref:`wx.int`







      .. versionadded:: 2.9.1 
     








   .. method:: Green(self)

      Returns the green intensity.                  

      :rtype: `int`








   .. method:: IsOk(self)

      Returns ``True`` if the colour object is valid (the colour has been initialised with ``RGB`` values).                  

      :rtype: `bool`








   .. method:: IsSolid(self)

      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)                  

      :rtype: `bool`








   .. method:: MakeDisabled(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **MakeDisabled** `(self, brightness=255)`
      
      Make a disabled version of this colour.                  
      
      This method modifies the object in place and returns the object itself. 
      
                      
      
      
      :param `brightness`: 
      :type `brightness`: int
      
      
      
      
      :rtype: :ref:`wx.Colour`
      
      
      
      
      
      
      
      .. versionadded:: 2.9.5 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **MakeDisabled** `(r, g, b, brightness=255)`
      
      Create a disabled (dimmed) colour from (in/out) rgb parameters.                  
      
                      
      
      
      :param `r`: 
      :type `r`: int
      :param `g`: 
      :type `g`: int
      :param `b`: 
      :type `b`: int
      :param `brightness`: 
      :type `brightness`: int
      
      
      
      
      :rtype: `tuple`
      
      
      
      
      
      
      
      :returns: 
      
         ( `r`, `g`, `b` ) 
      
      
      
      
      
      
      
      .. versionadded:: 2.9.0 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. staticmethod:: MakeGrey(*args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **MakeGrey** `(r, g, b)`
      
      Create a grey colour from (in/out) rgb parameters using integer arithmetic.                  
      
                      
      
      
      :param `r`: 
      :type `r`: int
      :param `g`: 
      :type `g`: int
      :param `b`: 
      :type `b`: int
      
      
      
      
      :rtype: `tuple`
      
      
      
      
      
      
      
      :returns: 
      
         ( `r`, `g`, `b` ) 
      
      
      
      
      
      
      
      .. versionadded:: 2.9.0 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **MakeGrey** `(r, g, b, weight_r, weight_g, weight_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  `weight_r`) + (G  `weight_g`) + (B  `weight_b`).                  
      
      
      :param `r`: 
      :type `r`: int
      :param `g`: 
      :type `g`: int
      :param `b`: 
      :type `b`: int
      :param `weight_r`: 
      :type `weight_r`: float
      :param `weight_g`: 
      :type `weight_g`: float
      :param `weight_b`: 
      :type `weight_b`: float
      
      
      
      
      :rtype: `tuple`
      
      
      
      
      
      
      
      :returns: 
      
         ( `r`, `g`, `b` ) 
      
      
      
      
      
      
      
      .. versionadded:: 2.9.0 
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. staticmethod:: MakeMono(on)

      Assigns the same value to `r`, `g`, `b:`  0 if `on`  is  ``false`` , 255 otherwise.                   

                


      :param `on`: 
      :type `on`: bool




      :rtype: `tuple`







      :returns: 

         ( `r`, `g`, `b` ) 







      .. versionadded:: 2.9.0 
     








   .. method:: Red(self)

      Returns the red intensity.                  

      :rtype: `int`








   .. method:: Set(self, *args, **kw)

      Sets the ``RGB`` intensity values using the given values (first overload), extracting them from the packed long (second overload), using the given string (third overload).                  

      When using third form, :meth:`Set`   accepts: colour names (those listed in :ref:`wx.ColourDatabase`), the CSS-like  ``"rgb(r,g,b)"``   or   ``"rgba(r,g,b,a)"``   syntax (case insensitive) and the HTML-like syntax:   ``"#"``   followed by 6 hexadecimal digits for red, green, blue components. 

      Returns ``True`` if the conversion was successful, ``False`` otherwise. 

                 



      .. versionadded:: 2.7.0 
     





      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **Set** `(self, red, green, blue, alpha=ALPHA_OPAQUE)`
      
      
      
      
      :param `red`: 
      :type `red`: int
      :param `green`: 
      :type `green`: int
      :param `blue`: 
      :type `blue`: int
      :param `alpha`: 
      :type `alpha`: int
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **Set** `(self, RGB)`
      
      
      
      
      :param `RGB`: 
      :type `RGB`: long
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **Set** `(self, str)`
      
      
      
      
      :param `str`: 
      :type `str`: string
      
      
      
      
      :rtype: `bool`
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: SetRGB(self, colRGB)

      Sets the ``RGB`` or ``RGBA`` colour values from a single 32 bit value.                  

      The arguments `colRGB`  and `colRGBA`  should be of the form 0x00BBGGRR and 0xAABBGGRR respectively where  ``0xRR`` ,   ``0xGG`` ,   ``0xBB``   and   ``0xAA``   are the values of the red, green, blue and alpha components. 

      Notice the right-to-left order of components! 

                


      :param `colRGB`: 
      :type `colRGB`: wx.int






      .. versionadded:: 2.9.1 
     







      .. seealso:: :meth:`GetRGB` , :meth:`GetRGBA`   








   .. method:: SetRGBA(self, colRGBA)

      Sets the ``RGB`` or ``RGBA`` colour values from a single 32 bit value.                  

      The arguments `colRGB`  and `colRGBA`  should be of the form 0x00BBGGRR and 0xAABBGGRR respectively where  ``0xRR`` ,   ``0xGG`` ,   ``0xBB``   and   ``0xAA``   are the values of the red, green, blue and alpha components. 

      Notice the right-to-left order of components! 

                


      :param `colRGBA`: 
      :type `colRGBA`: wx.int






      .. versionadded:: 2.9.1 
     







      .. seealso:: :meth:`GetRGB` , :meth:`GetRGBA`   








   .. method:: __bool__(self)



      :rtype: `int`








   .. method:: __getitem__(self, idx)




   .. method:: __len__(self)




   .. method:: __nonzero__(self)



      :rtype: `int`








   .. method:: __reduce__(self)




   .. method:: __repr__(self)




   .. method:: __setitem__(self, idx, val)




   .. method:: __str__(self)




   .. method:: _copyFrom(self, other)

      For internal use only.  





   .. method:: __ne__(self)

      Tests the inequality of two colours by comparing individual red, green, blue intensities and alpha values.                  


      :param `colour`: 
      :type `colour`: wx.Colour







   .. method:: __eq__(self)

      Tests the equality of two colours by comparing individual red, green, blue intensities and alpha values.                  


      :param `colour`: 
      :type `colour`: wx.Colour







   .. attribute:: Pixel

      See :meth:`~wx.Colour.GetPixel`


   .. attribute:: RGB

      See :meth:`~wx.Colour.GetRGB` and :meth:`~wx.Colour.SetRGB`


   .. attribute:: RGBA

      See :meth:`~wx.Colour.GetRGBA` and :meth:`~wx.Colour.SetRGBA`


   .. attribute:: alpha

      See :meth:`~wx.Colour.Alpha`


   .. attribute:: blue

      See :meth:`~wx.Colour.Blue`


   .. attribute:: green

      See :meth:`~wx.Colour.Green`


   .. attribute:: red

      See :meth:`~wx.Colour.Red`

