]>
Commit | Line | Data |
---|---|---|
edc536d3 WS |
1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
2 | %% Name: colour.tex | |
3 | %% Purpose: wxColour docs | |
4 | %% Author: | |
40989e46 | 5 | %% Modified by: Francesco Montorsi |
edc536d3 WS |
6 | %% Created: |
7 | %% RCS-ID: $Id$ | |
8 | %% Copyright: (c) wxWidgets | |
9 | %% License: wxWindows license | |
10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
11 | ||
a660d684 KB |
12 | \section{\class{wxColour}}\label{wxcolour} |
13 | ||
14 | A colour is an object representing a combination of Red, Green, and Blue (RGB) intensity values, | |
15 | and is used to determine drawing colours. See the | |
16 | entry for \helpref{wxColourDatabase}{wxcolourdatabase} for how a pointer to a predefined, | |
17 | named colour may be returned instead of creating a new colour. | |
18 | ||
19 | Valid RGB values are in the range 0 to 255. | |
20 | ||
8161ba08 JS |
21 | You can retrieve the current system colour settings with \helpref{wxSystemSettings}{wxsystemsettings}. |
22 | ||
a660d684 KB |
23 | \wxheading{Derived from} |
24 | ||
25 | \helpref{wxObject}{wxobject} | |
26 | ||
954b8ae6 JS |
27 | \wxheading{Include files} |
28 | ||
29 | <wx/colour.h> | |
30 | ||
20e85460 JS |
31 | \wxheading{Predefined objects} |
32 | ||
33 | Objects: | |
34 | ||
35 | {\bf wxNullColour} | |
36 | ||
37 | Pointers: | |
38 | ||
39 | {\bf wxBLACK\\ | |
40 | wxWHITE\\ | |
41 | wxRED\\ | |
42 | wxBLUE\\ | |
43 | wxGREEN\\ | |
44 | wxCYAN\\ | |
45 | wxLIGHT\_GREY} | |
46 | ||
a660d684 KB |
47 | \wxheading{See also} |
48 | ||
49 | \helpref{wxColourDatabase}{wxcolourdatabase}, \helpref{wxPen}{wxpen}, \helpref{wxBrush}{wxbrush},\rtfsp | |
8161ba08 | 50 | \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxSystemSettings}{wxsystemsettings} |
a660d684 KB |
51 | |
52 | \latexignore{\rtfignore{\wxheading{Members}}} | |
53 | ||
c50f92d0 | 54 | |
a660d684 KB |
55 | \membersection{wxColour::wxColour}\label{wxcolourconstr} |
56 | ||
57 | \func{}{wxColour}{\void} | |
58 | ||
59 | Default constructor. | |
60 | ||
36d55705 | 61 | \func{}{wxColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}, \param{unsigned char}{ alpha=wxALPHA\_OPAQUE}} |
a660d684 | 62 | |
36d55705 | 63 | Constructs a colour from red, green, blue and alpha values. |
a660d684 KB |
64 | |
65 | \func{}{wxColour}{\param{const wxString\& }{colourNname}} | |
66 | ||
7f9d7dea | 67 | Constructs a colour using the given string. See \helpref{Set}{wxcolourset} for more info. |
a660d684 | 68 | |
1e6d9499 JS |
69 | \func{}{wxColour}{\param{const wxColour\&}{ colour}} |
70 | ||
71 | Copy constructor. | |
72 | ||
a660d684 KB |
73 | \wxheading{Parameters} |
74 | ||
75 | \docparam{red}{The red value.} | |
76 | ||
77 | \docparam{green}{The green value.} | |
78 | ||
79 | \docparam{blue}{The blue value.} | |
80 | ||
36d55705 SC |
81 | \docparam{alpha}{The alpha value. Alpha values range from 0 (wxALPHA\_TRANSPARENT) to 255 (wxALPHA\_OPAQUE).} |
82 | ||
a660d684 KB |
83 | \docparam{colourName}{The colour name.} |
84 | ||
1e6d9499 JS |
85 | \docparam{colour}{The colour to copy.} |
86 | ||
a660d684 KB |
87 | \wxheading{See also} |
88 | ||
89 | \helpref{wxColourDatabase}{wxcolourdatabase} | |
90 | ||
06d20283 RD |
91 | \pythonnote{Constructors supported by wxPython are:\par |
92 | \indented{2cm}{\begin{twocollist} | |
c9110876 VS |
93 | \twocolitem{{\bf wxColour(red=0, green=0, blue=0)}}{} |
94 | \twocolitem{{\bf wxNamedColour(name)}}{} | |
06d20283 RD |
95 | \end{twocollist}} |
96 | } | |
97 | ||
98 | ||
c50f92d0 | 99 | |
36d55705 SC |
100 | \membersection{wxColour::Alpha}\label{wxcolouralpha} |
101 | ||
102 | \constfunc{unsigned char}{Alpha}{\void} | |
103 | ||
104 | Returns the alpha value, on platforms where alpha is not yet supported, this always returns wxALPHA\_OPAQUE. | |
105 | ||
106 | ||
a660d684 KB |
107 | \membersection{wxColour::Blue}\label{wxcolourblue} |
108 | ||
109 | \constfunc{unsigned char}{Blue}{\void} | |
110 | ||
111 | Returns the blue intensity. | |
112 | ||
c50f92d0 | 113 | |
40989e46 WS |
114 | \membersection{wxColour::GetAsString}\label{wxcolourgetasstring} |
115 | ||
116 | \constfunc{wxString}{GetAsString}{\param{long}{ flags}} | |
117 | ||
b534968d | 118 | Converts this colour to a \helpref{wxString}{wxstring} |
40989e46 WS |
119 | using the given {\it flags}. |
120 | ||
b534968d VZ |
121 | The supported flags are \textbf{wxC2S\_NAME}, to obtain the colour name (e.g. |
122 | wxColour(255,0,0) -> \texttt{``red"}), \textbf{wxC2S\_CSS\_SYNTAX}, to obtain | |
123 | the colour in the \texttt{``rgb(r,g,b)"} or \texttt{``rgba(r,g,b,a)"} syntax | |
124 | (e.g. wxColour(255,0,0,85) -> \texttt{``rgba(255,0,0,0.333)"}), and | |
125 | \textbf{wxC2S\_HTML\_SYNTAX}, to obtain the colour as \texttt{``\#"} followed | |
126 | by 6 hexadecimal digits (e.g. wxColour(255,0,0) -> \texttt{``\#FF0000"}). | |
40989e46 | 127 | |
b534968d VZ |
128 | This function never fails and always returns a non-empty string but asserts if |
129 | the colour has alpha channel (i.e. is non opaque) but | |
130 | \textbf{wxC2S\_CSS\_SYNTAX} (which is the only one supporting alpha) is not | |
131 | specified in flags. | |
40989e46 | 132 | |
78b5edc5 | 133 | \newsince{2.7.0} |
40989e46 | 134 | |
b534968d | 135 | |
a660d684 KB |
136 | \membersection{wxColour::GetPixel}\label{wxcolourgetpixel} |
137 | ||
138 | \constfunc{long}{GetPixel}{\void} | |
139 | ||
140 | Returns a pixel value which is platform-dependent. On Windows, a COLORREF is returned. | |
141 | On X, an allocated pixel value is returned. | |
142 | ||
143 | -1 is returned if the pixel is invalid (on X, unallocated). | |
144 | ||
c50f92d0 | 145 | |
a660d684 KB |
146 | \membersection{wxColour::Green}\label{wxcolourgreen} |
147 | ||
148 | \constfunc{unsigned char}{Green}{\void} | |
149 | ||
150 | Returns the green intensity. | |
151 | ||
c50f92d0 | 152 | |
b7cacb43 | 153 | \membersection{wxColour::IsOk}\label{wxcolourisok} |
a660d684 | 154 | |
b7cacb43 | 155 | \constfunc{bool}{IsOk}{\void} |
a660d684 | 156 | |
c50f92d0 VZ |
157 | Returns \true if the colour object is valid (the colour has been initialised with RGB values). |
158 | ||
a660d684 KB |
159 | |
160 | \membersection{wxColour::Red}\label{wxcolourred} | |
161 | ||
162 | \constfunc{unsigned char}{Red}{\void} | |
163 | ||
164 | Returns the red intensity. | |
165 | ||
c50f92d0 | 166 | |
a660d684 KB |
167 | \membersection{wxColour::Set}\label{wxcolourset} |
168 | ||
36d55705 | 169 | \func{void}{Set}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}, \param{unsigned char}{ alpha=wxALPHA\_OPAQUE}} |
a660d684 | 170 | |
40989e46 WS |
171 | \func{void}{Set}{\param{unsigned long}{ RGB}} |
172 | ||
40989e46 WS |
173 | \func{bool}{Set}{\param{const wxString \&}{ str}} |
174 | ||
aaa6f9ba RD |
175 | Sets the RGB intensity values using the given values (first overload), extracting them from the packed long (second overload), using the given string (third overloard). |
176 | ||
b534968d VZ |
177 | When using third form, Set() accepts: colour names (those listed in |
178 | \helpref{wxTheColourDatabase}{wxcolourdatabase}), the CSS-like | |
179 | \texttt{``rgb(r,g,b)"} or \texttt{``rgba(r,g,b,a)"} syntax (case insensitive) | |
180 | and the HTML-like syntax (i.e. \texttt{``\#"} followed by 6 hexadecimal digits | |
181 | for red, green, blue components). | |
40989e46 WS |
182 | |
183 | Returns \true if the conversion was successful, \false otherwise. | |
184 | ||
78b5edc5 MR |
185 | \newsince{2.7.0} |
186 | ||
40989e46 | 187 | |
a660d684 KB |
188 | \membersection{wxColour::operator $=$}\label{wxcolourassign} |
189 | ||
190 | \func{wxColour\&}{operator $=$}{\param{const wxColour\&}{ colour}} | |
191 | ||
192 | Assignment operator, taking another colour object. | |
193 | ||
194 | \func{wxColour\&}{operator $=$}{\param{const wxString\&}{ colourName}} | |
195 | ||
196 | Assignment operator, using a colour name to be found in the colour database. | |
197 | ||
198 | \wxheading{See also} | |
199 | ||
200 | \helpref{wxColourDatabase}{wxcolourdatabase} | |
201 | ||
c50f92d0 | 202 | |
a660d684 KB |
203 | \membersection{wxColour::operator $==$}\label{wxcolourequality} |
204 | ||
205 | \func{bool}{operator $==$}{\param{const wxColour\&}{ colour}} | |
206 | ||
36d55705 | 207 | Tests the equality of two colours by comparing individual red, green, blue colours and alpha values. |
a660d684 | 208 | |
c50f92d0 | 209 | |
a660d684 KB |
210 | \membersection{wxColour::operator $!=$}\label{wxcolourinequality} |
211 | ||
212 | \func{bool}{operator $!=$}{\param{const wxColour\&}{ colour}} | |
213 | ||
36d55705 | 214 | Tests the inequality of two colours by comparing individual red, green, blue colours and alpha values. |
a660d684 | 215 | |
a660d684 KB |
216 | \section{\class{wxColourData}}\label{wxcolourdata} |
217 | ||
218 | This class holds a variety of information related to colour dialogs. | |
219 | ||
220 | \wxheading{Derived from} | |
221 | ||
222 | \helpref{wxObject}{wxobject} | |
223 | ||
954b8ae6 JS |
224 | \wxheading{Include files} |
225 | ||
226 | <wx/cmndata.h> | |
227 | ||
a660d684 KB |
228 | \wxheading{See also} |
229 | ||
230 | \helpref{wxColour}{wxcolour}, \helpref{wxColourDialog}{wxcolourdialog}, \helpref{wxColourDialog overview}{wxcolourdialogoverview} | |
231 | ||
232 | \latexignore{\rtfignore{\wxheading{Members}}} | |
233 | ||
c50f92d0 | 234 | |
f510b7b2 | 235 | \membersection{wxColourData::wxColourData}\label{wxcolourdatactor} |
a660d684 KB |
236 | |
237 | \func{}{wxColourData}{\void} | |
238 | ||
393c836c VS |
239 | Constructor. Initializes the custom colours to {\tt wxNullColour}, |
240 | the {\it data colour} setting | |
cc81d32f | 241 | to black, and the {\it choose full} setting to true. |
a660d684 | 242 | |
c50f92d0 | 243 | |
f510b7b2 | 244 | \membersection{wxColourData::\destruct{wxColourData}}\label{wxcolourdatadtor} |
a660d684 KB |
245 | |
246 | \func{}{\destruct{wxColourData}}{\void} | |
247 | ||
248 | Destructor. | |
249 | ||
c50f92d0 | 250 | |
a660d684 KB |
251 | \membersection{wxColourData::GetChooseFull}\label{wxcolourdatagetchoosefull} |
252 | ||
253 | \constfunc{bool}{GetChooseFull}{\void} | |
254 | ||
255 | Under Windows, determines whether the Windows colour dialog will display the full dialog | |
f5d9cc73 WS |
256 | with custom colour selection controls. Under PalmOS, determines whether colour dialog |
257 | will display full rgb colour picker or only available palette indexer. | |
258 | Has no meaning under other platforms. | |
a660d684 | 259 | |
cc81d32f | 260 | The default value is true. |
a660d684 | 261 | |
c50f92d0 | 262 | |
a660d684 KB |
263 | \membersection{wxColourData::GetColour}\label{wxcolourdatagetcolour} |
264 | ||
265 | \constfunc{wxColour\&}{GetColour}{\void} | |
266 | ||
267 | Gets the current colour associated with the colour dialog. | |
268 | ||
269 | The default colour is black. | |
270 | ||
c50f92d0 | 271 | |
a660d684 KB |
272 | \membersection{wxColourData::GetCustomColour}\label{wxcolourdatagetcustomcolour} |
273 | ||
eaaa6a06 | 274 | \constfunc{wxColour\&}{GetCustomColour}{\param{int}{ i}} |
a660d684 KB |
275 | |
276 | Gets the {\it i}th custom colour associated with the colour dialog. {\it i} should | |
277 | be an integer between 0 and 15. | |
278 | ||
393c836c | 279 | The default custom colours are invalid colours. |
a660d684 | 280 | |
c50f92d0 | 281 | |
a660d684 KB |
282 | \membersection{wxColourData::SetChooseFull}\label{wxcolourdatasetchoosefull} |
283 | ||
284 | \func{void}{SetChooseFull}{\param{const bool }{flag}} | |
285 | ||
286 | Under Windows, tells the Windows colour dialog to display the full dialog | |
287 | with custom colour selection controls. Under other platforms, has no effect. | |
288 | ||
cc81d32f | 289 | The default value is true. |
a660d684 | 290 | |
c50f92d0 | 291 | |
a660d684 KB |
292 | \membersection{wxColourData::SetColour}\label{wxcolourdatasetcolour} |
293 | ||
294 | \func{void}{SetColour}{\param{const wxColour\&}{ colour}} | |
295 | ||
296 | Sets the default colour for the colour dialog. | |
297 | ||
298 | The default colour is black. | |
299 | ||
c50f92d0 | 300 | |
a660d684 KB |
301 | \membersection{wxColourData::SetCustomColour}\label{wxcolourdatasetcustomcolour} |
302 | ||
f6bcfd97 | 303 | \func{void}{SetCustomColour}{\param{int}{ i}, \param{const wxColour\&}{ colour}} |
a660d684 KB |
304 | |
305 | Sets the {\it i}th custom colour for the colour dialog. {\it i} should | |
306 | be an integer between 0 and 15. | |
307 | ||
393c836c | 308 | The default custom colours are invalid colours. |
a660d684 | 309 | |
c50f92d0 | 310 | |
a660d684 KB |
311 | \membersection{wxColourData::operator $=$}\label{wxcolourdataassign} |
312 | ||
313 | \func{void}{operator $=$}{\param{const wxColourData\&}{ data}} | |
314 | ||
2edb0bde | 315 | Assignment operator for the colour data. |
a660d684 | 316 | |
c50f92d0 VZ |
317 | |
318 | ||
319 | ||
a660d684 KB |
320 | \section{\class{wxColourDatabase}}\label{wxcolourdatabase} |
321 | ||
fc2171bd | 322 | wxWidgets maintains a database of standard RGB colours for a predefined |
a660d684 | 323 | set of named colours (such as ``BLACK'', ``LIGHT GREY''). The |
edc536d3 | 324 | application may add to this set if desired by using |
c50f92d0 VZ |
325 | \helpref{AddColour}{wxcolourdatabaseaddcolour} and may use it to look up |
326 | colours by names using \helpref{Find}{wxcolourdatabasefind} or find the names | |
327 | for the standard colour suing \helpref{FindName}{wxcolourdatabasefindname}. | |
328 | ||
edc536d3 | 329 | There is one predefined instance of this class called |
c50f92d0 | 330 | {\bf wxTheColourDatabase}. |
a660d684 KB |
331 | |
332 | \wxheading{Derived from} | |
333 | ||
8f520a56 | 334 | None |
a660d684 | 335 | |
954b8ae6 JS |
336 | \wxheading{Include files} |
337 | ||
338 | <wx/gdicmn.h> | |
339 | ||
a660d684 KB |
340 | \wxheading{Remarks} |
341 | ||
c50f92d0 | 342 | The standard database contains at least the following colours: |
a660d684 KB |
343 | |
344 | AQUAMARINE, BLACK, BLUE, BLUE VIOLET, BROWN, CADET BLUE, CORAL, | |
345 | CORNFLOWER BLUE, CYAN, DARK GREY, DARK GREEN, DARK OLIVE GREEN, DARK | |
346 | ORCHID, DARK SLATE BLUE, DARK SLATE GREY DARK TURQUOISE, DIM GREY, | |
347 | FIREBRICK, FOREST GREEN, GOLD, GOLDENROD, GREY, GREEN, GREEN YELLOW, | |
348 | INDIAN RED, KHAKI, LIGHT BLUE, LIGHT GREY, LIGHT STEEL BLUE, LIME GREEN, | |
349 | MAGENTA, MAROON, MEDIUM AQUAMARINE, MEDIUM BLUE, MEDIUM FOREST GREEN, | |
350 | MEDIUM GOLDENROD, MEDIUM ORCHID, MEDIUM SEA GREEN, MEDIUM SLATE BLUE, | |
351 | MEDIUM SPRING GREEN, MEDIUM TURQUOISE, MEDIUM VIOLET RED, MIDNIGHT BLUE, | |
352 | NAVY, ORANGE, ORANGE RED, ORCHID, PALE GREEN, PINK, PLUM, PURPLE, RED, | |
353 | SALMON, SEA GREEN, SIENNA, SKY BLUE, SLATE BLUE, SPRING GREEN, STEEL | |
354 | BLUE, TAN, THISTLE, TURQUOISE, VIOLET, VIOLET RED, WHEAT, WHITE, YELLOW, | |
355 | YELLOW GREEN. | |
356 | ||
357 | \wxheading{See also} | |
358 | ||
359 | \helpref{wxColour}{wxcolour} | |
360 | ||
361 | \latexignore{\rtfignore{\wxheading{Members}}} | |
362 | ||
c50f92d0 | 363 | |
a660d684 KB |
364 | \membersection{wxColourDatabase::wxColourDatabase}\label{wxcolourdatabaseconstr} |
365 | ||
366 | \func{}{wxColourDatabase}{\void} | |
367 | ||
c50f92d0 VZ |
368 | Constructs the colour database. It will be initialized at the first use. |
369 | ||
a660d684 | 370 | |
8f520a56 MB |
371 | \membersection{wxColourDatabase::AddColour}\label{wxcolourdatabaseaddcolour} |
372 | ||
c50f92d0 VZ |
373 | \func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{const wxColour\&}{colour}} |
374 | ||
8f520a56 MB |
375 | \func{void}{AddColour}{\param{const wxString\& }{colourName}, \param{wxColour* }{colour}} |
376 | ||
377 | Adds a colour to the database. If a colour with the same name already exists, | |
378 | it is replaced. | |
379 | ||
c50f92d0 | 380 | Please note that the overload taking a pointer is deprecated and will be |
fc2171bd | 381 | removed in the next wxWidgets version, please don't use it. |
c50f92d0 VZ |
382 | |
383 | ||
384 | \membersection{wxColourDatabase::Find}\label{wxcolourdatabasefind} | |
385 | ||
f6e9a818 | 386 | \func{wxColour}{Find}{\param{const wxString\& }{colourName}} |
c50f92d0 VZ |
387 | |
388 | Finds a colour given the name. Returns an invalid colour object (that is, such | |
b7cacb43 | 389 | that its \helpref{Ok()}{wxcolourisok} method returns \false) if the colour wasn't |
c50f92d0 VZ |
390 | found in the database. |
391 | ||
392 | ||
c50f92d0 | 393 | \membersection{wxColourDatabase::FindName}\label{wxcolourdatabasefindname} |
a660d684 | 394 | |
c50f92d0 | 395 | \constfunc{wxString}{FindName}{\param{const wxColour\&}{ colour}} |
a660d684 | 396 | |
c50f92d0 VZ |
397 | Finds a colour name given the colour. Returns an empty string if the colour is |
398 | not found in the database. | |
b67a86d5 | 399 |