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