/////////////////////////////////////////////////////////////////////////////
// Name: brush.h
-// Purpose: documentation for wxBrush class
+// Purpose: interface of wxBrush
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
- @class wxBrush
- @wxheader{brush.h}
+ The possible brush styles.
+*/
+enum wxBrushStyle
+{
+ wxBRUSHSTYLE_INVALID = -1,
- A brush is a drawing tool for filling in areas. It is used for painting
- the background of rectangles, ellipses, etc. It has a colour and a
- style.
+ wxBRUSHSTYLE_SOLID = wxSOLID,
+ /**< Solid. */
- @library{wxcore}
- @category{gdi}
+ wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT,
+ /**< Transparent (no fill). */
- @stdobjects
- Objects:
- wxNullBrush
- Pointers:
- wxBLUE_BRUSH
+ wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
+ /**< @todo WHAT's THIS?? */
+
+ wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
+ /**< @todo WHAT's THIS?? */
- wxGREEN_BRUSH
+ wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
+ /**< Uses a bitmap as a stipple. */
- wxWHITE_BRUSH
+ wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
+ /**< Backward diagonal hatch. */
- wxBLACK_BRUSH
+ wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
+ /**< Cross-diagonal hatch. */
- wxGREY_BRUSH
+ wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
+ /**< Forward diagonal hatch. */
- wxMEDIUM_GREY_BRUSH
+ wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
+ /**< Cross hatch. */
- wxLIGHT_GREY_BRUSH
+ wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
+ /**< Horizontal hatch. */
- wxTRANSPARENT_BRUSH
+ wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
+ /**< Vertical hatch. */
+
+ wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
+ wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
+};
- wxCYAN_BRUSH
- wxRED_BRUSH
- @seealso
- wxBrushList, wxDC, wxDC::SetBrush
+/**
+ @class wxBrush
+ @wxheader{brush.h}
+
+ A brush is a drawing tool for filling in areas. It is used for painting
+ the background of rectangles, ellipses, etc. It has a colour and a style.
+
+ On a monochrome display, wxWidgets shows all brushes as white unless the
+ colour is really black.
+
+ Do not initialize objects on the stack before the program commences, since
+ other required structures may not have been set up yet. Instead, define
+ global pointers to objects and create them in wxApp::OnInit or when required.
+
+ An application may wish to create brushes with different characteristics
+ dynamically, and there is the consequent danger that a large number of
+ duplicate brushes will be created. Therefore an application may wish to
+ get a pointer to a brush by using the global list of brushes ::wxTheBrushList,
+ and calling the member function wxBrushList::FindOrCreateBrush().
+
+ This class uses reference counting and copy-on-write internally so that
+ assignments between two instances of this class are very cheap.
+ You can therefore use actual objects instead of pointers without efficiency problems.
+ If an instance of this class is changed it will create its own data internally
+ so that other instances, which previously shared the data using the reference
+ counting, are not affected.
+
+ @library{wxcore}
+ @category{gdi}
+
+ @stdobjects
+ ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH,
+ ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH,
+ ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH
+
+ @see wxBrushList, wxDC, wxDC::SetBrush
*/
class wxBrush : public wxGDIObject
{
public:
- //@{
/**
- Copy constructor, uses @ref overview_trefcount "reference counting".
-
+ Default constructor.
+ The brush will be uninitialised, and wxBrush:IsOk() will return @false.
+ */
+ wxBrush();
+
+ /**
+ Constructs a brush from a colour object and @a style.
+
@param colour
- Colour object.
-
- @param colourName
- Colour name. The name will be looked up in the colour database.
-
+ Colour object.
@param style
- One of:
-
- wxTRANSPARENT
-
-
- Transparent (no fill).
-
- wxSOLID
-
-
- Solid.
-
- wxSTIPPLE
-
-
- Uses a bitmap as a stipple.
-
- wxBDIAGONAL_HATCH
-
-
- Backward diagonal hatch.
-
- wxCROSSDIAG_HATCH
-
-
- Cross-diagonal hatch.
-
- wxFDIAGONAL_HATCH
-
-
- Forward diagonal hatch.
-
- wxCROSS_HATCH
-
-
- Cross hatch.
-
- wxHORIZONTAL_HATCH
-
-
- Horizontal hatch.
-
- wxVERTICAL_HATCH
-
-
- Vertical hatch.
-
- @param brush
- Pointer or reference to a brush to copy.
-
- @param stippleBitmap
- A bitmap to use for stippling.
-
- @remarks If a stipple brush is created, the brush style will be set to
- wxSTIPPLE.
-
- @sa wxBrushList, wxColour, wxColourDatabase
+ One of the ::wxBrushStyle enumeration values.
+ */
+ wxBrush(const wxColour& colour, wxBrushStyle style = wxBRUSHSTYLE_SOLID);
+
+ /**
+ Constructs a stippled brush using a bitmap.
+ The brush style will be set to wxBRUSHSTYLE_STIPPLE.
*/
- wxBrush();
- wxBrush(const wxColour& colour, int style = wxSOLID);
- wxBrush(const wxString& colourName, int style);
wxBrush(const wxBitmap& stippleBitmap);
+
+ /**
+ Copy constructor, uses @ref overview_refcount "reference counting".
+ */
wxBrush(const wxBrush& brush);
- //@}
/**
Destructor.
- See @ref overview_refcountdestruct "reference-counted object destruction" for
- more info.
-
+
+ See @ref overview_refcount_destruct for more info.
+
@remarks Although all remaining brushes are deleted when the application
- exits, the application should try to clean up all
- brushes itself. This is because wxWidgets cannot know
- if a pointer to the brush object is stored in an
- application data structure, and there is a risk of
- double deletion.
+ exits, the application should try to clean up all brushes itself.
+ This is because wxWidgets cannot know if a pointer to the brush
+ object is stored in an application data structure, and there is
+ a risk of double deletion.
*/
- ~wxBrush();
+ virtual ~wxBrush();
/**
Returns a reference to the brush colour.
-
- @sa SetColour()
+
+ @see SetColour()
*/
- wxColour GetColour();
+ virtual wxColour GetColour() const;
/**
- Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE
- style,
- this bitmap may be non-@NULL but uninitialised (@ref wxBitmap::isok
- wxBitmap:IsOk returns @false).
-
- @sa SetStipple()
+ Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
+ style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
+
+ @see SetStipple()
*/
- wxBitmap * GetStipple();
+ virtual wxBitmap* GetStipple() const;
/**
- Returns the brush style, one of:
-
- @b wxTRANSPARENT
-
-
- Transparent (no fill).
-
- @b wxSOLID
-
-
- Solid.
-
- @b wxBDIAGONAL_HATCH
-
-
- Backward diagonal hatch.
-
- @b wxCROSSDIAG_HATCH
-
-
- Cross-diagonal hatch.
-
- @b wxFDIAGONAL_HATCH
-
-
- Forward diagonal hatch.
-
- @b wxCROSS_HATCH
-
-
- Cross hatch.
-
- @b wxHORIZONTAL_HATCH
-
-
- Horizontal hatch.
-
- @b wxVERTICAL_HATCH
-
-
- Vertical hatch.
-
- @b wxSTIPPLE
-
-
- Stippled using a bitmap.
-
- @b wxSTIPPLE_MASK_OPAQUE
-
-
- Stippled using a bitmap's mask.
-
-
- @sa SetStyle(), SetColour(), SetStipple()
+ Returns the brush style, one of the ::wxBrushStyle values.
+
+ @see SetStyle(), SetColour(), SetStipple()
*/
- int GetStyle();
+ virtual wxBrushStyle GetStyle() const;
/**
Returns @true if the style of the brush is any of hatched fills.
-
- @sa GetStyle()
+
+ @see GetStyle()
*/
- bool IsHatch();
+ virtual bool IsHatch() const;
/**
Returns @true if the brush is initialised. It will return @false if the default
constructor has been used (for example, the brush is a member of a class, or
@NULL has been assigned to it).
*/
-#define bool IsOk() /* implementation is private */
+ bool IsOk() const;
//@{
/**
Sets the brush colour using red, green and blue values.
-
- @sa GetColour()
+
+ @see GetColour()
*/
- void SetColour(wxColour& colour);
- void SetColour(const wxString& colourName);
- void SetColour(unsigned char red, unsigned char green,
- unsigned char blue);
+ virtual void SetColour(wxColour& colour);
+ virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
//@}
/**
Sets the stipple bitmap.
-
+
@param bitmap
- The bitmap to use for stippling.
-
- @remarks The style will be set to wxSTIPPLE, unless the bitmap has a mask
- associated to it, in which case the style will be set
- to wxSTIPPLE_MASK_OPAQUE.
-
- @sa wxBitmap
+ The bitmap to use for stippling.
+
+ @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
+ has a mask associated to it, in which case the style will be set
+ to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
+
+ @see wxBitmap
*/
- void SetStipple(const wxBitmap& bitmap);
+ virtual void SetStipple(const wxBitmap& bitmap);
/**
Sets the brush style.
-
+
@param style
- One of:
-
- wxTRANSPARENT
-
-
- Transparent (no fill).
-
- wxSOLID
-
-
- Solid.
-
- wxBDIAGONAL_HATCH
-
-
- Backward diagonal hatch.
-
- wxCROSSDIAG_HATCH
-
-
- Cross-diagonal hatch.
-
- wxFDIAGONAL_HATCH
-
-
- Forward diagonal hatch.
-
- wxCROSS_HATCH
-
-
- Cross hatch.
-
- wxHORIZONTAL_HATCH
-
-
- Horizontal hatch.
-
- wxVERTICAL_HATCH
-
-
- Vertical hatch.
-
- wxSTIPPLE
-
-
- Stippled using a bitmap.
-
- wxSTIPPLE_MASK_OPAQUE
-
-
- Stippled using a bitmap's mask.
-
- @sa GetStyle()
+ One of the ::wxBrushStyle values.
+
+ @see GetStyle()
*/
- void SetStyle(int style);
+ virtual void SetStyle(wxBrushStyle style);
/**
Inequality operator.
- See @ref overview_refcountequality "reference-counted object comparison" for
- more info.
+ See @ref overview_refcount_equality for more info.
*/
- bool operator !=(const wxBrush& brush);
+ bool operator !=(const wxBrush& brush) const;
/**
- Assignment operator, using @ref overview_trefcount "reference counting".
+ Equality operator.
+ See @ref overview_refcount_equality for more info.
*/
- wxBrush operator =(const wxBrush& brush);
+ bool operator ==(const wxBrush& brush) const;
+};
+
+/**
+ An empty brush.
+*/
+wxBrush wxNullBrush;
+
+/**
+ Blue brush.
+*/
+wxBrush* wxBLUE_BRUSH;
+/**
+ Green brush.
+*/
+wxBrush* wxGREEN_BRUSH;
+
+/**
+ White brush.
+*/
+wxBrush* wxWHITE_BRUSH;
+
+/**
+ Black brush.
+*/
+wxBrush* wxBLACK_BRUSH;
+
+/**
+ Grey brush.
+*/
+wxBrush* wxGREY_BRUSH;
+
+/**
+ Medium grey brush.
+*/
+wxBrush* wxMEDIUM_GREY_BRUSH;
+
+/**
+ Light grey brush.
+*/
+wxBrush* wxLIGHT_GREY_BRUSH;
+
+/**
+ Transparent brush.
+*/
+wxBrush* wxTRANSPARENT_BRUSH;
+
+/**
+ Cyan brush.
+*/
+wxBrush* wxCYAN_BRUSH;
+
+/**
+ Red brush.
+*/
+wxBrush* wxRED_BRUSH;
+
+
+
+/**
+ @class wxBrushList
+ @wxheader{gdicmn.h}
+
+ A brush list is a list containing all brushes which have been created.
+
+ The application should not construct its own brush list: it should use the
+ object pointer ::wxTheBrushList.
+
+ @library{wxcore}
+ @category{gdi}
+
+ @see wxBrush
+*/
+class wxBrushList : public wxList
+{
+public:
/**
- Equality operator.
- See @ref overview_refcountequality "reference-counted object comparison" for
- more info.
+ Finds a brush with the specified attributes and returns it, else creates a new
+ brush, adds it to the brush list, and returns it.
+
+ @param colour
+ Colour object.
+ @param style
+ Brush style. See ::wxBrushStyle for a list of styles.
*/
- bool operator ==(const wxBrush& brush);
+ wxBrush* FindOrCreateBrush(const wxColour& colour,
+ wxBrushStyle style = wxBRUSHSTYLE_SOLID);
};
+
+/**
+ The global wxBrushList instance.
+*/
+wxBrushList* wxTheBrushList;
projects / wxWidgets.git / blobdiff