1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: brush.tex 3%% Purpose: wxPen docs 4%% Author: 5%% Modified by: 6%% Created: 7%% RCS-ID: $Id: brush.tex 43567 2006-11-21 09:27:10Z RR $ 8%% Copyright: (c) wxWidgets 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxBrush}}\label{wxbrush} 13 14A brush is a drawing tool for filling in areas. It is used for painting 15the background of rectangles, ellipses, etc. It has a colour and a 16style. 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 29Objects: 30 31{\bf wxNullBrush} 32 33Pointers: 34 35{\bf wxBLUE\_BRUSH\\ 36wxGREEN\_BRUSH\\ 37wxWHITE\_BRUSH\\ 38wxBLACK\_BRUSH\\ 39wxGREY\_BRUSH\\ 40wxMEDIUM\_GREY\_BRUSH\\ 41wxLIGHT\_GREY\_BRUSH\\ 42wxTRANSPARENT\_BRUSH\\ 43wxCYAN\_BRUSH\\ 44wxRED\_BRUSH} 45 46\wxheading{Remarks} 47 48On a monochrome display, wxWidgets shows 49all brushes as white unless the colour is really black. 50 51Do not initialize objects on the stack before the program commences, 52since other required structures may not have been set up yet. Instead, 53define global pointers to objects and create them in \helpref{wxApp::OnInit}{wxapponinit} or 54when required. 55 56An application may wish to create brushes with different 57characteristics dynamically, and there is the consequent danger that a 58large number of duplicate brushes will be created. Therefore an 59application may wish to get a pointer to a brush by using the global 60list of brushes {\bf wxTheBrushList}, and calling the member function 61\rtfsp{\bf FindOrCreateBrush}. 62 63This class uses \helpref{reference counting and copy-on-write}{trefcount} 64internally so that assignments between two instances of this class are very 65cheap. You can therefore use actual objects instead of pointers without 66efficiency problems. If an instance of this class is changed it will create 67its own data internally so that other instances, which previously shared the 68data 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 82Default constructor. The brush will be uninitialised, and \helpref{wxBrush:IsOk}{wxbrushisok} will 83return false. 84 85\func{}{wxBrush}{\param{const wxColour\&}{ colour}, \param{int}{ style = {\tt wxSOLID}}} 86 87Constructs a brush from a colour object and style. 88 89\func{}{wxBrush}{\param{const wxString\& }{colourName}, \param{int}{ style}} 90 91Constructs a brush from a colour name and style. 92 93\func{}{wxBrush}{\param{const wxBitmap\& }{stippleBitmap}} 94 95Constructs a stippled brush using a bitmap. 96 97\func{}{wxBrush}{\param{const wxBrush\&}{ brush}} 98 99Copy 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 127If 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 138Destructor. 139See \helpref{reference-counted object destruction}{refcountdestruct} for more info. 140 141\wxheading{Remarks} 142 143Although all remaining brushes are deleted when the application exits, 144the application should try to clean up all brushes itself. This is because 145wxWidgets cannot know if a pointer to the brush object is stored in an 146application 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 153Returns 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 164Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE style, 165this 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 176Returns 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 201Returns 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 212Returns true if the brush is initialised. It will return false if the default 213constructor has been used (for example, the brush is a member of a class, or 214NULL has been assigned to it). 215 216 217\membersection{wxBrush::SetColour}\label{wxbrushsetcolour} 218 219\func{void}{SetColour}{\param{wxColour\& }{colour}} 220 221Sets the brush colour using a reference to a colour object. 222 223\func{void}{SetColour}{\param{const wxString\& }{colourName}} 224 225Sets 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 229Sets 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 240Sets the stipple bitmap. 241 242\wxheading{Parameters} 243 244\docparam{bitmap}{The bitmap to use for stippling.} 245 246\wxheading{Remarks} 247 248The style will be set to wxSTIPPLE, unless the bitmap has a mask associated 249to it, in which case the style will be set to wxSTIPPLE\_MASK\_OPAQUE. 250 251If the wxSTIPPLE variant is used, the bitmap will be used to fill out the 252area to be drawn. If the wxSTIPPLE\_MASK\_OPAQUE is used, the current 253text foreground and text background determine what colours are used for 254displaying and the bits in the mask (which is a mono-bitmap actually) 255determine where to draw what. 256 257Note that under Windows 95, only 8x8 pixel large stipple bitmaps are 258supported, 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 269Sets 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 295Assignment operator, using \helpref{reference counting}{trefcount}. 296 297 298\membersection{wxBrush::operator $==$}\label{wxbrushequals} 299 300\func{bool}{operator $==$}{\param{const wxBrush\& }{brush}} 301 302Equality operator. 303See \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 310Inequality operator. 311See \helpref{reference-counted object comparison}{refcountequality} for more info. 312 313 314\section{\class{wxBrushList}}\label{wxbrushlist} 315 316A 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 329There is only one instance of this class: {\bf wxTheBrushList}. Use 330this object to search for a previously created brush of the desired 331type and create it if not already found. In some windowing systems, 332the brush may be a scarce resource, so it can pay to reuse old 333resources if possible. When an application finishes, all brushes will 334be deleted and their resources freed, eliminating the possibility of 335`memory leaks'. However, it is best not to rely on this automatic 336cleanup because it can lead to double deletion in some circumstances. 337 338There are two mechanisms in recent versions of wxWidgets which make the 339brush list less useful than it once was. Under Windows, scarce resources 340are cleaned up internally if they are not being used. Also, a reference 341counting mechanism applied to all GDI objects means that some sharing 342of underlying resources is possible. You don't have to keep track of pointers, 343working out when it is safe delete a brush, because the reference counting does 344it for you. For example, you can set a brush in a device context, and then 345immediately delete the brush you passed, because the brush is `copied'. 346 347So you may find it easier to ignore the brush list, and instead create 348and copy brushes as you see fit. If your Windows resource meter suggests 349your application is using too many resources, you can resort to using 350GDI lists to share objects explicitly. 351 352The only compelling use for the brush list is for wxWidgets to keep 353track of brushes in order to clean them up on exit. It is also kept for 354backward 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 367Constructor. The application should not construct its own brush list: 368use 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 375Finds a brush with the specified attributes and returns it, else creates a new brush, adds it 376to 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 385