]>
Commit | Line | Data |
---|---|---|
1a1498c0 WS |
1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
2 | %% Name: brush.tex | |
3 | %% Purpose: wxPen docs | |
4 | %% Author: | |
5 | %% Modified by: | |
6 | %% Created: | |
7 | %% RCS-ID: $Id$ | |
8 | %% Copyright: (c) wxWidgets | |
9 | %% License: wxWindows license | |
10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | |
11 | ||
a660d684 KB |
12 | \section{\class{wxBrush}}\label{wxbrush} |
13 | ||
14 | A brush is a drawing tool for filling in areas. It is used for painting | |
15 | the background of rectangles, ellipses, etc. It has a colour and a | |
16 | style. | |
17 | ||
18 | \wxheading{Derived from} | |
19 | ||
20 | \helpref{wxGDIObject}{wxgdiobject}\\ | |
21 | \helpref{wxObject}{wxobject} | |
22 | ||
954b8ae6 JS |
23 | \wxheading{Include files} |
24 | ||
25 | <wx/brush.h> | |
26 | ||
a7af285d VZ |
27 | \wxheading{Library} |
28 | ||
29 | \helpref{wxCore}{librarieslist} | |
30 | ||
20e85460 JS |
31 | \wxheading{Predefined objects} |
32 | ||
33 | Objects: | |
34 | ||
35 | {\bf wxNullBrush} | |
36 | ||
37 | Pointers: | |
38 | ||
39 | {\bf wxBLUE\_BRUSH\\ | |
40 | wxGREEN\_BRUSH\\ | |
41 | wxWHITE\_BRUSH\\ | |
42 | wxBLACK\_BRUSH\\ | |
43 | wxGREY\_BRUSH\\ | |
44 | wxMEDIUM\_GREY\_BRUSH\\ | |
45 | wxLIGHT\_GREY\_BRUSH\\ | |
46 | wxTRANSPARENT\_BRUSH\\ | |
47 | wxCYAN\_BRUSH\\ | |
48 | wxRED\_BRUSH} | |
49 | ||
a660d684 KB |
50 | \wxheading{Remarks} |
51 | ||
fc2171bd | 52 | On a monochrome display, wxWidgets shows |
a660d684 KB |
53 | all brushes as white unless the colour is really black. |
54 | ||
55 | Do not initialize objects on the stack before the program commences, | |
56 | since other required structures may not have been set up yet. Instead, | |
57 | define global pointers to objects and create them in \helpref{wxApp::OnInit}{wxapponinit} or | |
58 | when required. | |
59 | ||
60 | An application may wish to create brushes with different | |
61 | characteristics dynamically, and there is the consequent danger that a | |
62 | large number of duplicate brushes will be created. Therefore an | |
63 | application may wish to get a pointer to a brush by using the global | |
64 | list of brushes {\bf wxTheBrushList}, and calling the member function | |
65 | \rtfsp{\bf FindOrCreateBrush}. | |
66 | ||
a95bfca7 RR |
67 | This class uses \helpref{reference counting and copy-on-write}{trefcount} |
68 | internally so that assignments between two instances of this class are very | |
69 | cheap. You can therefore use actual objects instead of pointers without | |
70 | efficiency problems. If an instance of this class is changed it will create | |
71 | its own data internally so that other instances, which previously shared the | |
12a44087 | 72 | data using the reference counting, are not affected. |
a660d684 | 73 | |
5b6aa0ff | 74 | %TODO: an overview for wxBrush. |
a660d684 KB |
75 | \wxheading{See also} |
76 | ||
77 | \helpref{wxBrushList}{wxbrushlist}, \helpref{wxDC}{wxdc}, \helpref{wxDC::SetBrush}{wxdcsetbrush} | |
78 | ||
79 | \latexignore{\rtfignore{\wxheading{Members}}} | |
80 | ||
cf000528 | 81 | |
f510b7b2 | 82 | \membersection{wxBrush::wxBrush}\label{wxbrushctor} |
a660d684 KB |
83 | |
84 | \func{}{wxBrush}{\void} | |
85 | ||
b7cacb43 | 86 | Default constructor. The brush will be uninitialised, and \helpref{wxBrush:IsOk}{wxbrushisok} will |
cc81d32f | 87 | return false. |
a660d684 | 88 | |
559b61bf | 89 | \func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style = {\tt wxSOLID}}} |
a660d684 KB |
90 | |
91 | Constructs a brush from a colour object and style. | |
92 | ||
eaaa6a06 | 93 | \func{}{wxBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}} |
a660d684 KB |
94 | |
95 | Constructs a brush from a colour name and style. | |
96 | ||
97 | \func{}{wxBrush}{\param{const wxBitmap\& }{stippleBitmap}} | |
98 | ||
99 | Constructs a stippled brush using a bitmap. | |
100 | ||
101 | \func{}{wxBrush}{\param{const wxBrush\&}{ brush}} | |
102 | ||
a91225b2 | 103 | Copy constructor, uses \helpref{reference counting}{trefcount}. |
a660d684 | 104 | |
a660d684 KB |
105 | \wxheading{Parameters} |
106 | ||
107 | \docparam{colour}{Colour object.} | |
108 | ||
109 | \docparam{colourName}{Colour name. The name will be looked up in the colour database.} | |
110 | ||
111 | \docparam{style}{One of: | |
112 | ||
113 | \begin{twocollist}\itemsep=0pt | |
114 | \twocolitem{{\bf wxTRANSPARENT}}{Transparent (no fill).} | |
115 | \twocolitem{{\bf wxSOLID}}{Solid.} | |
03ca23b6 | 116 | \twocolitem{{\bf wxSTIPPLE}}{Uses a bitmap as a stipple.} |
a660d684 KB |
117 | \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.} |
118 | \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.} | |
119 | \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.} | |
120 | \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.} | |
121 | \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.} | |
122 | \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.} | |
123 | \end{twocollist}} | |
124 | ||
125 | \docparam{brush}{Pointer or reference to a brush to copy.} | |
126 | ||
127 | \docparam{stippleBitmap}{A bitmap to use for stippling.} | |
128 | ||
129 | \wxheading{Remarks} | |
130 | ||
131 | If a stipple brush is created, the brush style will be set to wxSTIPPLE. | |
132 | ||
133 | \wxheading{See also} | |
134 | ||
135 | \helpref{wxBrushList}{wxbrushlist}, \helpref{wxColour}{wxcolour}, \helpref{wxColourDatabase}{wxcolourdatabase} | |
136 | ||
cf000528 | 137 | |
f510b7b2 | 138 | \membersection{wxBrush::\destruct{wxBrush}}\label{wxbrushdtor} |
a660d684 | 139 | |
0e10e38d | 140 | \func{}{\destruct{wxBrush}}{\void} |
a660d684 KB |
141 | |
142 | Destructor. | |
55ccdb93 | 143 | See \helpref{reference-counted object destruction}{refcountdestruct} for more info. |
a660d684 KB |
144 | |
145 | \wxheading{Remarks} | |
146 | ||
a660d684 KB |
147 | Although all remaining brushes are deleted when the application exits, |
148 | the application should try to clean up all brushes itself. This is because | |
fc2171bd | 149 | wxWidgets cannot know if a pointer to the brush object is stored in an |
a660d684 KB |
150 | application data structure, and there is a risk of double deletion. |
151 | ||
cf000528 | 152 | |
a660d684 KB |
153 | \membersection{wxBrush::GetColour}\label{wxbrushgetcolour} |
154 | ||
155 | \constfunc{wxColour\&}{GetColour}{\void} | |
156 | ||
157 | Returns a reference to the brush colour. | |
158 | ||
159 | \wxheading{See also} | |
160 | ||
161 | \helpref{wxBrush::SetColour}{wxbrushsetcolour} | |
162 | ||
cf000528 | 163 | |
a660d684 KB |
164 | \membersection{wxBrush::GetStipple}\label{wxbrushgetstipple} |
165 | ||
166 | \constfunc{wxBitmap *}{GetStipple}{\void} | |
167 | ||
168 | Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE style, | |
b7cacb43 | 169 | this bitmap may be non-NULL but uninitialised (\helpref{wxBitmap:IsOk}{wxbitmapisok} returns false). |
a660d684 KB |
170 | |
171 | \wxheading{See also} | |
172 | ||
173 | \helpref{wxBrush::SetStipple}{wxbrushsetstipple} | |
174 | ||
cf000528 | 175 | |
a660d684 KB |
176 | \membersection{wxBrush::GetStyle}\label{wxbrushgetstyle} |
177 | ||
178 | \constfunc{int}{GetStyle}{\void} | |
179 | ||
180 | Returns the brush style, one of: | |
181 | ||
182 | \begin{twocollist}\itemsep=0pt | |
183 | \twocolitem{{\bf wxTRANSPARENT}}{Transparent (no fill).} | |
184 | \twocolitem{{\bf wxSOLID}}{Solid.} | |
185 | \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.} | |
186 | \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.} | |
187 | \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.} | |
188 | \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.} | |
189 | \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.} | |
190 | \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.} | |
191 | \twocolitem{{\bf wxSTIPPLE}}{Stippled using a bitmap.} | |
e7240349 | 192 | \twocolitem{{\bf wxSTIPPLE\_MASK\_OPAQUE}}{Stippled using a bitmap's mask.} |
a660d684 KB |
193 | \end{twocollist} |
194 | ||
195 | \wxheading{See also} | |
196 | ||
197 | \helpref{wxBrush::SetStyle}{wxbrushsetstyle}, \helpref{wxBrush::SetColour}{wxbrushsetcolour},\rtfsp | |
198 | \helpref{wxBrush::SetStipple}{wxbrushsetstipple} | |
199 | ||
cf000528 | 200 | |
ab9d0a8c WS |
201 | \membersection{wxBrush::IsHatch}\label{wxbrushishatch} |
202 | ||
203 | \constfunc{bool}{IsHatch}{\void} | |
204 | ||
205 | Returns true if the style of the brush is any of hatched fills. | |
206 | ||
207 | \wxheading{See also} | |
208 | ||
209 | \helpref{wxBrush::GetStyle}{wxbrushgetstyle} | |
210 | ||
cf000528 | 211 | |
b7cacb43 | 212 | \membersection{wxBrush::IsOk}\label{wxbrushisok} |
a660d684 | 213 | |
b7cacb43 | 214 | \constfunc{bool}{IsOk}{\void} |
a660d684 | 215 | |
cc81d32f | 216 | Returns true if the brush is initialised. It will return false if the default |
a660d684 KB |
217 | constructor has been used (for example, the brush is a member of a class, or |
218 | NULL has been assigned to it). | |
219 | ||
cf000528 | 220 | |
a660d684 KB |
221 | \membersection{wxBrush::SetColour}\label{wxbrushsetcolour} |
222 | ||
223 | \func{void}{SetColour}{\param{wxColour\& }{colour}} | |
224 | ||
225 | Sets the brush colour using a reference to a colour object. | |
226 | ||
227 | \func{void}{SetColour}{\param{const wxString\& }{colourName}} | |
228 | ||
229 | Sets the brush colour using a colour name from the colour database. | |
230 | ||
1a1498c0 | 231 | \func{void}{SetColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}} |
a660d684 KB |
232 | |
233 | Sets the brush colour using red, green and blue values. | |
234 | ||
235 | \wxheading{See also} | |
236 | ||
237 | \helpref{wxBrush::GetColour}{wxbrushgetcolour} | |
238 | ||
cf000528 | 239 | |
a660d684 KB |
240 | \membersection{wxBrush::SetStipple}\label{wxbrushsetstipple} |
241 | ||
242 | \func{void}{SetStipple}{\param{const wxBitmap\&}{ bitmap}} | |
243 | ||
244 | Sets the stipple bitmap. | |
245 | ||
246 | \wxheading{Parameters} | |
247 | ||
248 | \docparam{bitmap}{The bitmap to use for stippling.} | |
249 | ||
250 | \wxheading{Remarks} | |
251 | ||
6e7b6cc6 | 252 | The style will be set to wxSTIPPLE, unless the bitmap has a mask associated |
e7240349 | 253 | to it, in which case the style will be set to wxSTIPPLE\_MASK\_OPAQUE. |
a660d684 | 254 | |
6e7b6cc6 | 255 | If the wxSTIPPLE variant is used, the bitmap will be used to fill out the |
e7240349 | 256 | area to be drawn. If the wxSTIPPLE\_MASK\_OPAQUE is used, the current |
6e7b6cc6 RR |
257 | text foreground and text background determine what colours are used for |
258 | displaying and the bits in the mask (which is a mono-bitmap actually) | |
259 | determine where to draw what. | |
260 | ||
261 | Note that under Windows 95, only 8x8 pixel large stipple bitmaps are | |
262 | supported, Windows 98 and NT as well as GTK support arbitrary bitmaps. | |
a660d684 KB |
263 | |
264 | \wxheading{See also} | |
265 | ||
266 | \helpref{wxBitmap}{wxbitmap} | |
267 | ||
cf000528 | 268 | |
a660d684 KB |
269 | \membersection{wxBrush::SetStyle}\label{wxbrushsetstyle} |
270 | ||
eaaa6a06 | 271 | \func{void}{SetStyle}{\param{int}{ style}} |
a660d684 KB |
272 | |
273 | Sets the brush style. | |
274 | ||
275 | \docparam{style}{One of: | |
276 | ||
277 | \begin{twocollist}\itemsep=0pt | |
278 | \twocolitem{{\bf wxTRANSPARENT}}{Transparent (no fill).} | |
279 | \twocolitem{{\bf wxSOLID}}{Solid.} | |
280 | \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.} | |
281 | \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.} | |
282 | \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.} | |
283 | \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.} | |
284 | \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.} | |
285 | \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.} | |
286 | \twocolitem{{\bf wxSTIPPLE}}{Stippled using a bitmap.} | |
e7240349 | 287 | \twocolitem{{\bf wxSTIPPLE\_MASK\_OPAQUE}}{Stippled using a bitmap's mask.} |
a660d684 KB |
288 | \end{twocollist}} |
289 | ||
290 | \wxheading{See also} | |
291 | ||
292 | \helpref{wxBrush::GetStyle}{wxbrushgetstyle} | |
293 | ||
cf000528 | 294 | |
a660d684 KB |
295 | \membersection{wxBrush::operator $=$}\label{wxbrushassignment} |
296 | ||
297 | \func{wxBrush\&}{operator $=$}{\param{const wxBrush\& }{brush}} | |
298 | ||
a91225b2 | 299 | Assignment operator, using \helpref{reference counting}{trefcount}. |
a660d684 | 300 | |
cf000528 | 301 | |
a660d684 KB |
302 | \membersection{wxBrush::operator $==$}\label{wxbrushequals} |
303 | ||
304 | \func{bool}{operator $==$}{\param{const wxBrush\& }{brush}} | |
305 | ||
55ccdb93 VZ |
306 | Equality operator. |
307 | See \helpref{reference-counted object comparison}{refcountequality} for more info. | |
a660d684 | 308 | |
cf000528 | 309 | |
a660d684 KB |
310 | \membersection{wxBrush::operator $!=$}\label{wxbrushnotequals} |
311 | ||
312 | \func{bool}{operator $!=$}{\param{const wxBrush\& }{brush}} | |
313 | ||
55ccdb93 VZ |
314 | Inequality operator. |
315 | See \helpref{reference-counted object comparison}{refcountequality} for more info. | |
316 | ||
a660d684 KB |
317 | |
318 | \section{\class{wxBrushList}}\label{wxbrushlist} | |
319 | ||
320 | A brush list is a list containing all brushes which have been created. | |
321 | ||
322 | \wxheading{Derived from} | |
323 | ||
324 | \helpref{wxList}{wxlist}\\ | |
325 | \helpref{wxObject}{wxobject} | |
326 | ||
954b8ae6 JS |
327 | \wxheading{Include files} |
328 | ||
329 | <wx/gdicmn.h> | |
330 | ||
a7af285d VZ |
331 | \wxheading{Library} |
332 | ||
333 | \helpref{wxCore}{librarieslist} | |
334 | ||
a660d684 KB |
335 | \wxheading{Remarks} |
336 | ||
337 | There is only one instance of this class: {\bf wxTheBrushList}. Use | |
338 | this object to search for a previously created brush of the desired | |
339 | type and create it if not already found. In some windowing systems, | |
340 | the brush may be a scarce resource, so it can pay to reuse old | |
341 | resources if possible. When an application finishes, all brushes will | |
342 | be deleted and their resources freed, eliminating the possibility of | |
343 | `memory leaks'. However, it is best not to rely on this automatic | |
344 | cleanup because it can lead to double deletion in some circumstances. | |
345 | ||
fc2171bd | 346 | There are two mechanisms in recent versions of wxWidgets which make the |
a660d684 | 347 | brush list less useful than it once was. Under Windows, scarce resources |
43e8916f | 348 | are cleaned up internally if they are not being used. Also, a reference |
a660d684 KB |
349 | counting mechanism applied to all GDI objects means that some sharing |
350 | of underlying resources is possible. You don't have to keep track of pointers, | |
43e8916f | 351 | working out when it is safe delete a brush, because the reference counting does |
a660d684 KB |
352 | it for you. For example, you can set a brush in a device context, and then |
353 | immediately delete the brush you passed, because the brush is `copied'. | |
354 | ||
355 | So you may find it easier to ignore the brush list, and instead create | |
356 | and copy brushes as you see fit. If your Windows resource meter suggests | |
357 | your application is using too many resources, you can resort to using | |
358 | GDI lists to share objects explicitly. | |
359 | ||
fc2171bd | 360 | The only compelling use for the brush list is for wxWidgets to keep |
a660d684 | 361 | track of brushes in order to clean them up on exit. It is also kept for |
fc2171bd | 362 | backward compatibility with earlier versions of wxWidgets. |
a660d684 KB |
363 | |
364 | \wxheading{See also} | |
365 | ||
366 | \helpref{wxBrush}{wxbrush} | |
367 | ||
368 | \latexignore{\rtfignore{\wxheading{Members}}} | |
369 | ||
cf000528 | 370 | |
a660d684 KB |
371 | \membersection{wxBrushList::wxBrushList}\label{wxbrushlistconstr} |
372 | ||
373 | \func{void}{wxBrushList}{\void} | |
374 | ||
375 | Constructor. The application should not construct its own brush list: | |
376 | use the object pointer {\bf wxTheBrushList}. | |
377 | ||
cf000528 | 378 | |
cf000528 | 379 | \membersection{wxBrushList::FindOrCreateBrush}\label{wxbrushlistfindorcreatebrush} |
a660d684 | 380 | |
cf000528 | 381 | \func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style = wxSOLID}} |
a660d684 KB |
382 | |
383 | Finds a brush with the specified attributes and returns it, else creates a new brush, adds it | |
384 | to the brush list, and returns it. | |
385 | ||
a660d684 KB |
386 | \wxheading{Parameters} |
387 | ||
388 | \docparam{colour}{Colour object.} | |
389 | ||
a660d684 KB |
390 | \docparam{style}{Brush style. See \helpref{wxBrush::SetStyle}{wxbrushsetstyle} for a list of styles.} |
391 | ||
cf000528 | 392 |