Version: 3.3.0
wxColourDatabase Class Reference

#include <wx/gdicmn.h>

Detailed Description

wxWidgets maintains a database of standard RGB colours for a predefined set of named colours.

The application may add to this set if desired by using AddColour() and may use it to look up colours by names using Find() or find the names for the standard colour using FindName().

It is also possible to switch between the colour values defined in the CSS standard (see https://www.w3.org/TR/css-color-4/#named-colors) and the traditional colour values which were used by wxWidgets versions earlier than 3.3.0, which may be useful to preserve the appearance of the existing code: if you need to do this, please call UseScheme() with Traditional argument, but the use of new, standard colours is recommended.

There is one predefined, global instance of this class called wxTheColourDatabase.

The standard database contains at least the following colours:

AQUAMARINE
BLACK
BLUE
BLUE VIOLET
BROWN
CADET BLUE
CORAL
CORNFLOWER BLUE
CYAN
DARK GREY
DARK GREEN
DARK OLIVE GREEN
DARK ORCHID
DARK SLATE BLUE
DARK SLATE GREY
DARK TURQUOISE
DIM GREY
FIREBRICK
FOREST GREEN
GOLD
GOLDENROD
GREY
GREEN
GREEN YELLOW
INDIAN RED
KHAKI
LIGHT BLUE
LIGHT GREY
LIGHT STEEL BLUE
LIME GREEN
MAGENTA
MAROON
MEDIUM AQUAMARINE
MEDIUM BLUE
MEDIUM FOREST GREEN
MEDIUM GOLDENROD
MEDIUM ORCHID
MEDIUM SEA GREEN
MEDIUM SLATE BLUE
MEDIUM SPRING GREEN
MEDIUM TURQUOISE
MEDIUM VIOLET RED
MIDNIGHT BLUE
NAVY
ORANGE
ORANGE RED
ORCHID
PALE GREEN
PINK
PLUM
PURPLE
RED
SALMON
SEA GREEN
SIENNA
SKY BLUE
SLATE BLUE
SPRING GREEN
STEEL BLUE
TAN
THISTLE
TURQUOISE
VIOLET
VIOLET RED
WHEAT
WHITE
YELLOW
YELLOW GREEN

See the "Database colours" page of the Drawing Sample to see how all these colours look like.

Library:  wxCore
Category:  Graphics Device Interface (GDI)
See also
wxColour

Public Types

enum  Scheme {
  CSS ,
  Traditional
}
 Possible colour schemes for UseScheme(). More...
 

Public Member Functions

 wxColourDatabase ()
 Constructs the colour database. More...
 
void AddColour (const wxString &colourName, const wxColour &colour)
 Adds a colour to the database. More...
 
wxColour Find (const wxString &colourName) const
 Finds a colour given the name. More...
 
wxString FindName (const wxColour &colour) const
 Finds a colour name given the colour. More...
 
wxVector< wxStringGetAllNames () const
 List all known colours by name. More...
 
void UseScheme (Scheme scheme)
 Select the colour scheme to use. More...
 

Member Enumeration Documentation

◆ Scheme

Possible colour schemes for UseScheme().

Since
3.3.0
Enumerator
CSS 

Use CSS standard colours, default since 3.3.0.

Traditional 

Use traditional wxWidgets colours for compatibility.

Constructor & Destructor Documentation

◆ wxColourDatabase()

wxColourDatabase::wxColourDatabase ( )

Constructs the colour database.

It will be initialized at the first use.

Member Function Documentation

◆ AddColour()

void wxColourDatabase::AddColour ( const wxString colourName,
const wxColour colour 
)

Adds a colour to the database.

If a colour with the same name already exists, it is replaced.

◆ Find()

wxColour wxColourDatabase::Find ( const wxString colourName) const

Finds a colour given the name.

Returns an invalid colour object (that is, wxColour::IsOk() will return false) if the colour wasn't found in the database.

◆ FindName()

wxString wxColourDatabase::FindName ( const wxColour colour) const

Finds a colour name given the colour.

Returns an empty string if the colour is not found in the database.

◆ GetAllNames()

wxVector<wxString> wxColourDatabase::GetAllNames ( ) const

List all known colours by name.

Since
3.3.0

◆ UseScheme()

void wxColourDatabase::UseScheme ( Scheme  scheme)

Select the colour scheme to use.

By default, wxColourDatabase uses CSS scheme which returns the standard values for the colours defined in the CSS specification, see https://www.w3.org/TR/css-color-4/#named-colors

If preserving compatibility with the behaviour and appearance of the previous wxWidgets versions is important, you may switch to the traditional colour scheme by using this function with Traditional argument, e.g. call

@ Traditional
Use traditional wxWidgets colours for compatibility.
Definition: gdicmn.h:958
void UseScheme(Scheme scheme)
Select the colour scheme to use.
wxColourDatabase * wxTheColourDatabase
Global instance of a wxColourDatabase.
Definition: gdicmn.h:1005

during the application initialization. Please note that in the previous versions wxGTK already used CSS colour values, unlike all the other ports, so Traditional is not actually backwards compatible for wxGTK, but does make the colour values consistent across all platforms and the same as had been used by wxMSW and wxOSX before. In other words, to obtain 100% compatibility with the previous versions, the UseScheme() call above should be made for all ports except wxGTK.

Note that the colour names defined only by wxWidgets, which notably includes all colour variants with spaces in their names, are still available in the default CSS colour scheme, with their traditional values but the names of colours defined by CSS standard are taken from it, e.g. "GREEN" corresponds to #00ff00 in the traditional scheme but to #008000 in the CSS scheme. Similarly, CSS colour names that were not defined by the previous wxWidgets versions are available even when using the traditional scheme, the scheme choice only affects the values of the colours defined by both wxWidgets and CSS with different values.

Since
3.3.0