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

TODO: this may be different on platforms other than Windows - no reference counting
is done on Windows.

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

TODO: this may be different on platforms other than Windows - no reference counting
is done on Windows.

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

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

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

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