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