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