]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \section{\class{wxBrush}}\label{wxbrush} |
2 | ||
3 | A brush is a drawing tool for filling in areas. It is used for painting | |
4 | the background of rectangles, ellipses, etc. It has a colour and a | |
5 | style. | |
6 | ||
7 | \wxheading{Derived from} | |
8 | ||
9 | \helpref{wxGDIObject}{wxgdiobject}\\ | |
10 | \helpref{wxObject}{wxobject} | |
11 | ||
12 | \wxheading{Remarks} | |
13 | ||
14 | On a monochrome display, wxWindows shows | |
15 | all brushes as white unless the colour is really black. | |
16 | ||
17 | Do not initialize objects on the stack before the program commences, | |
18 | since other required structures may not have been set up yet. Instead, | |
19 | define global pointers to objects and create them in \helpref{wxApp::OnInit}{wxapponinit} or | |
20 | when required. | |
21 | ||
22 | An application may wish to create brushes with different | |
23 | characteristics dynamically, and there is the consequent danger that a | |
24 | large number of duplicate brushes will be created. Therefore an | |
25 | application may wish to get a pointer to a brush by using the global | |
26 | list of brushes {\bf wxTheBrushList}, and calling the member function | |
27 | \rtfsp{\bf FindOrCreateBrush}. | |
28 | ||
29 | wxBrush uses a reference counting system, so assignments between brushes are very | |
30 | cheap. You can therefore use actual wxBrush objects instead of pointers without | |
12a44087 RR |
31 | efficiency problems. Once one wxBrush object changes its data it will create its |
32 | own brush data internally so that other brushes, which previously shared the | |
33 | data using the reference counting, are not affected. | |
a660d684 | 34 | |
5b6aa0ff | 35 | %TODO: an overview for wxBrush. |
a660d684 KB |
36 | \wxheading{See also} |
37 | ||
38 | \helpref{wxBrushList}{wxbrushlist}, \helpref{wxDC}{wxdc}, \helpref{wxDC::SetBrush}{wxdcsetbrush} | |
39 | ||
40 | \latexignore{\rtfignore{\wxheading{Members}}} | |
41 | ||
42 | \membersection{wxBrush::wxBrush} | |
43 | ||
44 | \func{}{wxBrush}{\void} | |
45 | ||
46 | Default constructor. The brush will be uninitialised, and \helpref{wxBrush::Ok}{wxbrushok} will | |
47 | return FALSE. | |
48 | ||
eaaa6a06 | 49 | \func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style}} |
a660d684 KB |
50 | |
51 | Constructs a brush from a colour object and style. | |
52 | ||
eaaa6a06 | 53 | \func{}{wxBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}} |
a660d684 KB |
54 | |
55 | Constructs a brush from a colour name and style. | |
56 | ||
57 | \func{}{wxBrush}{\param{const wxBitmap\& }{stippleBitmap}} | |
58 | ||
59 | Constructs a stippled brush using a bitmap. | |
60 | ||
61 | \func{}{wxBrush}{\param{const wxBrush\&}{ brush}} | |
62 | ||
63 | Copy constructor. This uses reference counting so is a cheap operation. | |
64 | ||
a660d684 KB |
65 | \wxheading{Parameters} |
66 | ||
67 | \docparam{colour}{Colour object.} | |
68 | ||
69 | \docparam{colourName}{Colour name. The name will be looked up in the colour database.} | |
70 | ||
71 | \docparam{style}{One of: | |
72 | ||
73 | \begin{twocollist}\itemsep=0pt | |
74 | \twocolitem{{\bf wxTRANSPARENT}}{Transparent (no fill).} | |
75 | \twocolitem{{\bf wxSOLID}}{Solid.} | |
76 | \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.} | |
77 | \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.} | |
78 | \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.} | |
79 | \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.} | |
80 | \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.} | |
81 | \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.} | |
82 | \end{twocollist}} | |
83 | ||
84 | \docparam{brush}{Pointer or reference to a brush to copy.} | |
85 | ||
86 | \docparam{stippleBitmap}{A bitmap to use for stippling.} | |
87 | ||
88 | \wxheading{Remarks} | |
89 | ||
90 | If a stipple brush is created, the brush style will be set to wxSTIPPLE. | |
91 | ||
92 | \wxheading{See also} | |
93 | ||
94 | \helpref{wxBrushList}{wxbrushlist}, \helpref{wxColour}{wxcolour}, \helpref{wxColourDatabase}{wxcolourdatabase} | |
95 | ||
96 | \membersection{wxBrush::\destruct{wxBrush}} | |
97 | ||
98 | \func{void}{\destruct{wxBrush}}{\void} | |
99 | ||
100 | Destructor. | |
101 | ||
102 | \wxheading{Remarks} | |
103 | ||
104 | The destructor may not delete the underlying brush object of the native windowing | |
105 | system, since wxBrush uses a reference counting system for efficiency. | |
106 | ||
107 | Although all remaining brushes are deleted when the application exits, | |
108 | the application should try to clean up all brushes itself. This is because | |
109 | wxWindows cannot know if a pointer to the brush object is stored in an | |
110 | application data structure, and there is a risk of double deletion. | |
111 | ||
112 | \membersection{wxBrush::GetColour}\label{wxbrushgetcolour} | |
113 | ||
114 | \constfunc{wxColour\&}{GetColour}{\void} | |
115 | ||
116 | Returns a reference to the brush colour. | |
117 | ||
118 | \wxheading{See also} | |
119 | ||
120 | \helpref{wxBrush::SetColour}{wxbrushsetcolour} | |
121 | ||
122 | \membersection{wxBrush::GetStipple}\label{wxbrushgetstipple} | |
123 | ||
124 | \constfunc{wxBitmap *}{GetStipple}{\void} | |
125 | ||
126 | Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE style, | |
127 | this bitmap may be non-NULL but uninitialised (\helpref{wxBitmap::Ok}{wxbitmapok} returns FALSE). | |
128 | ||
129 | \wxheading{See also} | |
130 | ||
131 | \helpref{wxBrush::SetStipple}{wxbrushsetstipple} | |
132 | ||
133 | \membersection{wxBrush::GetStyle}\label{wxbrushgetstyle} | |
134 | ||
135 | \constfunc{int}{GetStyle}{\void} | |
136 | ||
137 | Returns the brush style, one of: | |
138 | ||
139 | \begin{twocollist}\itemsep=0pt | |
140 | \twocolitem{{\bf wxTRANSPARENT}}{Transparent (no fill).} | |
141 | \twocolitem{{\bf wxSOLID}}{Solid.} | |
142 | \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.} | |
143 | \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.} | |
144 | \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.} | |
145 | \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.} | |
146 | \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.} | |
147 | \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.} | |
148 | \twocolitem{{\bf wxSTIPPLE}}{Stippled using a bitmap.} | |
149 | \end{twocollist} | |
150 | ||
151 | \wxheading{See also} | |
152 | ||
153 | \helpref{wxBrush::SetStyle}{wxbrushsetstyle}, \helpref{wxBrush::SetColour}{wxbrushsetcolour},\rtfsp | |
154 | \helpref{wxBrush::SetStipple}{wxbrushsetstipple} | |
155 | ||
156 | \membersection{wxBrush::Ok}\label{wxbrushok} | |
157 | ||
158 | \constfunc{bool}{Ok}{\void} | |
159 | ||
160 | Returns TRUE if the brush is initialised. It will return FALSE if the default | |
161 | constructor has been used (for example, the brush is a member of a class, or | |
162 | NULL has been assigned to it). | |
163 | ||
164 | \membersection{wxBrush::SetColour}\label{wxbrushsetcolour} | |
165 | ||
166 | \func{void}{SetColour}{\param{wxColour\& }{colour}} | |
167 | ||
168 | Sets the brush colour using a reference to a colour object. | |
169 | ||
170 | \func{void}{SetColour}{\param{const wxString\& }{colourName}} | |
171 | ||
172 | Sets the brush colour using a colour name from the colour database. | |
173 | ||
174 | \func{void}{SetColour}{\param{const unsigned char}{ red}, \param{const unsigned char}{ green}, \param{const unsigned char}{ blue}} | |
175 | ||
176 | Sets the brush colour using red, green and blue values. | |
177 | ||
178 | \wxheading{See also} | |
179 | ||
180 | \helpref{wxBrush::GetColour}{wxbrushgetcolour} | |
181 | ||
182 | \membersection{wxBrush::SetStipple}\label{wxbrushsetstipple} | |
183 | ||
184 | \func{void}{SetStipple}{\param{const wxBitmap\&}{ bitmap}} | |
185 | ||
186 | Sets the stipple bitmap. | |
187 | ||
188 | \wxheading{Parameters} | |
189 | ||
190 | \docparam{bitmap}{The bitmap to use for stippling.} | |
191 | ||
192 | \wxheading{Remarks} | |
193 | ||
194 | The style will be set to wxSTIPPLE. | |
195 | ||
196 | Note that there is a big difference between stippling in X and Windows. | |
197 | On X, the stipple is a mask between the wxBitmap and current colour. | |
198 | On Windows, the current colour is ignored, and the bitmap colour is used. | |
199 | However, for pre-defined modes like wxCROSS\_HATCH, the behaviour is the | |
200 | same for both platforms. | |
201 | ||
202 | \wxheading{See also} | |
203 | ||
204 | \helpref{wxBitmap}{wxbitmap} | |
205 | ||
206 | \membersection{wxBrush::SetStyle}\label{wxbrushsetstyle} | |
207 | ||
eaaa6a06 | 208 | \func{void}{SetStyle}{\param{int}{ style}} |
a660d684 KB |
209 | |
210 | Sets the brush style. | |
211 | ||
212 | \docparam{style}{One of: | |
213 | ||
214 | \begin{twocollist}\itemsep=0pt | |
215 | \twocolitem{{\bf wxTRANSPARENT}}{Transparent (no fill).} | |
216 | \twocolitem{{\bf wxSOLID}}{Solid.} | |
217 | \twocolitem{{\bf wxBDIAGONAL\_HATCH}}{Backward diagonal hatch.} | |
218 | \twocolitem{{\bf wxCROSSDIAG\_HATCH}}{Cross-diagonal hatch.} | |
219 | \twocolitem{{\bf wxFDIAGONAL\_HATCH}}{Forward diagonal hatch.} | |
220 | \twocolitem{{\bf wxCROSS\_HATCH}}{Cross hatch.} | |
221 | \twocolitem{{\bf wxHORIZONTAL\_HATCH}}{Horizontal hatch.} | |
222 | \twocolitem{{\bf wxVERTICAL\_HATCH}}{Vertical hatch.} | |
223 | \twocolitem{{\bf wxSTIPPLE}}{Stippled using a bitmap.} | |
224 | \end{twocollist}} | |
225 | ||
226 | \wxheading{See also} | |
227 | ||
228 | \helpref{wxBrush::GetStyle}{wxbrushgetstyle} | |
229 | ||
230 | \membersection{wxBrush::operator $=$}\label{wxbrushassignment} | |
231 | ||
232 | \func{wxBrush\&}{operator $=$}{\param{const wxBrush\& }{brush}} | |
233 | ||
234 | Assignment operator, using reference counting. Returns a reference | |
235 | to `this'. | |
236 | ||
237 | \membersection{wxBrush::operator $==$}\label{wxbrushequals} | |
238 | ||
239 | \func{bool}{operator $==$}{\param{const wxBrush\& }{brush}} | |
240 | ||
241 | Equality operator. Two brushes are equal if they contain pointers | |
242 | to the same underlying brush data. It does not compare each attribute, | |
243 | so two independently-created brushes using the same parameters will | |
244 | fail the test. | |
245 | ||
246 | \membersection{wxBrush::operator $!=$}\label{wxbrushnotequals} | |
247 | ||
248 | \func{bool}{operator $!=$}{\param{const wxBrush\& }{brush}} | |
249 | ||
250 | Inequality operator. Two brushes are not equal if they contain pointers | |
251 | to different underlying brush data. It does not compare each attribute. | |
252 | ||
253 | \section{\class{wxBrushList}}\label{wxbrushlist} | |
254 | ||
255 | A brush list is a list containing all brushes which have been created. | |
256 | ||
257 | \wxheading{Derived from} | |
258 | ||
259 | \helpref{wxList}{wxlist}\\ | |
260 | \helpref{wxObject}{wxobject} | |
261 | ||
262 | \wxheading{Remarks} | |
263 | ||
264 | There is only one instance of this class: {\bf wxTheBrushList}. Use | |
265 | this object to search for a previously created brush of the desired | |
266 | type and create it if not already found. In some windowing systems, | |
267 | the brush may be a scarce resource, so it can pay to reuse old | |
268 | resources if possible. When an application finishes, all brushes will | |
269 | be deleted and their resources freed, eliminating the possibility of | |
270 | `memory leaks'. However, it is best not to rely on this automatic | |
271 | cleanup because it can lead to double deletion in some circumstances. | |
272 | ||
273 | There are two mechanisms in recent versions of wxWindows which make the | |
274 | brush list less useful than it once was. Under Windows, scarce resources | |
275 | are cleaned up internally if they are not being used. Also, a referencing | |
276 | counting mechanism applied to all GDI objects means that some sharing | |
277 | of underlying resources is possible. You don't have to keep track of pointers, | |
278 | working out when it is safe delete a brush, because the referencing counting does | |
279 | it for you. For example, you can set a brush in a device context, and then | |
280 | immediately delete the brush you passed, because the brush is `copied'. | |
281 | ||
282 | So you may find it easier to ignore the brush list, and instead create | |
283 | and copy brushes as you see fit. If your Windows resource meter suggests | |
284 | your application is using too many resources, you can resort to using | |
285 | GDI lists to share objects explicitly. | |
286 | ||
287 | The only compelling use for the brush list is for wxWindows to keep | |
288 | track of brushes in order to clean them up on exit. It is also kept for | |
289 | backward compatibility with earlier versions of wxWindows. | |
290 | ||
291 | \wxheading{See also} | |
292 | ||
293 | \helpref{wxBrush}{wxbrush} | |
294 | ||
295 | \latexignore{\rtfignore{\wxheading{Members}}} | |
296 | ||
297 | \membersection{wxBrushList::wxBrushList}\label{wxbrushlistconstr} | |
298 | ||
299 | \func{void}{wxBrushList}{\void} | |
300 | ||
301 | Constructor. The application should not construct its own brush list: | |
302 | use the object pointer {\bf wxTheBrushList}. | |
303 | ||
304 | \membersection{wxBrushList::AddBrush}\label{wxbrushlistaddbrush} | |
305 | ||
306 | \func{void}{AddBrush}{\param{wxBrush *}{brush}} | |
307 | ||
308 | Used internally by wxWindows to add a brush to the list. | |
309 | ||
310 | \membersection{wxBrushList::FindOrCreateBrush}\label{wxbrushlistfindorcreatebrush} | |
311 | ||
eaaa6a06 | 312 | \func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style}} |
a660d684 KB |
313 | |
314 | Finds a brush with the specified attributes and returns it, else creates a new brush, adds it | |
315 | to the brush list, and returns it. | |
316 | ||
eaaa6a06 | 317 | \func{wxBrush *}{FindOrCreateBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}} |
a660d684 KB |
318 | |
319 | Finds a brush with the specified attributes and returns it, else creates a new brush, adds it | |
320 | to the brush list, and returns it. | |
321 | ||
322 | Finds a brush of the given specification, or creates one and adds it to the list. | |
323 | ||
324 | \wxheading{Parameters} | |
325 | ||
326 | \docparam{colour}{Colour object.} | |
327 | ||
328 | \docparam{colourName}{Colour name, which should be in the colour database.} | |
329 | ||
330 | \docparam{style}{Brush style. See \helpref{wxBrush::SetStyle}{wxbrushsetstyle} for a list of styles.} | |
331 | ||
332 | \membersection{wxBrushList::RemoveBrush}\label{wxbrushlistremovebrush} | |
333 | ||
334 | \func{void}{RemoveBrush}{\param{wxBrush *}{brush}} | |
335 | ||
336 | Used by wxWindows to remove a brush from the list. | |
337 | ||
338 |