X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/c0cc7004a6ec1c53c0fd974898ef9ffd3739bef4..02e22828ebafb109d321370d75e2df95596b7a9a:/interface/pen.h?ds=sidebyside diff --git a/interface/pen.h b/interface/pen.h index 9a9a2833ac..02368092d5 100644 --- a/interface/pen.h +++ b/interface/pen.h @@ -1,224 +1,201 @@ ///////////////////////////////////////////////////////////////////////////// // Name: pen.h -// Purpose: interface of wxPen +// Purpose: interface of wxPen* classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// +/** + The possible styles for a wxPen. +*/ +enum wxPenStyle +{ + wxPENSTYLE_INVALID = -1, + + wxPENSTYLE_SOLID, + /**< Solid style. */ + + wxPENSTYLE_DOT, + /**< Dotted style. */ + + wxPENSTYLE_LONG_DASH, + /**< Long dashed style. */ + + wxPENSTYLE_SHORT_DASH, + /**< Short dashed style. */ + + wxPENSTYLE_DOT_DASH, + /**< Dot and dash style. */ + + wxPENSTYLE_USER_DASH, + /**< Use the user dashes: see wxPen::SetDashes. */ + + wxPENSTYLE_TRANSPARENT, + /**< No pen is used. */ + + wxPENSTYLE_STIPPLE_MASK_OPAQUE, + /**< @todo WHAT's this? */ + + wxPENSTYLE_STIPPLE_MASK, + /**< @todo WHAT's this? */ + + wxPENSTYLE_STIPPLE, + /**< Use the stipple bitmap. */ + + wxPENSTYLE_BDIAGONAL_HATCH, + /**< Backward diagonal hatch. */ + + wxPENSTYLE_CROSSDIAG_HATCH, + /**< Cross-diagonal hatch. */ + + wxPENSTYLE_FDIAGONAL_HATCH, + /**< Forward diagonal hatch. */ + + wxPENSTYLE_CROSS_HATCH, + /**< Cross hatch. */ + + wxPENSTYLE_HORIZONTAL_HATCH, + /**< Horizontal hatch. */ + + wxPENSTYLE_VERTICAL_HATCH, + /**< Vertical hatch. */ + + wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH, + wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH +}; + +/** + The possible join values of a wxPen. + + @todo use wxPENJOIN_ prefix +*/ +enum wxPenJoin +{ + wxJOIN_INVALID = -1, + + wxJOIN_BEVEL = 120, + wxJOIN_MITER, + wxJOIN_ROUND, +}; + + +/** + The possible cap values of a wxPen. + + @todo use wxPENCAP_ prefix +*/ +enum wxPenCap +{ + wxCAP_INVALID = -1, + + wxCAP_ROUND = 130, + wxCAP_PROJECTING, + wxCAP_BUTT +}; + + + /** @class wxPen @wxheader{pen.h} A pen is a drawing tool for drawing outlines. It is used for drawing - lines and painting the outline of rectangles, ellipses, etc. It has a - colour, a width and a style. + lines and painting the outline of rectangles, ellipses, etc. + It has a colour, a width and a style. + + @note On a monochrome display, wxWidgets shows all non-white pens as 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 dynamically create pens with different characteristics, + and there is the consequent danger that a large number of duplicate pens will + be created. Therefore an application may wish to get a pointer to a pen by using + the global list of pens ::wxThePenList, and calling the member function + wxPenList::FindOrCreatePen(). + See wxPenList for more info. + + This class uses @ref overview_refcount "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 - ::Objects:, ::wxNullPen, ::Pointers:, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, - ::wxBLACK_PEN, ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN, - - @see wxPenList, wxDC, wxDC::SetPen + @li ::wxNullPen + @li ::wxRED_PEN + @li ::wxCYAN_PEN + @li ::wxGREEN_PEN + @li ::wxBLACK_PEN + @li ::wxWHITE_PEN + @li ::wxTRANSPARENT_PEN + @li ::wxBLACK_DASHED_PEN + @li ::wxGREY_PEN + @li ::wxMEDIUM_GREY_PEN + @li ::wxLIGHT_GREY_PEN + + @see wxPenList, wxDC, wxDC::SetPen() */ class wxPen : public wxGDIObject { public: - //@{ /** - Copy constructor, uses @ref overview_trefcount "reference counting". - + Default constructor. The pen will be uninitialised, and IsOk() will return @false. + */ + wxPen(); + + /** + Constructs a pen from a colour object, pen width and style. + @param colour A colour object. - @param colourName - A colour name. @param width Pen width. Under Windows, the pen width cannot be greater than 1 if - the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH. - @param stipple - A stipple bitmap. - @param pen - A pointer or reference to a pen to copy. + the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH. @param style - The style may be one of the following: - - - - - - - wxSOLID - - - - - Solid style. - - - - - - wxTRANSPARENT - - - - - No pen is used. - - - - - - wxDOT - - - - - Dotted style. - - - - - - wxLONG_DASH - - - - - Long dashed style. - - - - - - wxSHORT_DASH - - - - - Short dashed style. - - - - - - wxDOT_DASH - - - - - Dot and dash style. - - - - - - wxSTIPPLE - - - - - Use the stipple bitmap. - - - - - - wxUSER_DASH - - - - - Use the user dashes: see SetDashes(). - - - - - - 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. - + The style may be one of the ::wxPenStyle values. + @remarks Different versions of Windows and different versions of other platforms support very different subsets of the styles above - there is no similarity even between Windows95 and Windows98 - so handle with care. - - @see SetStyle(), SetColour(), SetWidth(), SetStipple() + + @see SetStyle(), SetColour(), SetWidth() + */ + wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID); + + /** + Constructs a stippled pen from a stipple bitmap and a width. + + @param width + Pen width. Under Windows, the pen width cannot be greater than 1 if + the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH. + @param stipple + A stipple bitmap. + + @see SetWidth(), SetStipple() */ - wxPen(); - wxPen(const wxColour& colour, int width = 1, - int style = wxSOLID); - wxPen(const wxString& colourName, int width, int style); wxPen(const wxBitmap& stipple, int width); + + /** + Copy constructor, uses @ref overview_refcount. + + @param pen + A pointer or reference to a pen to copy. + */ wxPen(const wxPen& pen); - //@} /** Destructor. - See @ref overview_refcountdestruct "reference-counted object destruction" for - more info. - + @see @ref overview_refcount_destruct "reference-counted object destruction" + @remarks Although all remaining pens are deleted when the application exits, the application should try to clean up all pens itself. This is because wxWidgets cannot know if a @@ -228,60 +205,63 @@ public: ~wxPen(); /** - Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b - wxCAP_PROJECTING and - @b wxCAP_BUTT. The default is @b wxCAP_ROUND. - + Returns the pen cap style, which may be one of @c wxCAP_ROUND, @c + wxCAP_PROJECTING and @c wxCAP_BUTT. + + The default is @c wxCAP_ROUND. + @see SetCap() */ - int GetCap() const; + virtual wxPenCap GetCap() const; /** Returns a reference to the pen colour. - + @see SetColour() */ - wxColour GetColour() const; + virtual wxColour GetColour() const; /** Gets an array of dashes (defined as char in X, DWORD under Windows). @a dashes is a pointer to the internal array. Do not deallocate or store this pointer. - The function returns the number of dashes associated with this pen. - + + @return The number of dashes associated with this pen. + @see SetDashes() */ - int GetDashes(wxDash** dashes) const; + virtual int GetDashes(wxDash** dashes) const; /** - Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b - wxJOIN_ROUND and - @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. - + Returns the pen join style, which may be one of @c wxJOIN_BEVEL, @c + wxJOIN_ROUND and @c wxJOIN_MITER. + + The default is @c wxJOIN_ROUND. + @see SetJoin() */ - int GetJoin() const; + virtual wxPenJoin GetJoin() const; /** Gets a pointer to the stipple bitmap. - + @see SetStipple() */ - wxBitmap* GetStipple() const; + virtual wxBitmap* GetStipple() const; /** Returns the pen style. - + @see wxPen(), SetStyle() */ - int GetStyle() const; + virtual wxPenStyle GetStyle() const; /** Returns the pen width. - + @see SetWidth() */ - int GetWidth() const; + virtual int GetWidth() const; /** Returns @true if the pen is initialised. @@ -289,153 +269,211 @@ public: bool IsOk() const; /** - Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING - and - @b wxCAP_BUTT. The default is @b wxCAP_ROUND. - + Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING + and @c wxCAP_BUTT. The default is @c wxCAP_ROUND. + @see GetCap() */ - void SetCap(int capStyle); + virtual void SetCap(wxPenCap capStyle); //@{ /** The pen's colour is changed to the given colour. - + @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); //@} /** Associates an array of pointers to dashes (defined as char in X, DWORD under - Windows) - with the pen. The array is not deallocated by wxPen, but neither must it be - deallocated by the calling application until the pen is deleted or this - function is called with a @NULL array. - + Windows) with the pen. + + The array is not deallocated by wxPen, but neither must it be deallocated by + the calling application until the pen is deleted or this function is called + with a @NULL array. + @see GetDashes() */ - void SetDashes(int n, wxDash* dashes); + virtual void SetDashes(int n, wxDash* dashes); /** - Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND - and - @b wxJOIN_MITER. The default is @b wxJOIN_ROUND. - + Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND + and @c wxJOIN_MITER. + + The default is @c wxJOIN_ROUND. + @see GetJoin() */ - void SetJoin(int join_style); + virtual void SetJoin(wxPenJoin join_style); /** Sets the bitmap for stippling. - + @see GetStipple() */ - void SetStipple(wxBitmap* stipple); + virtual void SetStipple(wxBitmap* stipple); /** Set the pen style. - + @see wxPen() */ - void SetStyle(int style); + virtual void SetStyle(wxPenStyle style); /** Sets the pen width. - + @see GetWidth() */ - void SetWidth(int width); + virtual void SetWidth(int width); /** Inequality operator. - See @ref overview_refcountequality "reference-counted object comparison" for + + See @ref overview_refcount_equality "reference-counted object comparison" for more info. */ bool operator !=(const wxPen& pen); /** - Assignment operator, using @ref overview_trefcount "reference counting". + Assignment operator, using @ref overview_refcount. */ wxPen operator =(const wxPen& pen); /** Equality operator. - See @ref overview_refcountequality "reference-counted object comparison" for + + See @ref overview_refcount_equality "reference-counted object comparison" for more info. */ bool operator ==(const wxPen& pen); }; - /** - FIXME + An empty pen. */ -wxPen Objects: -; +wxPen wxNullPen; /** - FIXME + Red pen. */ -wxPen wxNullPen; +wxPen* wxRED_PEN; /** - FIXME + Cyan pen. */ -wxPen Pointers: -; +wxPen* wxCYAN_PEN; /** - FIXME + Green pen. */ -wxPen wxRED_PEN; +wxPen* wxGREEN_PEN; /** - FIXME + Black pen. */ -wxPen wxCYAN_PEN; +wxPen* wxBLACK_PEN; /** - FIXME + White pen. */ -wxPen wxGREEN_PEN; +wxPen* wxWHITE_PEN; /** - FIXME + Transparent pen. */ -wxPen wxBLACK_PEN; +wxPen* wxTRANSPARENT_PEN; /** - FIXME + Black dashed pen. */ -wxPen wxWHITE_PEN; +wxPen* wxBLACK_DASHED_PEN; /** - FIXME + Grey pen. */ -wxPen wxTRANSPARENT_PEN; +wxPen* wxGREY_PEN; /** - FIXME + Medium-grey pen. */ -wxPen wxBLACK_DASHED_PEN; +wxPen* wxMEDIUM_GREY_PEN; /** - FIXME + Light-grey pen. */ -wxPen wxGREY_PEN; +wxPen* wxLIGHT_GREY_PEN; + + /** - FIXME + @class wxPenList + @wxheader{gdicmn.h} + + There is only one instance of this class: ::wxThePenList. + Use this object to search for a previously created pen of the desired + type and create it if not already found. In some windowing systems, + the pen may be a scarce resource, so it can pay to reuse old + resources if possible. When an application finishes, all pens will + be deleted and their resources freed, eliminating the possibility of + 'memory leaks'. However, it is best not to rely on this automatic + cleanup because it can lead to double deletion in some circumstances. + + There are two mechanisms in recent versions of wxWidgets which make the + pen list less useful than it once was. Under Windows, scarce resources + are cleaned up internally if they are not being used. Also, a referencing + counting mechanism applied to all GDI objects means that some sharing + of underlying resources is possible. You don't have to keep track of pointers, + working out when it is safe delete a pen, because the referencing counting does + it for you. For example, you can set a pen in a device context, and then + immediately delete the pen you passed, because the pen is 'copied'. + + So you may find it easier to ignore the pen list, and instead create + and copy pens as you see fit. If your Windows resource meter suggests + your application is using too many resources, you can resort to using + GDI lists to share objects explicitly. + + The only compelling use for the pen list is for wxWidgets to keep + track of pens in order to clean them up on exit. It is also kept for + backward compatibility with earlier versions of wxWidgets. + + @library{wxcore} + @category{gdi} + + @stdobjects + ::wxThePenList + + @see wxPen */ -wxPen wxMEDIUM_GREY_PEN; +class wxPenList +{ +public: + /** + Constructor. The application should not construct its own pen list: + use the object pointer ::wxThePenList. + */ + wxPenList(); + + /** + Finds a pen with the specified attributes and returns it, else creates a + new pen, adds it to the pen list, and returns it. + + @param colour + Colour object. + @param width + Width of pen. + @param style + Pen style. See ::wxPenStyle for a list of styles. + */ + wxPen* FindOrCreatePen(const wxColour& colour, + int width = 1, + wxPenStyle style = wxPENSTYLE_SOLID); +}; /** - FIXME + The global list of wxPen objects ready to be re-used (for better performances). */ -wxPen wxLIGHT_GREY_PEN; - +wxPenList* wxThePenList;