interface/wx/brush.h

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