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     virtual 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     virtual 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     virtual void SetColour(wxColour& colour);
 178     virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
 179     //@}
 180
 181     /**
 182         Sets the stipple bitmap.
 183
 184         @param bitmap
 185             The bitmap to use for stippling.
 186
 187         @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
 188                  has a mask associated to it, in which case the style will be set
 189                  to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
 190
 191         @see wxBitmap
 192     */
 193     virtual void SetStipple(const wxBitmap& bitmap);
 194
 195     /**
 196         Sets the brush style.
 197
 198         @param style
 199             One of the ::wxBrushStyle values.
 200
 201         @see GetStyle()
 202     */
 203     virtual void SetStyle(wxBrushStyle style);
 204
 205     /**
 206         Inequality operator.
 207         See @ref overview_refcount_equality for more info.
 208     */
 209     bool operator !=(const wxBrush& brush) const;
 210
 211     /**
 212         Equality operator.
 213         See @ref overview_refcount_equality for more info.
 214     */
 215     bool operator ==(const wxBrush& brush) const;
 216 };
 217
 218 /**
 219     An empty brush.
 220 */
 221 wxBrush wxNullBrush;
 222
 223 /**
 224     Blue brush.
 225 */
 226 wxBrush* wxBLUE_BRUSH;
 227
 228 /**
 229     Green brush.
 230 */
 231 wxBrush* wxGREEN_BRUSH;
 232
 233 /**
 234     White brush.
 235 */
 236 wxBrush* wxWHITE_BRUSH;
 237
 238 /**
 239     Black brush.
 240 */
 241 wxBrush* wxBLACK_BRUSH;
 242
 243 /**
 244     Grey brush.
 245 */
 246 wxBrush* wxGREY_BRUSH;
 247
 248 /**
 249     Medium grey brush.
 250 */
 251 wxBrush* wxMEDIUM_GREY_BRUSH;
 252
 253 /**
 254     Light grey brush.
 255 */
 256 wxBrush* wxLIGHT_GREY_BRUSH;
 257
 258 /**
 259     Transparent brush.
 260 */
 261 wxBrush* wxTRANSPARENT_BRUSH;
 262
 263 /**
 264     Cyan brush.
 265 */
 266 wxBrush* wxCYAN_BRUSH;
 267
 268 /**
 269     Red brush.
 270 */
 271 wxBrush* wxRED_BRUSH;
 272
 273
 274
 275 /**
 276     @class wxBrushList
 277     @wxheader{gdicmn.h}
 278
 279     A brush list is a list containing all brushes which have been created.
 280
 281     The application should not construct its own brush list: it should use the
 282     object pointer ::wxTheBrushList.
 283
 284     @library{wxcore}
 285     @category{gdi}
 286
 287     @see wxBrush
 288 */
 289 class wxBrushList : public wxList
 290 {
 291 public:
 292     /**
 293         Finds a brush with the specified attributes and returns it, else creates a new
 294         brush, adds it to the brush list, and returns it.
 295
 296         @param colour
 297             Colour object.
 298         @param style
 299             Brush style. See ::wxBrushStyle for a list of styles.
 300     */
 301     wxBrush* FindOrCreateBrush(const wxColour& colour,
 302                                wxBrushStyle style = wxBRUSHSTYLE_SOLID);
 303 };
 304
 305 /**
 306     The global wxBrushList instance.
 307 */
 308 wxBrushList* wxTheBrushList;