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