]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/brush.h
Fix a parameter type and add some missing const keywords
[wxWidgets.git] / interface / wx / brush.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: brush.h
3 // Purpose: interface of wxBrush
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 The possible brush styles.
11 */
12 enum wxBrushStyle
13 {
14 wxBRUSHSTYLE_INVALID = -1,
15
16 wxBRUSHSTYLE_SOLID = wxSOLID,
17 /**< Solid. */
18
19 wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT,
20 /**< Transparent (no fill). */
21
22 wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
23 /**< Uses a bitmap as a stipple; the mask is used for blitting monochrome
24 using text foreground and background colors. */
25
26 wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
27 /**< Uses a bitmap as a stipple; mask is used for masking areas in the
28 stipple bitmap. */
29
30 wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
31 /**< Uses a bitmap as a stipple. */
32
33 wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
34 /**< Backward diagonal hatch. */
35
36 wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
37 /**< Cross-diagonal hatch. */
38
39 wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
40 /**< Forward diagonal hatch. */
41
42 wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
43 /**< Cross hatch. */
44
45 wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
46 /**< Horizontal hatch. */
47
48 wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
49 /**< Vertical hatch. */
50
51 wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
52 wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
53 };
54
55
56
57 /**
58 @class wxBrush
59
60 A brush is a drawing tool for filling in areas. It is used for painting
61 the background of rectangles, ellipses, etc. It has a colour and a style.
62
63 On a monochrome display, wxWidgets shows all brushes as white unless the
64 colour is really black.
65
66 Do not initialize objects on the stack before the program commences, since
67 other required structures may not have been set up yet. Instead, define
68 global pointers to objects and create them in wxApp::OnInit or when required.
69
70 An application may wish to create brushes with different characteristics
71 dynamically, and there is the consequent danger that a large number of
72 duplicate brushes will be created. Therefore an application may wish to
73 get a pointer to a brush by using the global list of brushes ::wxTheBrushList,
74 and calling the member function wxBrushList::FindOrCreateBrush().
75
76 This class uses reference counting and copy-on-write internally so that
77 assignments between two instances of this class are very cheap.
78 You can therefore use actual objects instead of pointers without efficiency problems.
79 If an instance of this class is changed it will create its own data internally
80 so that other instances, which previously shared the data using the reference
81 counting, are not affected.
82
83 @library{wxcore}
84 @category{gdi}
85
86 @stdobjects
87 @li ::wxNullBrush
88 @li ::wxBLACK_BRUSH
89 @li ::wxBLUE_BRUSH
90 @li ::wxCYAN_BRUSH
91 @li ::wxGREEN_BRUSH
92 @li ::wxYELLOW_BRUSH
93 @li ::wxGREY_BRUSH
94 @li ::wxLIGHT_GREY_BRUSH
95 @li ::wxMEDIUM_GREY_BRUSH
96 @li ::wxRED_BRUSH
97 @li ::wxTRANSPARENT_BRUSH
98 @li ::wxWHITE_BRUSH
99
100 @see wxBrushList, wxDC, wxDC::SetBrush
101 */
102 class wxBrush : public wxGDIObject
103 {
104 public:
105 /**
106 Default constructor.
107 The brush will be uninitialised, and wxBrush:IsOk() will return @false.
108 */
109 wxBrush();
110
111 /**
112 Constructs a brush from a colour object and @a style.
113
114 @param colour
115 Colour object.
116 @param style
117 One of the ::wxBrushStyle enumeration values.
118 */
119 wxBrush(const wxColour& colour, wxBrushStyle style = wxBRUSHSTYLE_SOLID);
120
121 /**
122 Constructs a stippled brush using a bitmap.
123 The brush style will be set to @c wxBRUSHSTYLE_STIPPLE.
124 */
125 wxBrush(const wxBitmap& stippleBitmap);
126
127 /**
128 Copy constructor, uses @ref overview_refcount "reference counting".
129 */
130 wxBrush(const wxBrush& brush);
131
132 /**
133 Destructor.
134
135 See @ref overview_refcount_destruct for more info.
136
137 @remarks Although all remaining brushes are deleted when the application
138 exits, the application should try to clean up all brushes itself.
139 This is because wxWidgets cannot know if a pointer to the brush
140 object is stored in an application data structure, and there is
141 a risk of double deletion.
142 */
143 virtual ~wxBrush();
144
145 /**
146 Returns a reference to the brush colour.
147
148 @see SetColour()
149 */
150 virtual wxColour GetColour() const;
151
152 /**
153 Gets a pointer to the stipple bitmap. If the brush does not have a @c wxBRUSHSTYLE_STIPPLE
154 style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
155
156 @see SetStipple()
157 */
158 virtual wxBitmap* GetStipple() const;
159
160 /**
161 Returns the brush style, one of the ::wxBrushStyle values.
162
163 @see SetStyle(), SetColour(), SetStipple()
164 */
165 virtual wxBrushStyle GetStyle() const;
166
167 /**
168 Returns @true if the style of the brush is any of hatched fills.
169
170 @see GetStyle()
171 */
172 virtual bool IsHatch() const;
173
174 /**
175 Returns @true if the brush is initialised.
176
177 Notice that an uninitialized brush object can't be queried for any
178 brush properties and all calls to the accessor methods on it will
179 result in an assert failure.
180 */
181 virtual bool IsOk() const;
182
183 /**
184 Returns @true if the brush is a valid non-transparent brush.
185
186 This method returns @true if the brush object is initialized and has a
187 non-transparent style. Notice that this should be used instead of
188 simply testing whether GetStyle() returns a style different from
189 wxBRUSHSTYLE_TRANSPARENT if the brush may be invalid as GetStyle()
190 would assert in this case.
191
192 @see IsTransparent()
193
194 @since 2.9.2.
195 */
196 bool IsNonTransparent() const;
197
198 /**
199 Returns @true if the brush is transparent.
200
201 A transparent brush is simply a brush with wxBRUSHSTYLE_TRANSPARENT
202 style.
203
204 Notice that this function works even for non-initialized brushs (for
205 which it returns @false) unlike tests of the form <code>GetStyle() ==
206 wxBRUSHSTYLE_TRANSPARENT</code> which would assert if the brush is
207 invalid.
208
209 @see IsNonTransparent()
210
211 @since 2.9.2.
212 */
213 bool IsTransparent() const;
214
215
216 //@{
217 /**
218 Sets the brush colour using red, green and blue values.
219
220 @see GetColour()
221 */
222 virtual void SetColour(const wxColour& colour);
223 virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
224 //@}
225
226 /**
227 Sets the stipple bitmap.
228
229 @param bitmap
230 The bitmap to use for stippling.
231
232 @remarks The style will be set to @c wxBRUSHSTYLE_STIPPLE, unless the bitmap
233 has a mask associated to it, in which case the style will be set
234 to @c wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
235
236 @see wxBitmap
237 */
238 virtual void SetStipple(const wxBitmap& bitmap);
239
240 /**
241 Sets the brush style.
242
243 @param style
244 One of the ::wxBrushStyle values.
245
246 @see GetStyle()
247 */
248 virtual void SetStyle(wxBrushStyle style);
249
250 /**
251 Inequality operator.
252 See @ref overview_refcount_equality for more info.
253 */
254 bool operator !=(const wxBrush& brush) const;
255
256 /**
257 Equality operator.
258 See @ref overview_refcount_equality for more info.
259 */
260 bool operator ==(const wxBrush& brush) const;
261 };
262
263 /**
264 An empty brush.
265 wxBrush::IsOk() always returns @false for this object.
266 */
267 wxBrush wxNullBrush;
268
269 /**
270 Blue brush.
271 Except for the color it has all standard attributes
272 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
273 */
274 wxBrush* wxBLUE_BRUSH;
275
276 /**
277 Green brush.
278 Except for the color it has all standard attributes
279 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
280 */
281 wxBrush* wxGREEN_BRUSH;
282
283 /**
284 Yellow brush.
285 Except for the color it has all standard attributes
286 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
287 */
288 wxBrush* wxYELLOW_BRUSH;
289
290 /**
291 White brush.
292 Except for the color it has all standard attributes
293 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
294 */
295 wxBrush* wxWHITE_BRUSH;
296
297 /**
298 Black brush.
299 Except for the color it has all standard attributes
300 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
301 */
302 wxBrush* wxBLACK_BRUSH;
303
304 /**
305 Grey brush.
306 Except for the color it has all standard attributes
307 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
308 */
309 wxBrush* wxGREY_BRUSH;
310
311 /**
312 Medium grey brush.
313 Except for the color it has all standard attributes
314 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
315 */
316 wxBrush* wxMEDIUM_GREY_BRUSH;
317
318 /**
319 Light grey brush.
320 Except for the color it has all standard attributes
321 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
322 */
323 wxBrush* wxLIGHT_GREY_BRUSH;
324
325 /**
326 Transparent brush.
327 Except for the color it has all standard attributes
328 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
329 */
330 wxBrush* wxTRANSPARENT_BRUSH;
331
332 /**
333 Cyan brush.
334 Except for the color it has all standard attributes
335 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
336 */
337 wxBrush* wxCYAN_BRUSH;
338
339 /**
340 Red brush.
341 Except for the color it has all standard attributes
342 (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
343 */
344 wxBrush* wxRED_BRUSH;
345
346
347
348 /**
349 @class wxBrushList
350
351 A brush list is a list containing all brushes which have been created.
352
353 The application should not construct its own brush list: it should use the
354 object pointer ::wxTheBrushList.
355
356 @library{wxcore}
357 @category{gdi}
358
359 @see wxBrush
360 */
361 class wxBrushList : public wxList
362 {
363 public:
364 /**
365 Finds a brush with the specified attributes and returns it, else creates a new
366 brush, adds it to the brush list, and returns it.
367
368 @param colour
369 Colour object.
370 @param style
371 Brush style. See ::wxBrushStyle for a list of styles.
372 */
373 wxBrush* FindOrCreateBrush(const wxColour& colour,
374 wxBrushStyle style = wxBRUSHSTYLE_SOLID);
375 };
376
377 /**
378 The global wxBrushList instance.
379 */
380 wxBrushList* wxTheBrushList;