| Version: 3.3.1

Public Member Functions | Static Public Member Functions | List of all members
wxColour Class Reference
Class List by Category » Graphics Device Interface (GDI)

`#include <wx/colour.h>`

Inheritance diagram for wxColour:
[legend]

## Detailed Description

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 wxColourDatabase 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 wxSystemSettings.

# 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 Red(), Green(), Blue() and Alpha() return the values of type `unsigned` `char`, while GetRed(), GetGreen(), GetBlue() and 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).

##

Library: wxCore
Category: Graphics Device Interface (GDI)

Predefined objects/pointers:

- 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

See also
  wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings

## Public Member Functions
| wxColour ()
| Default constructor. More...
| wxColour (unsigned char red, unsigned char green, unsigned char blue, unsigned char alpha=wxALPHA_OPAQUE)
| wxColour (const wxString &colourName)
| wxColour (unsigned long colRGB)
| wxColour (const wxColour &colour)
| Copy constructor. More...
virtual unsigned char | Alpha () const
| Returns the alpha value, on platforms where alpha is not yet supported, this always returns wxALPHA_OPAQUE. More...
virtual unsigned char | Blue () const
| Returns the blue intensity. More...
unsigned int | GetAlpha () const
| Returns the alpha value, on platforms where alpha is not yet supported, this always returns wxALPHA_OPAQUE. More...
unsigned int | GetBlue () const
| Returns the blue intensity as unsigned int. More...
unsigned int | GetGreen () const
| Returns the green intensity as unsigned int. More...
unsigned int | GetRed () const
| Returns the red intensity as unsigned int. More...
virtual wxString | GetAsString (long flags=wxC2S_NAME|wxC2S_CSS_SYNTAX) const
| Converts this colour to a wxString using the given flags. More...
double | GetLuminance () const
| Return the perceived brightness of the colour. More...
wxIntPtr | GetPixel () const
| Returns a pixel value which is platform-dependent. More...
virtual unsigned char | Green () const
| Returns the green intensity. More...
virtual bool | IsOk () const
| Returns true if the colour object is valid (the colour has been initialised with RGB values). More...
virtual unsigned char | Red () const
| Returns the red intensity. More...
virtual bool | IsSolid () const
| Returns true if the color can be described using RGB values, i.e. More...
bool | IsTransparent () const
| Returns true if the color is completely transparent (i.e., no opacity). More...
bool | IsOpaque () const
| Returns true if the color is completely opaque (i.e., full opacity). More...
bool | IsTranslucent () const
| Returns true if the color has some translucency (not fully opaque, but not transparent either). More...
bool | operator!= (const wxColour &colour) const
| Tests the inequality of two colours by comparing individual red, green, blue intensities and alpha values. More...
wxColour & | operator= (const wxColour &colour)
| Assignment operator. More...
bool | operator== (const wxColour &colour) const
| Tests the equality of two colours by comparing individual red, green, blue intensities and alpha values. More...
wxColour & | MakeDisabled (unsigned char brightness=255)
| Make a disabled version of this colour. More...
wxColour | ChangeLightness (int ialpha) const
| wxColour wrapper for ChangeLightness(r,g,b,ialpha). More...
void | SetRGB (wxUint32 colRGB)
| Sets the RGB or RGBA colour values from a single 32 bit value. More...
void | SetRGBA (wxUint32 colRGBA)
| Sets the RGB or RGBA colour values from a single 32 bit value. More...
wxUint32 | GetRGB () const
| Gets the RGB or RGBA colour values as a single 32 bit value. More...
wxUint32 | GetRGBA () const
| Gets the RGB or RGBA colour values as a single 32 bit value. More...
void | Set (unsigned char red, unsigned char green, unsigned char blue, unsigned char alpha=wxALPHA_OPAQUE)
| 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). More...
void | Set (unsigned long RGB)
| 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). More...
bool | Set (const wxString &str)
| 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). More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to nullptr the internal reference data. More...
| wxObject (const wxObject &other)
| Copy ctor. More...
virtual | ~wxObject ()
| Destructor. More...
virtual wxClassInfo * | GetClassInfo () const
| This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
wxObjectRefData * | GetRefData () const
| Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
bool | IsKindOf (const wxClassInfo *info) const
| Determines whether this class is a subclass of (or the same class as) the given class. More...
bool | IsSameAs (const wxObject &obj) const
| Returns true if this object has the same data pointer as obj. More...
void | Ref (const wxObject &clone)
| Makes this object refer to the data in clone. More...
void | SetRefData (wxObjectRefData *data)
| Sets the wxObject::m_refData pointer. More...
void | UnRef ()
| Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
void | UnShare ()
| This is the same of AllocExclusive() but this method is public. More...
void | operator delete (void *buf)
| The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...
void * | operator new (size_t size, const wxString &filename=nullptr, int lineNum=0)
| The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

## Static Public Member Functions
static void | MakeMono (unsigned char *r, unsigned char *g, unsigned char *b, bool on)
| Assigns the same value to r, g, b: 0 if on is `false`, 255 otherwise. More...
static void | MakeDisabled (unsigned char *r, unsigned char *g, unsigned char *b, unsigned char brightness=255)
| Create a disabled (dimmed) colour from (in/out) rgb parameters. More...
static void | MakeGrey (unsigned char *r, unsigned char *g, unsigned char *b)
| Create a grey colour from (in/out) rgb parameters using integer arithmetic. More...
static void | MakeGrey (unsigned char *r, unsigned char *g, unsigned char *b, double weight_r, double weight_g, double weight_b)
| Create a grey colour from (in/out) rgb parameters using floating point arithmetic. More...
static unsigned char | AlphaBlend (unsigned char fg, unsigned char bg, double alpha)
| Blend colour, taking alpha into account. More...
static void | ChangeLightness (unsigned char *r, unsigned char *g, unsigned char *b, int ialpha)
| Utility function that simply darkens or lightens a color, based on the specified percentage ialpha. More...

## Additional Inherited Members
Protected Member Functions inherited from wxObject
void | AllocExclusive ()
| Ensure that this object's data is not shared with any other object. More...
virtual wxObjectRefData * | CreateRefData () const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
virtual wxObjectRefData * | CloneRefData (const wxObjectRefData *data) const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...
Protected Attributes inherited from wxObject
wxObjectRefData * | m_refData
| Pointer to an object which is the object's reference-counted data. More...

## Constructor & Destructor Documentation

## ◆ wxColour() [1/5]

wxColour::wxColour | ( |  | ) |

Default constructor.

## ◆ wxColour() [2/5]

wxColour::wxColour | ( | unsigned char | red,
|  | unsigned char | green,
|  | unsigned char | blue,
|  | unsigned char | alpha = `wxALPHA_OPAQUE`
| ) |  |

Parameters

  red | The red value.
  green | The green value.
  blue | The blue value.
  alpha | The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255 (wxALPHA_OPAQUE).

## ◆ wxColour() [3/5]

wxColour::wxColour | ( | const wxString & | colourName | ) |

Parameters

  colourName | The colour name.

## ◆ wxColour() [4/5]

wxColour::wxColour | ( | unsigned long | colRGB | ) |

Parameters

  colRGB | A packed RGB value.

## ◆ wxColour() [5/5]

wxColour::wxColour | ( | const wxColour & | colour | ) |

Copy constructor.

## Member Function Documentation

## ◆ Alpha()

virtual unsigned char wxColour::Alpha | ( |  | ) | const
| virtual

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

See also
  GetAlpha()

## ◆ AlphaBlend()

static unsigned char wxColour::AlphaBlend | ( | unsigned char | fg,
|  | unsigned char | bg,
|  | double | alpha
| ) |  |
| static

Blend colour, taking alpha into account.

Since
  2.9.0

## ◆ Blue()

virtual unsigned char wxColour::Blue | ( |  | ) | const
| virtual

Returns the blue intensity.

See also
  GetBlue()

## ◆ ChangeLightness() [1/2]

wxColour wxColour::ChangeLightness | ( | int | ialpha | ) | const

wxColour wrapper for ChangeLightness(r,g,b,ialpha).

Since
  2.9.0

## ◆ ChangeLightness() [2/2]

static void wxColour::ChangeLightness | ( | unsigned char * | r,
|  | unsigned char * | g,
|  | unsigned char * | b,
|  | int | ialpha
| ) |  |
| static

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.

Since
  2.9.0

## ◆ GetAlpha()

unsigned int wxColour::GetAlpha | ( |  | ) | const

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

Since
  3.1.6

## ◆ GetAsString()

virtual wxString wxColour::GetAsString | ( | long | flags = `wxC2S_NAME|wxC2S_CSS_SYNTAX` | ) | const
| virtual

Converts this colour to a wxString using the given flags.

The supported flags are `wxC2S_NAME`, to obtain the colour name (e.g. wxColour(255,0,0) == "red"), `wxC2S_CSS_SYNTAX`, to obtain the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax (e.g. wxColour(255,0,0,85) == "rgba(255,0,0,0.333)"), and `wxC2S_HTML_SYNTAX`, to obtain the colour as "#" followed by 6 hexadecimal digits (e.g. wxColour(255,0,0) == "#FF0000").

This function returns empty string if the colour is not initialized (see 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 `wxC2S_CSS_SYNTAX` (which is the only one supporting alpha) is not specified in flags.

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

Since
  2.7.0

## ◆ GetBlue()

unsigned int wxColour::GetBlue | ( |  | ) | const

Returns the blue intensity as unsigned int.

Since
  3.1.6

## ◆ GetGreen()

unsigned int wxColour::GetGreen | ( |  | ) | const

Returns the green intensity as unsigned int.

Since
  3.1.6

## ◆ GetLuminance()

double wxColour::GetLuminance | ( |  | ) | const

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.

Since
  3.1.3

## ◆ GetPixel()

wxIntPtr wxColour::GetPixel | ( |  | ) | const

Returns a pixel value which is platform-dependent.

On Windows, a COLORREF is returned. On X, an allocated pixel value is returned. If the pixel is invalid (on X, unallocated), `-1` is returned.

## ◆ GetRed()

unsigned int wxColour::GetRed | ( |  | ) | const

Returns the red intensity as unsigned int.

Since
  3.1.6

## ◆ GetRGB()

wxUint32 wxColour::GetRGB | ( |  | ) | const

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 `0xFFBBGGRR` while that of GetRGB() is `0x00BBGGRR`.

Since
  2.9.1

## ◆ GetRGBA()

wxUint32 wxColour::GetRGBA | ( |  | ) | const

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 `0xFFBBGGRR` while that of GetRGB() is `0x00BBGGRR`.

Since
  2.9.1

## ◆ Green()

virtual unsigned char wxColour::Green | ( |  | ) | const
| virtual

Returns the green intensity.

See also
  GetGreen()

## ◆ IsOk()

virtual bool wxColour::IsOk | ( |  | ) | const
| virtual

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

## ◆ IsOpaque()

bool wxColour::IsOpaque | ( |  | ) | const

Returns true if the color is completely opaque (i.e., full opacity).

Since
  3.3.1

## ◆ IsSolid()

virtual bool wxColour::IsSolid | ( |  | ) | const
| virtual

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)

Since
  3.1.2

## ◆ IsTranslucent()

bool wxColour::IsTranslucent | ( |  | ) | const

Returns true if the color has some translucency (not fully opaque, but not transparent either).

Since
  3.3.1

## ◆ IsTransparent()

bool wxColour::IsTransparent | ( |  | ) | const

Returns true if the color is completely transparent (i.e., no opacity).

Since
  3.3.1

## ◆ MakeDisabled() [1/2]

static void wxColour::MakeDisabled | ( | unsigned char * | r,
|  | unsigned char * | g,
|  | unsigned char * | b,
|  | unsigned char | brightness = `255`
| ) |  |
| static

Create a disabled (dimmed) colour from (in/out) rgb parameters.

Since
  2.9.0

## ◆ MakeDisabled() [2/2]

wxColour& wxColour::MakeDisabled | ( | unsigned char | brightness = `255` | ) |

Make a disabled version of this colour.

This method modifies the object in place and returns the object itself.

Since
  2.9.5

## ◆ MakeGrey() [1/2]

static void wxColour::MakeGrey | ( | unsigned char * | r,
|  | unsigned char * | g,
|  | unsigned char * | b
| ) |  |
| static

Create a grey colour from (in/out) rgb parameters using integer arithmetic.

Since
  2.9.0

## ◆ MakeGrey() [2/2]

static void wxColour::MakeGrey | ( | unsigned char * | r,
|  | unsigned char * | g,
|  | unsigned char * | b,
|  | double | weight_r,
|  | double | weight_g,
|  | double | weight_b
| ) |  |
| static

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).

Since
  2.9.0

## ◆ MakeMono()

static void wxColour::MakeMono | ( | unsigned char * | r,
|  | unsigned char * | g,
|  | unsigned char * | b,
|  | bool | on
| ) |  |
| static

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

Since
  2.9.0

## ◆ operator!=()

bool wxColour::operator!= | ( | const wxColour & | colour | ) | const

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

## ◆ operator=()

wxColour& wxColour::operator= | ( | const wxColour & | colour | ) |

Assignment operator.

See also
  wxColourDatabase

## ◆ operator==()

bool wxColour::operator== | ( | const wxColour & | colour | ) | const

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

## ◆ Red()

virtual unsigned char wxColour::Red | ( |  | ) | const
| virtual

Returns the red intensity.

See also
  GetRed()

## ◆ Set() [1/3]

bool wxColour::Set | ( | const wxString & | str | ) |

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, Set() accepts: colour names (those listed in wxColourDatabase), 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.

Since
  2.7.0

## ◆ Set() [2/3]

void wxColour::Set | ( | unsigned char | red,
|  | unsigned char | green,
|  | unsigned char | blue,
|  | unsigned char | alpha = `wxALPHA_OPAQUE`
| ) |  |

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, Set() accepts: colour names (those listed in wxColourDatabase), 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.

Since
  2.7.0

## ◆ Set() [3/3]

void wxColour::Set | ( | unsigned long | RGB | ) |

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, Set() accepts: colour names (those listed in wxColourDatabase), 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.

Since
  2.7.0

## ◆ SetRGB()

void wxColour::SetRGB | ( | wxUint32 | 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!

See also
  GetRGB(), GetRGBA()

Since
  2.9.1

## ◆ SetRGBA()

void wxColour::SetRGBA | ( | wxUint32 | 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!

See also
  GetRGB(), GetRGBA()

Since
  2.9.1