X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/brush.h diff --git a/interface/brush.h b/interface/brush.h index f4752aa3e7..f98b98525f 100644 --- a/interface/brush.h +++ b/interface/brush.h @@ -1,333 +1,308 @@ ///////////////////////////////////////////////////////////////////////////// // 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;