.. 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
<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.svg" 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="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." alt="" coords="5,82,106,111"/> <area shape="rect" id="node2" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="6,5,105,34"/> </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.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, green, blue, alpha=ALPHA_OPAQUE) -> None
Colour(colRGB) -> None
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:`<hr class="overloadsep" /><br />`
**__init__** `(self)`
Default constructor.
:rtype: `None`
: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
:rtype: `None`
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, colRGB)`
:param `colRGB`: A packed ``RGB`` value.
:type `colRGB`: long
:rtype: `None`
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, colour)`
Copy constructor.
:param `colour`:
:type `colour`: wx.Colour
:rtype: `None`
: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`
.. seealso:: :meth:`GetAlpha`
.. 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`
.. seealso:: :meth:`GetBlue`
.. 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: :ref:`Tuple[int, int, int]`
.. 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: `Any`
.. 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=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:`<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: :ref:`Tuple[int, int, int]`
.. 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: :ref:`Tuple[int, int, int]`
.. 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: :ref:`Tuple[int, int, int]`
.. 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: :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:`<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
:rtype: `None`
:html:`<hr class="overloadsep" /><br />`
**Set** `(self, RGB)`
:param `RGB`:
:type `RGB`: long
:rtype: `None`
: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
:rtype: `None`
.. 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
:rtype: `None`
.. versionadded:: 2.9.1
.. seealso:: :meth:`GetRGB` , :meth:`GetRGBA`
.. method:: __bool__(self)
:rtype: `bool`
.. method:: __getitem__(self, idx)
.. method:: __len__(self)
.. method:: __nonzero__(self)
:rtype: `bool`
.. method:: __reduce__(self)
.. method:: __repr__(self)
.. method:: __setitem__(self, idx, val)
.. method:: __str__(self)
.. method:: _copyFrom(self, other)
For internal use only.
:rtype: `None`
.. method:: __ne__(self, colour)
Tests the inequality of two colours by comparing individual red, green, blue intensities and alpha values.
:param `colour`:
:type `colour`: wx.Colour
:rtype: `bool`
.. method:: __eq__(self, colour)
Tests the equality of two colours by comparing individual red, green, blue intensities and alpha values.
:param `colour`:
:type `colour`: wx.Colour
:rtype: `bool`
.. 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`