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