docs/latex/wx/brush.tex

   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
  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.
  34
  35 %TODO: an overview for wxBrush.
  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
  49 \func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style}}
  50
  51 Constructs a brush from a colour object and style.
  52
  53 \func{}{wxBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}}
  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
  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
 208 \func{void}{SetStyle}{\param{int}{ style}}
 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
 312 \func{wxBrush *}{FindOrCreateBrush}{\param{const wxColour\& }{colour}, \param{int}{ style}}
 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
 317 \func{wxBrush *}{FindOrCreateBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}}
 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