/////////////////////////////////////////////////////////////////////////////
// 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;
+