.. include:: headings.inc .. _Colour: ========================================================================================================================================== |phoenix_title| **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 :ref:`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:`SystemSettings`. .. seealso:: :ref:`ColourDatabase`, :ref:`Pen`, :ref:`Brush`, :ref:`ColourDialog`, :ref:`SystemSettings` | |class_hierarchy| Inheritance Diagram ===================================== Inheritance diagram for class **Colour** .. raw:: html

Inheritance diagram of Colour

| |method_summary| Methods Summary ================================ ================================================================================ ================================================================================ :meth:`~Colour.__init__` Default constructor. :meth:`~Colour.Alpha` Returns the alpha value, on platforms where alpha is not yet supported, this always returns ``ALPHA_OPAQUE``. :meth:`~Colour.AlphaBlend` Blend colour, taking alpha into account. :meth:`~Colour.Blue` Returns the blue intensity. :meth:`~Colour.ChangeLightness` :ref:`Colour` wrapper for ChangeLightness(r,g,b,ialpha). :meth:`~Colour.Get` Get(includeAlpha=False) -> (r,g,b) or (r,g,b,a) :meth:`~Colour.GetAsString` Converts this colour to a `String` using the given flags. :meth:`~Colour.GetRGB` Gets the ``RGB`` or ``RGBA`` colour values as a single 32 bit value. :meth:`~Colour.GetRGBA` Gets the ``RGB`` or ``RGBA`` colour values as a single 32 bit value. :meth:`~Colour.Green` Returns the green intensity. :meth:`~Colour.IsOk` Returns ``True`` if the colour object is valid (the colour has been initialised with ``RGB`` values). :meth:`~Colour.MakeDisabled` Create a disabled (dimmed) colour from (in/out) rgb parameters. :meth:`~Colour.MakeGrey` Create a grey colour from (in/out) rgb parameters using integer arithmetic. :meth:`~Colour.MakeMono` Assign 0 or 255 to rgb out parameters. :meth:`~Colour.Red` Returns the red intensity. :meth:`~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:`~Colour.SetRGB` Sets the ``RGB`` or ``RGBA`` colour values from a single 32 bit value. :meth:`~Colour.SetRGBA` Sets the ``RGB`` or ``RGBA`` colour values from a single 32 bit value. :meth:`~Colour.__getitem__` :meth:`~Colour.__len__` :meth:`~Colour.__nonzero__` :meth:`~Colour.__reduce__` :meth:`~Colour.__repr__` :meth:`~Colour.__setitem__` :meth:`~Colour.__str__` :meth:`~Colour._copyFrom` For internal use only. :meth:`~Colour.__ne__` Tests the inequality of two colours by comparing individual red, green, blue colours and alpha values. :meth:`~Colour.__eq__` Tests the equality of two colours by comparing individual red, green, blue colours and alpha values. ================================================================================ ================================================================================ | |property_summary| Properties Summary ===================================== ================================================================================ ================================================================================ :attr:`~Colour.Pixel` See :meth:`~Colour.GetPixel` :attr:`~Colour.RGB` See :meth:`~Colour.GetRGB` and :meth:`~Colour.SetRGB` :attr:`~Colour.RGBA` See :meth:`~Colour.GetRGBA` and :meth:`~Colour.SetRGBA` :attr:`~Colour.alpha` See :meth:`~Colour.Alpha` :attr:`~Colour.blue` See :meth:`~Colour.Blue` :attr:`~Colour.green` See :meth:`~Colour.Green` :attr:`~Colour.red` See :meth:`~Colour.Red` ================================================================================ ================================================================================ | |api| Class API =============== .. class:: Colour(Object) A colour is an object representing a combination of Red, Green, and Blue (``RGB``) intensity values, and is used to determine drawing colours. **Possible constructors**:: Colour() Colour(red, green, blue, alpha=ALPHA_OPAQUE) Colour(colRGB) Colour(colour) .. method:: __init__(self, *args, **kw) |overload| **Overloaded Implementations**: **~~~** **__init__** `(self)` Default constructor. **~~~** **__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 (``ALPHA_TRANSPARENT``) to 255 (``ALPHA_OPAQUE``). :type `alpha`: int **~~~** **__init__** `(self, colRGB)` :param `colRGB`: A packed ``RGB`` value. :type `colRGB`: long **~~~** **__init__** `(self, colour)` Copy constructor. :param `colour`: :type `colour`: Colour **~~~** .. method:: Alpha(self) Returns the alpha value, on platforms where alpha is not yet supported, this always returns ``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**: **~~~** **ChangeLightness** `(self, ialpha)` :ref:`Colour` wrapper for ChangeLightness(r,g,b,ialpha). :param `ialpha`: :type `ialpha`: int :rtype: :ref:`Colour` .. versionadded:: 2.9.0 **~~~** **ChangeLightness** `(r, g, b, ialpha)` :meth:`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. :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 **~~~** .. method:: Get(self, includeAlpha=True) Get(includeAlpha=False) -> (r,g,b) or (r,g,b,a) Returns the ``RGB`` intensity values as a tuple, optionally the alpha value as well. :rtype: `PyObject` .. method:: GetAsString(self, flags=C2S_NAME|C2S_CSS_SYNTAX) Converts this colour to a `String` using the given flags. The supported flags are ``C2S_NAME`` , to obtain the colour name (e.g. Colour(255,0,0) == "red"), ``C2S_CSS_SYNTAX`` , to obtain the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g. Colour(255,0,0,85) == "rgba(255,0,0,0.333)"), and ``C2S_HTML_SYNTAX`` , to obtain the colour as "#" followed by 6 hexadecimal digits (e.g. Colour(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 ``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 .. 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: `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: `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` .. staticmethod:: 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 .. staticmethod:: MakeGrey(*args, **kw) |overload| **Overloaded Implementations**: **~~~** **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 **~~~** **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 **~~~** .. staticmethod:: MakeMono(on) Assign 0 or 255 to rgb out parameters. :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:`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**: **~~~** **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 **~~~** **Set** `(self, RGB)` :param `RGB`: :type `RGB`: long **~~~** **Set** `(self, str)` :param `str`: :type `str`: string :rtype: `bool` **~~~** .. 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, blue, green and alpha components. Notice the right-to-left order of components! :param `colRGB`: :type `colRGB`: 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, blue, green and alpha components. Notice the right-to-left order of components! :param `colRGBA`: :type `colRGBA`: int .. versionadded:: 2.9.1 .. seealso:: :meth:`GetRGB` , :meth:`GetRGBA` .. method:: __getitem__(self, idx) .. method:: __len__(self) .. method:: __nonzero__(self) .. 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 colours and alpha values. :param `colour`: :type `colour`: Colour .. method:: __eq__(self) Tests the equality of two colours by comparing individual red, green, blue colours and alpha values. :param `colour`: :type `colour`: Colour .. attribute:: Pixel See :meth:`~Colour.GetPixel` .. attribute:: RGB See :meth:`~Colour.GetRGB` and :meth:`~Colour.SetRGB` .. attribute:: RGBA See :meth:`~Colour.GetRGBA` and :meth:`~Colour.SetRGBA` .. attribute:: alpha See :meth:`~Colour.Alpha` .. attribute:: blue See :meth:`~Colour.Blue` .. attribute:: green See :meth:`~Colour.Green` .. attribute:: red See :meth:`~Colour.Red`