X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..d7c6d397381a8c3c7b873a9427ad1de12aa24781:/interface/pen.h diff --git a/interface/pen.h b/interface/pen.h index d6252a9831..02368092d5 100644 --- a/interface/pen.h +++ b/interface/pen.h @@ -1,313 +1,479 @@ ///////////////////////////////////////////////////////////////////////////// // Name: pen.h -// Purpose: documentation for wxPen class +// Purpose: interface of wxPen* classes // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// /** - @class wxPen - @wxheader{pen.h} + The possible styles for a wxPen. +*/ +enum wxPenStyle +{ + wxPENSTYLE_INVALID = -1, - 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. + wxPENSTYLE_SOLID, + /**< Solid style. */ - @library{wxcore} - @category{gdi} + wxPENSTYLE_DOT, + /**< Dotted style. */ - @stdobjects - Objects: - wxNullPen - Pointers: - wxRED_PEN + wxPENSTYLE_LONG_DASH, + /**< Long dashed style. */ + + wxPENSTYLE_SHORT_DASH, + /**< Short dashed style. */ + + wxPENSTYLE_DOT_DASH, + /**< Dot and dash style. */ - wxCYAN_PEN + wxPENSTYLE_USER_DASH, + /**< Use the user dashes: see wxPen::SetDashes. */ - wxGREEN_PEN + wxPENSTYLE_TRANSPARENT, + /**< No pen is used. */ - wxBLACK_PEN + wxPENSTYLE_STIPPLE_MASK_OPAQUE, + /**< @todo WHAT's this? */ - wxWHITE_PEN + wxPENSTYLE_STIPPLE_MASK, + /**< @todo WHAT's this? */ - wxTRANSPARENT_PEN + wxPENSTYLE_STIPPLE, + /**< Use the stipple bitmap. */ - wxBLACK_DASHED_PEN + 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. - wxGREY_PEN + @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} - wxMEDIUM_GREY_PEN + 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. + + @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. - wxLIGHT_GREY_PEN + @library{wxcore} + @category{gdi} - @seealso - wxPenList, wxDC, wxDC::SetPen + @stdobjects + @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. - + A colour object. @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. - + 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 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. - - @sa SetStyle(), SetColour(), SetWidth(), SetStipple() + 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() + */ + 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 pointer to the pen 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 pens + itself. This is because wxWidgets cannot know if a + pointer to the pen object is stored in an application + data structure, and there is a risk of double deletion. */ ~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. - - @sa SetCap() + 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(); + virtual wxPenCap GetCap() const; /** Returns a reference to the pen colour. - - @sa SetColour() + + @see SetColour() */ - wxColour GetColour(); + virtual wxColour GetColour() const; /** Gets an array of dashes (defined as char in X, DWORD under Windows). - @e dashes is a pointer to the internal array. Do not deallocate or store this + @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. - - @sa SetDashes() + + @return The number of dashes associated with this pen. + + @see SetDashes() */ - int GetDashes(wxDash** dashes); + 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. - - @sa SetJoin() + 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(); + virtual wxPenJoin GetJoin() const; /** Gets a pointer to the stipple bitmap. - - @sa SetStipple() + + @see SetStipple() */ - wxBitmap* GetStipple(); + virtual wxBitmap* GetStipple() const; /** Returns the pen style. - - @sa wxPen(), SetStyle() + + @see wxPen(), SetStyle() */ - int GetStyle(); + virtual wxPenStyle GetStyle() const; /** Returns the pen width. - - @sa SetWidth() + + @see SetWidth() */ - int GetWidth(); + virtual int GetWidth() const; /** Returns @true if the pen is initialised. */ -#define bool IsOk() /* implementation is private */ + 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. - - @sa GetCap() + 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. - - @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); //@} /** 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. - - @sa GetDashes() + 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. - - @sa GetJoin() + 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. - - @sa GetStipple() + + @see GetStipple() */ - void SetStipple(wxBitmap* stipple); + virtual void SetStipple(wxBitmap* stipple); /** Set the pen style. - - @sa wxPen() + + @see wxPen() */ - void SetStyle(int style); + virtual void SetStyle(wxPenStyle style); /** Sets the pen width. - - @sa GetWidth() + + @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); }; + +/** + An empty pen. +*/ +wxPen wxNullPen; + +/** + Red pen. +*/ +wxPen* wxRED_PEN; + +/** + Cyan pen. +*/ +wxPen* wxCYAN_PEN; + +/** + Green pen. +*/ +wxPen* wxGREEN_PEN; + +/** + Black pen. +*/ +wxPen* wxBLACK_PEN; + +/** + White pen. +*/ +wxPen* wxWHITE_PEN; + +/** + Transparent pen. +*/ +wxPen* wxTRANSPARENT_PEN; + +/** + Black dashed pen. +*/ +wxPen* wxBLACK_DASHED_PEN; + +/** + Grey pen. +*/ +wxPen* wxGREY_PEN; + +/** + Medium-grey pen. +*/ +wxPen* wxMEDIUM_GREY_PEN; + +/** + Light-grey pen. +*/ +wxPen* wxLIGHT_GREY_PEN; + + + +/** + @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 +*/ +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); +}; + +/** + The global list of wxPen objects ready to be re-used (for better performances). +*/ +wxPenList* wxThePenList; +