interface/brush.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        brush.h
   3 // Purpose:     interface of wxBrush
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     The possible brush styles.
  11 */
  12 enum wxBrushStyle
  13 {
  14     wxBRUSHSTYLE_SOLID = wxSOLID,
  15         /**< Solid. */
  16
  17     wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT,
  18         /**< Transparent (no fill). */
  19
  20     wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
  21         /**< @todo WHAT's THIS?? */
  22
  23     wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
  24         /**< @todo WHAT's THIS?? */
  25
  26     wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
  27         /**< Uses a bitmap as a stipple. */
  28
  29     wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
  30         /**< Backward diagonal hatch. */
  31
  32     wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
  33         /**< Cross-diagonal hatch. */
  34
  35     wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
  36         /**< Forward diagonal hatch. */
  37
  38     wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
  39         /**< Cross hatch. */
  40
  41     wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
  42         /**< Horizontal hatch. */
  43
  44     wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
  45         /**< Vertical hatch. */
  46
  47     wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
  48     wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
  49     wxBRUSHSTYLE_MAX
  50 };
  51
  52
  53
  54 /**
  55     @class wxBrush
  56     @wxheader{brush.h}
  57
  58     A brush is a drawing tool for filling in areas. It is used for painting
  59     the background of rectangles, ellipses, etc. It has a colour and a style.
  60
  61     On a monochrome display, wxWidgets shows all brushes as white unless the
  62     colour is really black.
  63
  64     Do not initialize objects on the stack before the program commences, since
  65     other required structures may not have been set up yet. Instead, define
  66     global pointers to objects and create them in wxApp::OnInit or when required.
  67
  68     An application may wish to create brushes with different characteristics
  69     dynamically, and there is the consequent danger that a large number of
  70     duplicate brushes will be created. Therefore an application may wish to
  71     get a pointer to a brush by using the global list of brushes ::wxTheBrushList,
  72     and calling the member function wxBrushList::FindOrCreateBrush().
  73
  74     This class uses reference counting and copy-on-write internally so that
  75     assignments between two instances of this class are very cheap.
  76     You can therefore use actual objects instead of pointers without efficiency problems.
  77     If an instance of this class is changed it will create its own data internally
  78     so that other instances, which previously shared the data using the reference
  79     counting, are not affected.
  80
  81     @library{wxcore}
  82     @category{gdi}
  83
  84     @stdobjects
  85     ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH,
  86     ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH,
  87     ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH
  88
  89     @see wxBrushList, wxDC, wxDC::SetBrush
  90 */
  91 class wxBrush : public wxGDIObject
  92 {
  93 public:
  94     /**
  95         Default constructor.
  96         The brush will be uninitialised, and wxBrush:IsOk() will return @false.
  97     */
  98     wxBrush();
  99
 100     /**
 101         Constructs a brush from a colour object and @a style.
 102
 103         @param colour
 104             Colour object.
 105         @param style
 106             One of the ::wxBrushStyle enumeration values.
 107     */
 108     wxBrush(const wxColour& colour, wxBrushStyle style = wxSOLID);
 109
 110     /**
 111         Constructs a brush from a colour name and @a style.
 112
 113         @param colourName
 114             Colour name. The name will be looked up in the colour database.
 115         @param style
 116             One of the ::wxBrushStyle enumeration values.
 117
 118         @see wxColourDatabase
 119     */
 120     wxBrush(const wxString& colourName, wxBrushStyle style);
 121
 122     /**
 123         Constructs a stippled brush using a bitmap.
 124         The brush style will be set to wxBRUSHSTYLE_STIPPLE.
 125     */
 126     wxBrush(const wxBitmap& stippleBitmap);
 127
 128     /**
 129         Copy constructor, uses @ref overview_refcount "reference counting".
 130     */
 131     wxBrush(const wxBrush& brush);
 132
 133     /**
 134         Destructor.
 135
 136         See @ref overview_refcount_destruct for more info.
 137
 138         @remarks Although all remaining brushes are deleted when the application
 139                  exits, the application should try to clean up all brushes itself.
 140                  This is because wxWidgets cannot know if a pointer to the brush
 141                  object is stored in an application data structure, and there is
 142                  a risk of double deletion.
 143     */
 144     ~wxBrush();
 145
 146     /**
 147         Returns a reference to the brush colour.
 148
 149         @see SetColour()
 150     */
 151     wxColour GetColour() const;
 152
 153     /**
 154         Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
 155         style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
 156
 157         @see SetStipple()
 158     */
 159     wxBitmap* GetStipple() const;
 160
 161     /**
 162         Returns the brush style, one of the ::wxBrushStyle values.
 163
 164         @see SetStyle(), SetColour(), SetStipple()
 165     */
 166     wxBrushStyle GetStyle() const;
 167
 168     /**
 169         Returns @true if the style of the brush is any of hatched fills.
 170
 171         @see GetStyle()
 172     */
 173     bool IsHatch() const;
 174
 175     /**
 176         Returns @true if the brush is initialised. It will return @false if the default
 177         constructor has been used (for example, the brush is a member of a class, or
 178         @NULL has been assigned to it).
 179     */
 180     bool IsOk() const;
 181
 182     //@{
 183     /**
 184         Sets the brush colour using red, green and blue values.
 185
 186         @see GetColour()
 187     */
 188     void SetColour(wxColour& colour);
 189     void SetColour(const wxString& colourName);
 190     void SetColour(unsigned char red, unsigned char green,
 191                    unsigned char blue);
 192     //@}
 193
 194     /**
 195         Sets the stipple bitmap.
 196
 197         @param bitmap
 198             The bitmap to use for stippling.
 199
 200         @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
 201                  has a mask associated to it, in which case the style will be set
 202                  to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
 203
 204         @see wxBitmap
 205     */
 206     void SetStipple(const wxBitmap& bitmap);
 207
 208     /**
 209         Sets the brush style.
 210
 211         @param style
 212             One of the ::wxBrushStyle values.
 213
 214         @see GetStyle()
 215     */
 216     void SetStyle(wxBrushStyle style);
 217
 218     /**
 219         Inequality operator.
 220         See @ref overview_refcount_equality for more info.
 221     */
 222     bool operator !=(const wxBrush& brush);
 223
 224     /**
 225         Assignment operator, using @ref overview_refcount "reference counting".
 226     */
 227     wxBrush operator =(const wxBrush& brush);
 228
 229     /**
 230         Equality operator.
 231         See @ref overview_refcount_equality for more info.
 232     */
 233     bool operator ==(const wxBrush& brush);
 234 };
 235
 236 /**
 237     An empty brush.
 238 */
 239 wxBrush wxNullBrush;
 240
 241 /**
 242     Blue brush.
 243 */
 244 wxBrush* wxBLUE_BRUSH;
 245
 246 /**
 247     Green brush.
 248 */
 249 wxBrush* wxGREEN_BRUSH;
 250
 251 /**
 252     White brush.
 253 */
 254 wxBrush* wxWHITE_BRUSH;
 255
 256 /**
 257     Black brush.
 258 */
 259 wxBrush* wxBLACK_BRUSH;
 260
 261 /**
 262     Grey brush.
 263 */
 264 wxBrush* wxGREY_BRUSH;
 265
 266 /**
 267     Medium grey brush.
 268 */
 269 wxBrush* wxMEDIUM_GREY_BRUSH;
 270
 271 /**
 272     Light grey brush.
 273 */
 274 wxBrush* wxLIGHT_GREY_BRUSH;
 275
 276 /**
 277     Transparent brush.
 278 */
 279 wxBrush* wxTRANSPARENT_BRUSH;
 280
 281 /**
 282     Cyan brush.
 283 */
 284 wxBrush* wxCYAN_BRUSH;
 285
 286 /**
 287     Red brush.
 288 */
 289 wxBrush* wxRED_BRUSH;
 290
 291
 292
 293 /**
 294     @class wxBrushList
 295     @wxheader{gdicmn.h}
 296
 297     A brush list is a list containing all brushes which have been created.
 298
 299     @library{wxcore}
 300     @category{gdi}
 301
 302     @see wxBrush
 303 */
 304 class wxBrushList : public wxList
 305 {
 306 public:
 307     /**
 308         Constructor. The application should not construct its own brush list:
 309         use the object pointer ::wxTheBrushList.
 310     */
 311     wxBrushList();
 312
 313     /**
 314         Finds a brush with the specified attributes and returns it, else creates a new
 315         brush, adds it to the brush list, and returns it.
 316
 317         @param colour
 318             Colour object.
 319         @param style
 320             Brush style. See ::wxBrushStyle for a list of styles.
 321     */
 322     wxBrush* FindOrCreateBrush(const wxColour& colour,
 323                                wxBrushStyle style = wxBRUSHSTYLE_SOLID);
 324 };
 325
 326 /**
 327     The global wxBrushList instance.
 328 */
 329 wxBrushList* wxTheBrushList;