docs/latex/wx/brush.tex

   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{Library}
  28
  29 \helpref{wxCore}{librarieslist}
  30
  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
  50 \wxheading{Remarks}
  51
  52 On a monochrome display, wxWidgets shows
  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
  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
  72 data using the reference counting, are not affected.
  73
  74 %TODO: an overview for wxBrush.
  75 \wxheading{See also}
  76
  77 \helpref{wxBrushList}{wxbrushlist}, \helpref{wxDC}{wxdc}, \helpref{wxDC::SetBrush}{wxdcsetbrush}
  78
  79 \latexignore{\rtfignore{\wxheading{Members}}}
  80
  81
  82 \membersection{wxBrush::wxBrush}\label{wxbrushctor}
  83
  84 \func{}{wxBrush}{\void}
  85
  86 Default constructor. The brush will be uninitialised, and \helpref{wxBrush:IsOk}{wxbrushisok} will
  87 return false.
  88
  89 \func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style = {\tt wxSOLID}}}
  90
  91 Constructs a brush from a colour object and style.
  92
  93 \func{}{wxBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}}
  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
 103 Copy constructor, uses \helpref{reference counting}{trefcount}.
 104
 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.}
 116 \twocolitem{{\bf wxSTIPPLE}}{Uses a bitmap as a stipple.}
 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
 137
 138 \membersection{wxBrush::\destruct{wxBrush}}\label{wxbrushdtor}
 139
 140 \func{}{\destruct{wxBrush}}{\void}
 141
 142 Destructor.
 143 See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
 144
 145 \wxheading{Remarks}
 146
 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
 149 wxWidgets cannot know if a pointer to the brush object is stored in an
 150 application data structure, and there is a risk of double deletion.
 151
 152
 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
 163
 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,
 169 this bitmap may be non-NULL but uninitialised (\helpref{wxBitmap:IsOk}{wxbitmapisok} returns false).
 170
 171 \wxheading{See also}
 172
 173 \helpref{wxBrush::SetStipple}{wxbrushsetstipple}
 174
 175
 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.}
 192 \twocolitem{{\bf wxSTIPPLE\_MASK\_OPAQUE}}{Stippled using a bitmap's mask.}
 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
 200
 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
 211
 212 \membersection{wxBrush::IsOk}\label{wxbrushisok}
 213
 214 \constfunc{bool}{IsOk}{\void}
 215
 216 Returns true if the brush is initialised. It will return false if the default
 217 constructor has been used (for example, the brush is a member of a class, or
 218 NULL has been assigned to it).
 219
 220
 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
 231 \func{void}{SetColour}{\param{unsigned char}{ red}, \param{unsigned char}{ green}, \param{unsigned char}{ blue}}
 232
 233 Sets the brush colour using red, green and blue values.
 234
 235 \wxheading{See also}
 236
 237 \helpref{wxBrush::GetColour}{wxbrushgetcolour}
 238
 239
 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
 252 The style will be set to wxSTIPPLE, unless the bitmap has a mask associated
 253 to it, in which case the style will be set to wxSTIPPLE\_MASK\_OPAQUE.
 254
 255 If the wxSTIPPLE variant is used, the bitmap will be used to fill out the
 256 area to be drawn. If the wxSTIPPLE\_MASK\_OPAQUE is used, the current
 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.
 263
 264 \wxheading{See also}
 265
 266 \helpref{wxBitmap}{wxbitmap}
 267
 268
 269 \membersection{wxBrush::SetStyle}\label{wxbrushsetstyle}
 270
 271 \func{void}{SetStyle}{\param{int}{ style}}
 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.}
 287 \twocolitem{{\bf wxSTIPPLE\_MASK\_OPAQUE}}{Stippled using a bitmap's mask.}
 288 \end{twocollist}}
 289
 290 \wxheading{See also}
 291
 292 \helpref{wxBrush::GetStyle}{wxbrushgetstyle}
 293
 294
 295 \membersection{wxBrush::operator $=$}\label{wxbrushassignment}
 296
 297 \func{wxBrush\&}{operator $=$}{\param{const wxBrush\& }{brush}}
 298
 299 Assignment operator, using \helpref{reference counting}{trefcount}.
 300
 301
 302 \membersection{wxBrush::operator $==$}\label{wxbrushequals}
 303
 304 \func{bool}{operator $==$}{\param{const wxBrush\& }{brush}}
 305
 306 Equality operator.
 307 See \helpref{reference-counted object comparison}{refcountequality} for more info.
 308
 309
 310 \membersection{wxBrush::operator $!=$}\label{wxbrushnotequals}
 311
 312 \func{bool}{operator $!=$}{\param{const wxBrush\& }{brush}}
 313
 314 Inequality operator.
 315 See \helpref{reference-counted object comparison}{refcountequality} for more info.
 316
 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
 326 \wxheading{Include files}
 327
 328 <wx/gdicmn.h>
 329
 330 \wxheading{Library}
 331
 332 \helpref{wxCore}{librarieslist}
 333
 334 \wxheading{Remarks}
 335
 336 There is only one instance of this class: {\bf wxTheBrushList}.  Use
 337 this object to search for a previously created brush of the desired
 338 type and create it if not already found. In some windowing systems,
 339 the brush may be a scarce resource, so it can pay to reuse old
 340 resources if possible. When an application finishes, all brushes will
 341 be deleted and their resources freed, eliminating the possibility of
 342 `memory leaks'. However, it is best not to rely on this automatic
 343 cleanup because it can lead to double deletion in some circumstances.
 344
 345 There are two mechanisms in recent versions of wxWidgets which make the
 346 brush list less useful than it once was. Under Windows, scarce resources
 347 are cleaned up internally if they are not being used. Also, a reference
 348 counting mechanism applied to all GDI objects means that some sharing
 349 of underlying resources is possible. You don't have to keep track of pointers,
 350 working out when it is safe delete a brush, because the reference counting does
 351 it for you. For example, you can set a brush in a device context, and then
 352 immediately delete the brush you passed, because the brush is `copied'.
 353
 354 So you may find it easier to ignore the brush list, and instead create
 355 and copy brushes as you see fit. If your Windows resource meter suggests
 356 your application is using too many resources, you can resort to using
 357 GDI lists to share objects explicitly.
 358
 359 The only compelling use for the brush list is for wxWidgets to keep
 360 track of brushes in order to clean them up on exit. It is also kept for
 361 backward compatibility with earlier versions of wxWidgets.
 362
 363 \wxheading{See also}
 364
 365 \helpref{wxBrush}{wxbrush}
 366
 367 \latexignore{\rtfignore{\wxheading{Members}}}
 368
 369
 370 \membersection{wxBrushList::wxBrushList}\label{wxbrushlistconstr}
 371
 372 \func{void}{wxBrushList}{\void}
 373
 374 Constructor. The application should not construct its own brush list:
 375 use the object pointer {\bf wxTheBrushList}.
 376
 377
 378 \membersection{wxBrushList::FindOrCreateBrush}\label{wxbrushlistfindorcreatebrush}
 379
 380 \func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style = wxSOLID}}
 381
 382 Finds a brush with the specified attributes and returns it, else creates a new brush, adds it
 383 to the brush list, and returns it.
 384
 385 \wxheading{Parameters}
 386
 387 \docparam{colour}{Colour object.}
 388
 389 \docparam{style}{Brush style. See \helpref{wxBrush::SetStyle}{wxbrushsetstyle} for a list of styles.}
 390
 391