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 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
  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 = wxBRUSHSTYLE_SOLID);
 109
 110     /**
 111         Constructs a stippled brush using a bitmap.
 112         The brush style will be set to wxBRUSHSTYLE_STIPPLE.
 113     */
 114     wxBrush(const wxBitmap& stippleBitmap);
 115
 116     /**
 117         Copy constructor, uses @ref overview_refcount "reference counting".
 118     */
 119     wxBrush(const wxBrush& brush);
 120
 121     /**
 122         Destructor.
 123
 124         See @ref overview_refcount_destruct for more info.
 125
 126         @remarks Although all remaining brushes are deleted when the application
 127                  exits, the application should try to clean up all brushes itself.
 128                  This is because wxWidgets cannot know if a pointer to the brush
 129                  object is stored in an application data structure, and there is
 130                  a risk of double deletion.
 131     */
 132     virtual ~wxBrush();
 133
 134     /**
 135         Returns a reference to the brush colour.
 136
 137         @see SetColour()
 138     */
 139     virtual wxColour GetColour() const;
 140
 141     /**
 142         Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
 143         style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
 144
 145         @see SetStipple()
 146     */
 147     virtual wxBitmap* GetStipple() const;
 148
 149     /**
 150         Returns the brush style, one of the ::wxBrushStyle values.
 151
 152         @see SetStyle(), SetColour(), SetStipple()
 153     */
 154     virtual wxBrushStyle GetStyle() const;
 155
 156     /**
 157         Returns @true if the style of the brush is any of hatched fills.
 158
 159         @see GetStyle()
 160     */
 161     virtual bool IsHatch() const;
 162
 163     /**
 164         Returns @true if the brush is initialised. It will return @false if the default
 165         constructor has been used (for example, the brush is a member of a class, or
 166         @NULL has been assigned to it).
 167     */
 168     virtual bool IsOk() const;
 169
 170     //@{
 171     /**
 172         Sets the brush colour using red, green and blue values.
 173
 174         @see GetColour()
 175     */
 176     virtual void SetColour(const wxColour& colour);
 177     virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
 178     //@}
 179
 180     /**
 181         Sets the stipple bitmap.
 182
 183         @param bitmap
 184             The bitmap to use for stippling.
 185
 186         @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
 187                  has a mask associated to it, in which case the style will be set
 188                  to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
 189
 190         @see wxBitmap
 191     */
 192     virtual void SetStipple(const wxBitmap& bitmap);
 193
 194     /**
 195         Sets the brush style.
 196
 197         @param style
 198             One of the ::wxBrushStyle values.
 199
 200         @see GetStyle()
 201     */
 202     virtual void SetStyle(wxBrushStyle style);
 203
 204     /**
 205         Inequality operator.
 206         See @ref overview_refcount_equality for more info.
 207     */
 208     bool operator !=(const wxBrush& brush) const;
 209
 210     /**
 211         Equality operator.
 212         See @ref overview_refcount_equality for more info.
 213     */
 214     bool operator ==(const wxBrush& brush) const;
 215 };
 216
 217 /**
 218     An empty brush.
 219 */
 220 wxBrush wxNullBrush;
 221
 222 /**
 223     Blue brush.
 224 */
 225 wxBrush* wxBLUE_BRUSH;
 226
 227 /**
 228     Green brush.
 229 */
 230 wxBrush* wxGREEN_BRUSH;
 231
 232 /**
 233     White brush.
 234 */
 235 wxBrush* wxWHITE_BRUSH;
 236
 237 /**
 238     Black brush.
 239 */
 240 wxBrush* wxBLACK_BRUSH;
 241
 242 /**
 243     Grey brush.
 244 */
 245 wxBrush* wxGREY_BRUSH;
 246
 247 /**
 248     Medium grey brush.
 249 */
 250 wxBrush* wxMEDIUM_GREY_BRUSH;
 251
 252 /**
 253     Light grey brush.
 254 */
 255 wxBrush* wxLIGHT_GREY_BRUSH;
 256
 257 /**
 258     Transparent brush.
 259 */
 260 wxBrush* wxTRANSPARENT_BRUSH;
 261
 262 /**
 263     Cyan brush.
 264 */
 265 wxBrush* wxCYAN_BRUSH;
 266
 267 /**
 268     Red brush.
 269 */
 270 wxBrush* wxRED_BRUSH;
 271
 272
 273
 274 /**
 275     @class wxBrushList
 276
 277     A brush list is a list containing all brushes which have been created.
 278
 279     The application should not construct its own brush list: it should use the
 280     object pointer ::wxTheBrushList.
 281
 282     @library{wxcore}
 283     @category{gdi}
 284
 285     @see wxBrush
 286 */
 287 class wxBrushList : public wxList
 288 {
 289 public:
 290     /**
 291         Finds a brush with the specified attributes and returns it, else creates a new
 292         brush, adds it to the brush list, and returns it.
 293
 294         @param colour
 295             Colour object.
 296         @param style
 297             Brush style. See ::wxBrushStyle for a list of styles.
 298     */
 299     wxBrush* FindOrCreateBrush(const wxColour& colour,
 300                                wxBrushStyle style = wxBRUSHSTYLE_SOLID);
 301 };
 302
 303 /**
 304     The global wxBrushList instance.
 305 */
 306 wxBrushList* wxTheBrushList;