wxPen Class Reference
[Graphics Device Interface (GDI)]

#include <wx/pen.h>

Inheritance diagram for wxPen:

List of all members.

---

Detailed Description

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 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:  Graphics Device Interface (GDI)

Predefined objects/pointers:

• wxNullPen
• wxRED_PEN
• wxCYAN_PEN
• wxGREEN_PEN
• wxBLACK_PEN
• wxWHITE_PEN
• wxTRANSPARENT_PEN
• wxBLACK_DASHED_PEN
• wxGREY_PEN
• wxMEDIUM_GREY_PEN
• wxLIGHT_GREY_PEN

See also:

wxPenList, wxDC, wxDC::SetPen()

Public Member Functions
	wxPen ()
	wxPen (const wxColour &colour, int width=1, wxPenStyle style=wxPENSTYLE_SOLID)
	wxPen (const wxBitmap &stipple, int width)
	wxPen (const wxPen &pen)
virtual	~wxPen ()
virtual wxPenCap	GetCap () const
virtual wxColour	GetColour () const
virtual int	GetDashes (wxDash **dashes) const
virtual wxPenJoin	GetJoin () const
virtual wxBitmap *	GetStipple () const
virtual wxPenStyle	GetStyle () const
virtual int	GetWidth () const
bool	IsOk () const
virtual void	SetCap (wxPenCap capStyle)
virtual void	SetDashes (int n, wxDash *dashes)
virtual void	SetJoin (wxPenJoin join_style)
virtual void	SetStipple (wxBitmap *stipple)
virtual void	SetStyle (wxPenStyle style)
virtual void	SetWidth (int width)
bool	operator!= (const wxPen &pen)
wxPen	operator= (const wxPen &pen)
bool	operator== (const wxPen &pen)
virtual void	SetColour (wxColour &colour)
virtual void	SetColour (unsigned char red, unsigned char green, unsigned char blue)

---

Constructor & Destructor Documentation

wxPen::wxPen

(

)

Default constructor. The pen will be uninitialised, and IsOk() will return false.

wxPen::wxPen	(	const wxColour &	colour,
		int	width = 1,
		wxPenStyle	style = wxPENSTYLE_SOLID
	)

Constructs a pen from a colour object, pen width and style.

Parameters:

	colour	A colour object.
	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.
	style	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 also:

SetStyle(), SetColour(), SetWidth()

wxPen::wxPen	(	const wxBitmap &	stipple,
		int	width
	)

Constructs a stippled pen from a stipple bitmap and a width.

Parameters:

	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.
	stipple	A stipple bitmap.

See also:

SetWidth(), SetStipple()

wxPen::wxPen

(

const wxPen &

pen

)

Copy constructor, uses Reference Counting.

Parameters:

pen

A pointer or reference to a pen to copy.

virtual wxPen::~wxPen

(

)

[virtual]

Destructor.

See also:

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.

---

Member Function Documentation

virtual wxPenCap wxPen::GetCap

(

)

const [virtual]

Returns the pen cap style, which may be one of wxCAP_ROUND, wxCAP_PROJECTING and wxCAP_BUTT.

The default is wxCAP_ROUND.

See also:

SetCap()

virtual wxColour wxPen::GetColour

(

)

const [virtual]

Returns a reference to the pen colour.

See also:

SetColour()

virtual int wxPen::GetDashes

(

wxDash **

dashes

)

const [virtual]

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.

Returns:

The number of dashes associated with this pen.

See also:

SetDashes()

virtual wxPenJoin wxPen::GetJoin

(

)

const [virtual]

Returns the pen join style, which may be one of wxJOIN_BEVEL, wxJOIN_ROUND and wxJOIN_MITER.

The default is wxJOIN_ROUND.

See also:

SetJoin()

virtual wxBitmap* wxPen::GetStipple

(

)

const [virtual]

Gets a pointer to the stipple bitmap.

See also:

SetStipple()

virtual wxPenStyle wxPen::GetStyle

(

)

const [virtual]

Returns the pen style.

See also:

wxPen(), SetStyle()

virtual int wxPen::GetWidth

(

)

const [virtual]

Returns the pen width.

See also:

SetWidth()

bool wxPen::IsOk

(

)

const

Returns true if the pen is initialised.

virtual void wxPen::SetCap

(

wxPenCap

capStyle

)

[virtual]

Sets the pen cap style, which may be one of wxCAP_ROUND, wxCAP_PROJECTING and wxCAP_BUTT. The default is wxCAP_ROUND.

See also:

GetCap()

virtual void wxPen::SetColour

(

wxColour &

colour

)

[virtual]

The pen's colour is changed to the given colour.

See also:

GetColour()

virtual void wxPen::SetColour	(	unsigned char	red,
		unsigned char	green,
		unsigned char	blue
	)			[virtual]

The pen's colour is changed to the given colour.

See also:

GetColour()

virtual void wxPen::SetDashes	(	int	n,
		wxDash *	dashes
	)			[virtual]

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:

GetDashes()

virtual void wxPen::SetJoin

(

wxPenJoin

join_style

)

[virtual]

Sets the pen join style, which may be one of wxJOIN_BEVEL, wxJOIN_ROUND and wxJOIN_MITER.

The default is wxJOIN_ROUND.

See also:

GetJoin()

virtual void wxPen::SetStipple

(

wxBitmap *

stipple

)

[virtual]

Sets the bitmap for stippling.

See also:

GetStipple()

virtual void wxPen::SetStyle

(

wxPenStyle

style

)

[virtual]

Set the pen style.

See also:

wxPen()

virtual void wxPen::SetWidth

(

int

width

)

[virtual]

Sets the pen width.

See also:

GetWidth()

bool wxPen::operator!=

(

const wxPen &

pen

)

Inequality operator.

See reference-counted object comparison for more info.

wxPen wxPen::operator=

(

const wxPen &

pen

)

Assignment operator, using Reference Counting.

bool wxPen::operator==

(

const wxPen &

pen

)

Equality operator.

See reference-counted object comparison for more info.