.. 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`. |phoenix_title| Channel Accessor Functions ========================================== Note that this class provides pairs of functions for each of the colour channels, i.e. red, green, blue and alpha values. The one word functions :meth:`~wx.Colour.Red`, :meth:`~wx.Colour.Green`, :meth:`~wx.Colour.Blue` and :meth:`~wx.Colour.Alpha` return the values of type ``unsigned`` ``char`` , while :meth:`~wx.Colour.GetRed`, :meth:`~wx.Colour.GetGreen`, :meth:`~wx.Colour.GetBlue` and :meth:`~wx.Colour.GetAlpha` returns the same value as ``unsigned`` ``int`` . According to the C++ integer promotion rules, the result of any arithmetic expression involving the former will be (signed) ``int`` , while that of the latter will be ``unsigned`` , which is what would be commonly expected, so the latter family of functions should be typically preferred (but they are only available since wxWidgets 3.1.6). .. seealso:: :ref:`wx.ColourDatabase`, :ref:`wx.Pen`, :ref:`wx.Brush`, :ref:`wx.ColourDialog`, :ref:`wx.SystemSettings` | |class_hierarchy| Class Hierarchy ================================= .. raw:: html
Inheritance diagram for class Colour:
| |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.GetAlpha` Returns the alpha value, on platforms where alpha is not yet supported, this always returns ``wx.ALPHA_OPAQUE``. :meth:`~wx.Colour.GetAsString` Converts this colour to a `String` using the given flags. :meth:`~wx.Colour.GetBlue` Returns the blue intensity as int. :meth:`~wx.Colour.GetGreen` Returns the green intensity as int. :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.GetRed` Returns the red intensity as int. :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() -> None Colour(red : int, green : int, blue : int, alpha: int=ALPHA_OPAQUE) -> None Colour(colRGB : int) -> None Colour(colour : Colour) -> None 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:`

` **__init__** `(self)` Default constructor. :rtype: `None` :html:`

` **__init__** `(self, red : int, green : int, blue : int, alpha: int=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 :rtype: `None` :html:`

` **__init__** `(self, colRGB : int)` :param `colRGB`: A packed ``RGB`` value. :type `colRGB`: long :rtype: `None` :html:`

` **__init__** `(self, colour : Colour)` Copy constructor. :param `colour`: :type `colour`: wx.Colour :rtype: `None` :html:`

` .. method:: Alpha(self) Returns the alpha value, on platforms where alpha is not yet supported, this always returns ``wx.ALPHA_OPAQUE``. :rtype: `int` .. seealso:: :meth:`GetAlpha` .. staticmethod:: AlphaBlend(fg : int, bg : int, alpha : float) 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` .. seealso:: :meth:`GetBlue` .. method:: ChangeLightness(self, *args, **kw) |overload| **Overloaded Implementations:** :html:`

` **ChangeLightness** `(self, ialpha : int)` :ref:`wx.Colour` wrapper for ChangeLightness(r,g,b,ialpha). :param `ialpha`: :type `ialpha`: int :rtype: :ref:`wx.Colour` .. versionadded:: 2.9.0 :html:`

` **ChangeLightness** `(r : int, g : int, b : int, ialpha : int)` 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: :ref:`Tuple[int, int, int]` .. versionadded:: 2.9.0 :html:`

` .. 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:: GetAlpha(self) Returns the alpha value, on platforms where alpha is not yet supported, this always returns ``wx.ALPHA_OPAQUE``. :rtype: `int` .. versionadded:: 4.1/wxWidgets-3.1.6 .. method:: GetAsString(self, flags: int=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. :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: `str` .. versionadded:: 2.7.0 .. note:: For non-solid (i.e. non-RGB) colour this function returns "rgb(??, ?? ??)" or "#??????". .. method:: GetBlue(self) Returns the blue intensity as int. :rtype: `int` .. versionadded:: 4.1/wxWidgets-3.1.6 .. method:: GetGreen(self) Returns the green intensity as int. :rtype: `int` .. versionadded:: 4.1/wxWidgets-3.1.6 .. 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: `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: `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: `wx.int` .. versionadded:: 2.9.1 .. method:: GetRed(self) Returns the red intensity as int. :rtype: `int` .. versionadded:: 4.1/wxWidgets-3.1.6 .. method:: Green(self) Returns the green intensity. :rtype: `int` .. seealso:: :meth:`GetGreen` .. 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` .. versionadded:: 4.1/wxWidgets-3.1.2 .. method:: MakeDisabled(self, *args, **kw) |overload| **Overloaded Implementations:** :html:`

` **MakeDisabled** `(self, brightness: int=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:`

` **MakeDisabled** `(r : int, g : int, b : int, brightness: int=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: :ref:`Tuple[int, int, int]` .. versionadded:: 2.9.0 :html:`

` .. staticmethod:: MakeGrey(*args, **kw) |overload| **Overloaded Implementations:** :html:`

` **MakeGrey** `(r : int, g : int, b : int)` 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: :ref:`Tuple[int, int, int]` .. versionadded:: 2.9.0 :html:`

` **MakeGrey** `(r : int, g : int, b : int, weight_r : float, weight_g : float, weight_b : float)` 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: :ref:`Tuple[int, int, int]` .. versionadded:: 2.9.0 :html:`

` .. staticmethod:: MakeMono(on : bool) Assigns the same value to `r`, `g`, `b:` 0 if `on` is ``false`` , 255 otherwise. :param `on`: :type `on`: bool :rtype: :ref:`Tuple[int, int, int]` .. versionadded:: 2.9.0 .. method:: Red(self) Returns the red intensity. :rtype: `int` .. seealso:: :meth:`GetRed` .. 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:`

` **Set** `(self, red : int, green : int, blue : int, alpha: int=ALPHA_OPAQUE)` :param `red`: :type `red`: int :param `green`: :type `green`: int :param `blue`: :type `blue`: int :param `alpha`: :type `alpha`: int :rtype: `None` :html:`

` **Set** `(self, RGB : int)` :param `RGB`: :type `RGB`: long :rtype: `None` :html:`

` **Set** `(self, str : str)` :param `str`: :type `str`: string :rtype: `bool` :html:`

` .. method:: SetRGB(self, colRGB : Uint32) 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 :rtype: `None` .. versionadded:: 2.9.1 .. seealso:: :meth:`GetRGB` , :meth:`GetRGBA` .. method:: SetRGBA(self, colRGBA : Uint32) 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 :rtype: `None` .. 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: Colour) For internal use only. :rtype: `None` .. 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`