interface/wx/brush.h

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