[wxWidgets.git] / docs / latex / wx / colour.tex

\section{\class{wxColour}}\label{wxcolour}

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 \helpref{wxColourDatabase}{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.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/colour.h>

\wxheading{Predefined objects}

Objects:

{\bf wxNullColour}

Pointers:

{\bf wxBLACK\\
wxWHITE\\
wxRED\\
wxBLUE\\
wxGREEN\\
wxCYAN\\
wxLIGHT\_GREY}

\wxheading{See also}

\helpref{wxColourDatabase}{wxcolourdatabase}, \helpref{wxPen}{wxpen}, \helpref{wxBrush}{wxbrush},\rtfsp
\helpref{wxColourDialog}{wxcolourdialog}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxColour::wxColour}\label{wxcolourconstr}

\func{}{wxColour}{\void}

Default constructor.

\func{}{wxColour}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}}

Constructs a colour from red, green and blue values.

\func{}{wxColour}{\param{const wxString\& }{colourNname}}

Constructs a colour object using a colour name
listed in {\bf wxTheColourDatabase}.

\func{}{wxColour}{\param{const wxColour\&}{ colour}}

Copy constructor.

\wxheading{Parameters}

\docparam{red}{The red value.}

\docparam{green}{The green value.}

\docparam{blue}{The blue value.}

\docparam{colourName}{The colour name.}

\docparam{colour}{The colour to copy.}

\wxheading{See also}

\helpref{wxColourDatabase}{wxcolourdatabase}

\pythonnote{Constructors supported by wxPython are:\par
\indented{2cm}{\begin{twocollist}
\twocolitem{\bf{wxColour(red=0, green=0, blue=0)}}{}
\twocolitem{\bf{wxNamedColour(name)}}{}
\end{twocollist}}
}


\membersection{wxColour::Blue}\label{wxcolourblue}

\constfunc{unsigned char}{Blue}{\void}

Returns the blue intensity.

\membersection{wxColour::GetPixel}\label{wxcolourgetpixel}

\constfunc{long}{GetPixel}{\void}

Returns a pixel value which is platform-dependent. On Windows, a COLORREF is returned.
On X, an allocated pixel value is returned.

-1 is returned if the pixel is invalid (on X, unallocated).

\membersection{wxColour::Green}\label{wxcolourgreen}

\constfunc{unsigned char}{Green}{\void}

Returns the green intensity.

\membersection{wxColour::Ok}\label{wxcolourok}

\constfunc{bool}{Ok}{\void}

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

\membersection{wxColour::Red}\label{wxcolourred}

\constfunc{unsigned char}{Red}{\void}

Returns the red intensity.

\membersection{wxColour::Set}\label{wxcolourset}

\func{void}{Set}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}}

Sets the RGB intensity values.

\membersection{wxColour::operator $=$}\label{wxcolourassign}

\func{wxColour\&}{operator $=$}{\param{const wxColour\&}{ colour}}

Assignment operator, taking another colour object.

\func{wxColour\&}{operator $=$}{\param{const wxString\&}{ colourName}}

Assignment operator, using a colour name to be found in the colour database.

\wxheading{See also}

\helpref{wxColourDatabase}{wxcolourdatabase}

\membersection{wxColour::operator $==$}\label{wxcolourequality}

\func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}

Tests the equality of two colours by comparing individual red, green blue colours.

\membersection{wxColour::operator $!=$}\label{wxcolourinequality}

\func{bool}{operator $!=$}{\param{const wxColour\&}{ colour}}

Tests the inequality of two colours by comparing individual red, green blue colours.

\section{\class{wxColourData}}\label{wxcolourdata}

This class holds a variety of information related to colour dialogs.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/cmndata.h>

\wxheading{See also}

\helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxColourData::wxColourData}\label{wxcolourdataconstr}

\func{}{wxColourData}{\void}

Constructor. Initializes the custom colours to white, the {\it data colour} setting
to black, and the {\it choose full} setting to TRUE.

\membersection{wxColourData::\destruct{wxColourData}}

\func{}{\destruct{wxColourData}}{\void}

Destructor.

\membersection{wxColourData::GetChooseFull}\label{wxcolourdatagetchoosefull}

\constfunc{bool}{GetChooseFull}{\void}

Under Windows, determines whether the Windows colour dialog will display the full dialog
with custom colour selection controls. Has no meaning under other platforms.

The default value is TRUE.

\membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour}

\constfunc{wxColour\&}{GetColour}{\void}

Gets the current colour associated with the colour dialog.

The default colour is black.

\membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour}

\constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}}

Gets the {\it i}th custom colour associated with the colour dialog. {\it i} should
be an integer between 0 and 15.

The default custom colours are all white.

\membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull}

\func{void}{SetChooseFull}{\param{const bool }{flag}}

Under Windows, tells the Windows colour dialog to display the full dialog
with custom colour selection controls. Under other platforms, has no effect.

The default value is TRUE.

\membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour}

\func{void}{SetColour}{\param{const wxColour\&}{ colour}}

Sets the default colour for the colour dialog.

The default colour is black.

\membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour}

\func{void}{SetColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}}

Sets the {\it i}th custom colour for the colour dialog. {\it i} should
be an integer between 0 and 15.

The default custom colours are all white.

\membersection{wxColourData::operator $=$}\label{wxcolourdataassign}

\func{void}{operator $=$}{\param{const wxColourData\&}{ data}}

Assingment operator for the colour data.

\section{\class{wxColourDatabase}}\label{wxcolourdatabase}

wxWindows maintains a database of standard RGB colours for a predefined
set of named colours (such as ``BLACK'', ``LIGHT GREY''). The
application may add to this set if desired by using {\it Append}.  There
is only one instance of this class: {\bf wxTheColourDatabase}.

\wxheading{Derived from}

\helpref{wxList}{wxlist}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/gdicmn.h>

\wxheading{Remarks}

The colours in the standard database are as follows:

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.

\wxheading{See also}

\helpref{wxColour}{wxcolour}

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxColourDatabase::wxColourDatabase}\label{wxcolourdatabaseconstr}

\func{}{wxColourDatabase}{\void}

Constructs the colour database.

\membersection{wxColourDatabase::FindColour}\label{wxcolourdatabasefindcolour}

\func{wxColour*}{FindColour}{\param{const wxString\& }{colourName}}

Finds a colour given the name. Returns NULL if not found.

\membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}

\constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}

Finds a colour name given the colour. Returns NULL if not found.

\membersection{wxColourDatabase::Initialize}\label{wxcolourdatabaseinitialize}

\func{void}{Initialize}{\void}

Initializes the database with a number of stock colours.  Called by wxWindows
on start-up.
Commit	Line	Data
a660d684 KB	1	\section{\class{wxColour}}\label{wxcolour}
	2
	3	A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values,
	4	and is used to determine drawing colours. See the
	5	entry for \helpref{wxColourDatabase}{wxcolourdatabase} for how a pointer to a predefined,
	6	named colour may be returned instead of creating a new colour.
	7
	8	Valid RGB values are in the range 0 to 255.
	9
	10	\wxheading{Derived from}
	11
	12	\helpref{wxObject}{wxobject}
	13
954b8ae6 JS	14	\wxheading{Include files}
	15
	16	<wx/colour.h>
	17
20e85460 JS	18	\wxheading{Predefined objects}
	19
	20	Objects:
	21
	22	{\bf wxNullColour}
	23
	24	Pointers:
	25
	26	{\bf wxBLACK\\
	27	wxWHITE\\
	28	wxRED\\
	29	wxBLUE\\
	30	wxGREEN\\
	31	wxCYAN\\
	32	wxLIGHT\_GREY}
	33
a660d684 KB	34	\wxheading{See also}
	35
	36	\helpref{wxColourDatabase}{wxcolourdatabase}, \helpref{wxPen}{wxpen}, \helpref{wxBrush}{wxbrush},\rtfsp
	37	\helpref{wxColourDialog}{wxcolourdialog}
	38
	39	\latexignore{\rtfignore{\wxheading{Members}}}
	40
	41	\membersection{wxColour::wxColour}\label{wxcolourconstr}
	42
	43	\func{}{wxColour}{\void}
	44
	45	Default constructor.
	46
	47	\func{}{wxColour}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}}
	48
	49	Constructs a colour from red, green and blue values.
	50
	51	\func{}{wxColour}{\param{const wxString\& }{colourNname}}
	52
	53	Constructs a colour object using a colour name
	54	listed in {\bf wxTheColourDatabase}.
	55
1e6d9499 JS	56	\func{}{wxColour}{\param{const wxColour\&}{ colour}}
	57
	58	Copy constructor.
	59
a660d684 KB	60	\wxheading{Parameters}
	61
	62	\docparam{red}{The red value.}
	63
	64	\docparam{green}{The green value.}
	65
	66	\docparam{blue}{The blue value.}
	67
	68	\docparam{colourName}{The colour name.}
	69
1e6d9499 JS	70	\docparam{colour}{The colour to copy.}
1e6d9499 JS	71
a660d684 KB	72	\wxheading{See also}
	73
	74	\helpref{wxColourDatabase}{wxcolourdatabase}
	75
06d20283 RD	76	\pythonnote{Constructors supported by wxPython are:\par
	77	\indented{2cm}{\begin{twocollist}
	78	\twocolitem{\bf{wxColour(red=0, green=0, blue=0)}}{}
	79	\twocolitem{\bf{wxNamedColour(name)}}{}
	80	\end{twocollist}}
	81	}
	82
	83
a660d684 KB	84	\membersection{wxColour::Blue}\label{wxcolourblue}
	85
	86	\constfunc{unsigned char}{Blue}{\void}
	87
	88	Returns the blue intensity.
	89
	90	\membersection{wxColour::GetPixel}\label{wxcolourgetpixel}
	91
	92	\constfunc{long}{GetPixel}{\void}
	93
	94	Returns a pixel value which is platform-dependent. On Windows, a COLORREF is returned.
	95	On X, an allocated pixel value is returned.
	96
	97	-1 is returned if the pixel is invalid (on X, unallocated).
	98
	99	\membersection{wxColour::Green}\label{wxcolourgreen}
	100
	101	\constfunc{unsigned char}{Green}{\void}
	102
	103	Returns the green intensity.
	104
	105	\membersection{wxColour::Ok}\label{wxcolourok}
	106
	107	\constfunc{bool}{Ok}{\void}
	108
	109	Returns TRUE if the colour object is valid (the colour has been initialised with RGB values).
	110
	111	\membersection{wxColour::Red}\label{wxcolourred}
	112
	113	\constfunc{unsigned char}{Red}{\void}
	114
	115	Returns the red intensity.
	116
	117	\membersection{wxColour::Set}\label{wxcolourset}
	118
	119	\func{void}{Set}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}}
	120
	121	Sets the RGB intensity values.
	122
	123	\membersection{wxColour::operator $=$}\label{wxcolourassign}
	124
	125	\func{wxColour\&}{operator $=$}{\param{const wxColour\&}{ colour}}
	126
	127	Assignment operator, taking another colour object.
	128
	129	\func{wxColour\&}{operator $=$}{\param{const wxString\&}{ colourName}}
	130
	131	Assignment operator, using a colour name to be found in the colour database.
	132
	133	\wxheading{See also}
	134
	135	\helpref{wxColourDatabase}{wxcolourdatabase}
	136
	137	\membersection{wxColour::operator $==$}\label{wxcolourequality}
	138
	139	\func{bool}{operator $==$}{\param{const wxColour\&}{ colour}}
	140
	141	Tests the equality of two colours by comparing individual red, green blue colours.
	142
a660d684 KB	143	\membersection{wxColour::operator $!=$}\label{wxcolourinequality}
	144
	145	\func{bool}{operator $!=$}{\param{const wxColour\&}{ colour}}
	146
	147	Tests the inequality of two colours by comparing individual red, green blue colours.
	148
a660d684 KB	149	\section{\class{wxColourData}}\label{wxcolourdata}
	150
	151	This class holds a variety of information related to colour dialogs.
	152
	153	\wxheading{Derived from}
	154
	155	\helpref{wxObject}{wxobject}
	156
954b8ae6 JS	157	\wxheading{Include files}
	158
	159	<wx/cmndata.h>
	160
a660d684 KB	161	\wxheading{See also}
	162
	163	\helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview}
	164
	165	\latexignore{\rtfignore{\wxheading{Members}}}
	166
	167	\membersection{wxColourData::wxColourData}\label{wxcolourdataconstr}
	168
	169	\func{}{wxColourData}{\void}
	170
	171	Constructor. Initializes the custom colours to white, the {\it data colour} setting
	172	to black, and the {\it choose full} setting to TRUE.
	173
	174	\membersection{wxColourData::\destruct{wxColourData}}
	175
	176	\func{}{\destruct{wxColourData}}{\void}
	177
	178	Destructor.
	179
	180	\membersection{wxColourData::GetChooseFull}\label{wxcolourdatagetchoosefull}
	181
	182	\constfunc{bool}{GetChooseFull}{\void}
	183
	184	Under Windows, determines whether the Windows colour dialog will display the full dialog
	185	with custom colour selection controls. Has no meaning under other platforms.
	186
	187	The default value is TRUE.
	188
	189	\membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour}
	190
	191	\constfunc{wxColour\&}{GetColour}{\void}
	192
	193	Gets the current colour associated with the colour dialog.
	194
	195	The default colour is black.
	196
	197	\membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour}
	198
eaaa6a06	199	\constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}}
a660d684 KB	200
	201	Gets the {\it i}th custom colour associated with the colour dialog. {\it i} should
	202	be an integer between 0 and 15.
	203
	204	The default custom colours are all white.
	205
	206	\membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull}
	207
	208	\func{void}{SetChooseFull}{\param{const bool }{flag}}
	209
	210	Under Windows, tells the Windows colour dialog to display the full dialog
	211	with custom colour selection controls. Under other platforms, has no effect.
	212
	213	The default value is TRUE.
	214
	215	\membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour}
	216
	217	\func{void}{SetColour}{\param{const wxColour\&}{ colour}}
	218
	219	Sets the default colour for the colour dialog.
	220
	221	The default colour is black.
	222
	223	\membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour}
	224
eaaa6a06	225	\func{void}{SetColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}}
a660d684 KB	226
	227	Sets the {\it i}th custom colour for the colour dialog. {\it i} should
	228	be an integer between 0 and 15.
	229
	230	The default custom colours are all white.
	231
	232	\membersection{wxColourData::operator $=$}\label{wxcolourdataassign}
	233
	234	\func{void}{operator $=$}{\param{const wxColourData\&}{ data}}
	235
	236	Assingment operator for the colour data.
	237
	238	\section{\class{wxColourDatabase}}\label{wxcolourdatabase}
	239
	240	wxWindows maintains a database of standard RGB colours for a predefined
	241	set of named colours (such as ``BLACK'', ``LIGHT GREY''). The
	242	application may add to this set if desired by using {\it Append}. There
	243	is only one instance of this class: {\bf wxTheColourDatabase}.
	244
	245	\wxheading{Derived from}
	246
	247	\helpref{wxList}{wxlist}\\
	248	\helpref{wxObject}{wxobject}
	249
954b8ae6 JS	250	\wxheading{Include files}
	251
	252	<wx/gdicmn.h>
	253
a660d684 KB	254	\wxheading{Remarks}
	255
	256	The colours in the standard database are as follows:
	257
	258	AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL,
	259	CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK
	260	ORCHID, DARK SLATE BLUE, DARK SLATE GREY DARK TURQUOISE, DIM GREY,
	261	FIREBRICK, FOREST GREEN, GOLD, GOLDENROD, GREY, GREEN, GREEN YELLOW,
	262	INDIAN RED, KHAKI, LIGHT BLUE, LIGHT GREY, LIGHT STEEL BLUE, LIME GREEN,
	263	MAGENTA, MAROON, MEDIUM AQUAMARINE, MEDIUM BLUE, MEDIUM FOREST GREEN,
	264	MEDIUM GOLDENROD, MEDIUM ORCHID, MEDIUM SEA GREEN, MEDIUM SLATE BLUE,
	265	MEDIUM SPRING GREEN, MEDIUM TURQUOISE, MEDIUM VIOLET RED, MIDNIGHT BLUE,
	266	NAVY, ORANGE, ORANGE RED, ORCHID, PALE GREEN, PINK, PLUM, PURPLE, RED,
	267	SALMON, SEA GREEN, SIENNA, SKY BLUE, SLATE BLUE, SPRING GREEN, STEEL
	268	BLUE, TAN, THISTLE, TURQUOISE, VIOLET, VIOLET RED, WHEAT, WHITE, YELLOW,
	269	YELLOW GREEN.
	270
	271	\wxheading{See also}
	272
	273	\helpref{wxColour}{wxcolour}
	274
	275	\latexignore{\rtfignore{\wxheading{Members}}}
	276
	277	\membersection{wxColourDatabase::wxColourDatabase}\label{wxcolourdatabaseconstr}
	278
	279	\func{}{wxColourDatabase}{\void}
	280
	281	Constructs the colour database.
	282
	283	\membersection{wxColourDatabase::FindColour}\label{wxcolourdatabasefindcolour}
	284
	285	\func{wxColour*}{FindColour}{\param{const wxString\& }{colourName}}
	286
	287	Finds a colour given the name. Returns NULL if not found.
	288
	289	\membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname}
	290
	291	\constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}}
	292
	293	Finds a colour name given the colour. Returns NULL if not found.
	294
	295	\membersection{wxColourDatabase::Initialize}\label{wxcolourdatabaseinitialize}
	296
	297	\func{void}{Initialize}{\void}
	298
	299	Initializes the database with a number of stock colours. Called by wxWindows
	300	on start-up.
	301
	302