[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{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}

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