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.
Derived from
Include files
<wx/pen.h>
Predefined objects
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
Remarks
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 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 FindOrCreatePen. See the entry for wxPenList.
wxPen uses a reference counting system, so assignments between brushes are very cheap. You can therefore use actual wxPen objects instead of pointers without efficiency problems. Once one wxPen object changes its data it will create its own pen data internally so that other pens, which previously shared the data using the reference counting, are not affected.
See also
Members
wxPen::wxPen
wxPen::~wxPen
wxPen::GetCap
wxPen::GetColour
wxPen::GetDashes
wxPen::GetJoin
wxPen::GetStipple
wxPen::GetStyle
wxPen::GetWidth
wxPen::Ok
wxPen::SetCap
wxPen::SetColour
wxPen::SetDashes
wxPen::SetJoin
wxPen::SetStipple
wxPen::SetStyle
wxPen::SetWidth
wxPen::operator =
wxPen::operator ==
wxPen::operator !=
wxPen()
Default constructor. The pen will be uninitialised, and wxPen::Ok will return false.
wxPen(const wxColour& colour, int width = 1, int style = wxSOLID)
Constructs a pen from a colour object, pen width and style.
wxPen(const wxString& colourName, int width, int style)
Constructs a pen from a colour name, pen width and style.
wxPen(const wxBitmap& stipple, int width)
Constructs a stippled pen from a stipple bitmap and a width.
wxPen(const wxPen& pen)
Copy constructor. This uses reference counting so is a cheap operation.
Parameters
colour
colourName
width
stipple
pen
style
| 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 wxPen::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. |
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.
If the named colour form is used, an appropriate wxColour structure is found in the colour database.
See also
wxPen::SetStyle, wxPen::SetColour, wxPen::SetWidth, wxPen::SetStipple
wxPerl note: Constructors supported by wxPerl are:
~wxPen()
Destructor.
Remarks
The destructor may not delete the underlying pen object of the native windowing system, since wxBrush uses a reference counting system for efficiency.
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.
int GetCap() const
Returns the pen cap style, which may be one of wxCAP_ROUND, wxCAP_PROJECTING and wxCAP_BUTT. The default is wxCAP_ROUND.
See also
wxColour& GetColour() const
Returns a reference to the pen colour.
See also
int GetDashes(wxDash** dashes) const
Gets an array of dashes (defined as char in X, DWORD under Windows). 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.
See also
int GetJoin() const
Returns the pen join style, which may be one of wxJOIN_BEVEL, wxJOIN_ROUND and wxJOIN_MITER. The default is wxJOIN_ROUND.
See also
wxBitmap* GetStipple() const
Gets a pointer to the stipple bitmap.
See also
int GetStyle() const
Returns the pen style.
See also
int GetWidth() const
Returns the pen width.
See also
bool Ok() const
Returns true if the pen is initialised.
void SetCap(int capStyle)
Sets the pen cap style, which may be one of wxCAP_ROUND, wxCAP_PROJECTING and wxCAP_BUTT. The default is wxCAP_ROUND.
See also
void SetColour(wxColour& colour)
void SetColour(const wxString& colourName)
void SetColour(int red, int green, int blue)
The pen's colour is changed to the given colour.
See also
void SetDashes(int n, wxDash* dashes)
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.
See also
void SetJoin(int join_style)
Sets the pen join style, which may be one of wxJOIN_BEVEL, wxJOIN_ROUND and wxJOIN_MITER. The default is wxJOIN_ROUND.
See also
void SetStipple(wxBitmap* stipple)
Sets the bitmap for stippling.
See also
void SetStyle(int style)
Set the pen style.
See also
void SetWidth(int width)
Sets the pen width.
See also
wxPen& operator =(const wxPen& pen)
Assignment operator, using reference counting. Returns a reference to 'this'.
bool operator ==(const wxPen& pen)
Equality operator. Two pens are equal if they contain pointers to the same underlying pen data. It does not compare each attribute, so two independently-created pens using the same parameters will fail the test.
bool operator !=(const wxPen& pen)
Inequality operator. Two pens are not equal if they contain pointers to different underlying pen data. It does not compare each attribute.