Added the function and macro group pages for Doxygen.
[wxWidgets.git] / interface / colour.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: colour.h
e54c96f1 3// Purpose: interface of wxColour
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxColour
3db7c3b1 11 @ingroup group_class_gdi
23324ae1 12 @wxheader{colour.h}
7c913512 13
23324ae1
FM
14 A colour is an object representing a combination of Red, Green, and Blue (RGB)
15 intensity values,
16 and is used to determine drawing colours. See the
17 entry for wxColourDatabase for how a pointer to a predefined,
18 named colour may be returned instead of creating a new colour.
7c913512 19
23324ae1 20 Valid RGB values are in the range 0 to 255.
7c913512 21
23324ae1 22 You can retrieve the current system colour settings with wxSystemSettings.
7c913512 23
23324ae1
FM
24 @library{wxcore}
25 @category{gdi}
7c913512 26
23324ae1 27 @stdobjects
e54c96f1
FM
28 ::Objects:, ::wxNullColour, ::Pointers:, ::wxBLACK, ::wxWHITE, ::wxRED,
29 ::wxBLUE, ::wxGREEN, ::wxCYAN, ::wxLIGHT_GREY,
7c913512 30
e54c96f1 31 @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
23324ae1
FM
32*/
33class wxColour : public wxObject
34{
35public:
36 //@{
37 /**
38 Copy constructor.
39
7c913512 40 @param red
4cc4bfaf 41 The red value.
7c913512 42 @param green
4cc4bfaf 43 The green value.
7c913512 44 @param blue
4cc4bfaf 45 The blue value.
7c913512 46 @param alpha
4cc4bfaf 47 The alpha value. Alpha values range from 0 (wxALPHA_TRANSPARENT) to 255
23324ae1 48 (wxALPHA_OPAQUE).
7c913512 49 @param colourName
4cc4bfaf 50 The colour name.
7c913512 51 @param colour
4cc4bfaf 52 The colour to copy.
23324ae1 53
4cc4bfaf 54 @see wxColourDatabase
23324ae1
FM
55 */
56 wxColour();
7c913512
FM
57 wxColour(unsigned char red, unsigned char green,
58 unsigned char blue,
4cc4bfaf 59 unsigned char alpha = wxALPHA_OPAQUE);
7c913512
FM
60 wxColour(const wxString& colourNname);
61 wxColour(const wxColour& colour);
23324ae1
FM
62 //@}
63
64 /**
65 Returns the alpha value, on platforms where alpha is not yet supported, this
66 always returns wxALPHA_OPAQUE.
67 */
328f5751 68 unsigned char Alpha() const;
23324ae1
FM
69
70 /**
71 Returns the blue intensity.
72 */
328f5751 73 unsigned char Blue() const;
23324ae1
FM
74
75 //@{
76 /**
77 is not
78 specified in flags.
e54c96f1
FM
79
80 @wxsince{2.7.0}
23324ae1
FM
81 */
82 wxString GetAsString(long flags);
328f5751
FM
83 const wxC2S_NAME, to obtain the colour name (e.g.
84 wxColour(255,0,0) - "red"), wxC2S_CSS_SYNTAX, to obtain
7c913512
FM
85 the colour in the "rgb(r,g,b)" or "rgba(r,g,b,a)" syntax
86 (e.g. wxColour(255,0,0,85) - "rgba(255,0,0,0.333)"), and
87 wxC2S_HTML_SYNTAX, to obtain the colour as "#" followed
88 by 6 hexadecimal digits (e.g. wxColour(255,0,0) - "#FF0000").
89 This function never fails and always returns a non-empty string but asserts if
90 the colour has alpha channel (i.e. is non opaque) but
91 wxC2S_CSS_SYNTAX();
23324ae1
FM
92 //@}
93
94 /**
95 Returns a pixel value which is platform-dependent. On Windows, a COLORREF is
96 returned.
97 On X, an allocated pixel value is returned.
23324ae1
FM
98 -1 is returned if the pixel is invalid (on X, unallocated).
99 */
328f5751 100 long GetPixel() const;
23324ae1
FM
101
102 /**
103 Returns the green intensity.
104 */
328f5751 105 unsigned char Green() const;
23324ae1
FM
106
107 /**
108 Returns @true if the colour object is valid (the colour has been initialised
109 with RGB values).
110 */
328f5751 111 bool IsOk() const;
23324ae1
FM
112
113 /**
114 Returns the red intensity.
115 */
328f5751 116 unsigned char Red() const;
23324ae1
FM
117
118 //@{
119 /**
120 Sets the RGB intensity values using the given values (first overload),
121 extracting them from the packed long (second overload), using the given string (third overloard).
7c913512 122 When using third form, Set() accepts: colour names (those listed in
e54c96f1 123 wxTheColourDatabase()), the CSS-like
7c913512
FM
124 @c "rgb(r,g,b)" or @c "rgba(r,g,b,a)" syntax (case insensitive)
125 and the HTML-like syntax (i.e. @c "#" followed by 6 hexadecimal digits
23324ae1 126 for red, green, blue components).
23324ae1 127 Returns @true if the conversion was successful, @false otherwise.
e54c96f1
FM
128
129 @wxsince{2.7.0}
23324ae1
FM
130 */
131 void Set(unsigned char red, unsigned char green,
132 unsigned char blue,
4cc4bfaf 133 unsigned char alpha = wxALPHA_OPAQUE);
7c913512 134 void Set(unsigned long RGB);
4cc4bfaf 135 bool Set(const wxString& str);
23324ae1
FM
136 //@}
137
138 /**
139 Tests the inequality of two colours by comparing individual red, green, blue
140 colours and alpha values.
141 */
142 bool operator !=(const wxColour& colour);
143
144 //@{
145 /**
146 Assignment operator, using a colour name to be found in the colour database.
147
4cc4bfaf 148 @see wxColourDatabase
23324ae1
FM
149 */
150 wxColour operator =(const wxColour& colour);
7c913512 151 wxColour operator =(const wxString& colourName);
23324ae1
FM
152 //@}
153
154 /**
155 Tests the equality of two colours by comparing individual red, green, blue
156 colours and alpha values.
157 */
158 bool operator ==(const wxColour& colour);
159};
e54c96f1
FM
160
161
162/**
163 FIXME
164*/
165wxColour Objects:
166;
167
168/**
169 FIXME
170*/
171wxColour wxNullColour;
172
173/**
174 FIXME
175*/
176wxColour Pointers:
177;
178
179/**
180 FIXME
181*/
182wxColour wxBLACK;
183
184/**
185 FIXME
186*/
187wxColour wxWHITE;
188
189/**
190 FIXME
191*/
192wxColour wxRED;
193
194/**
195 FIXME
196*/
197wxColour wxBLUE;
198
199/**
200 FIXME
201*/
202wxColour wxGREEN;
203
204/**
205 FIXME
206*/
207wxColour wxCYAN;
208
209/**
210 FIXME
211*/
212wxColour wxLIGHT_GREY;
213
214