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 \helpref{wxObject}{wxobject}
 326
 327 \wxheading{Include files}
 328
 329 <wx/gdicmn.h>
 330
 331 \wxheading{Library}
 332
 333 \helpref{wxCore}{librarieslist}
 334
 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
 346 There are two mechanisms in recent versions of wxWidgets which make the
 347 brush list less useful than it once was. Under Windows, scarce resources
 348 are cleaned up internally if they are not being used. Also, a reference
 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,
 351 working out when it is safe delete a brush, because the reference counting does
 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
 360 The only compelling use for the brush list is for wxWidgets to keep
 361 track of brushes in order to clean them up on exit. It is also kept for
 362 backward compatibility with earlier versions of wxWidgets.
 363
 364 \wxheading{See also}
 365
 366 \helpref{wxBrush}{wxbrush}
 367
 368 \latexignore{\rtfignore{\wxheading{Members}}}
 369
 370
 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
 378
 379 \membersection{wxBrushList::FindOrCreateBrush}\label{wxbrushlistfindorcreatebrush}
 380
 381 \func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style = wxSOLID}}
 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
 386 \wxheading{Parameters}
 387
 388 \docparam{colour}{Colour object.}
 389
 390 \docparam{style}{Brush style. See \helpref{wxBrush::SetStyle}{wxbrushsetstyle} for a list of styles.}
 391
 392