wx.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.

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 wx.App.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 wx.ThePenList , and calling the member function wx.PenList.FindOrCreatePen . See wx.PenList 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.

Note

On a monochrome display, wxWidgets shows all non-white pens as black.

See also

wx.PenList, wx.DC, wx.DC.SetPen

Class Hierarchy¶

Inheritance diagram for class Pen:

Methods Summary¶

`__init__`	Default constructor.
`GetCap`	Returns the pen cap style, which may be one of `CAP_ROUND` , `CAP_PROJECTING` and `CAP_BUTT` .
`GetColour`	Returns a reference to the pen colour.
`GetDashes`	Gets an array of dashes (defined as `char` in X, `DWORD` under Windows).
`GetJoin`	Returns the pen join style, which may be one of `JOIN_BEVEL` , `JOIN_ROUND` and `JOIN_MITER` .
`GetQuality`	Returns the pen quality.
`GetStipple`	Gets a pointer to the stipple bitmap.
`GetStyle`	Returns the pen style.
`GetWidth`	Returns the pen width.
`IsNonTransparent`	Returns `True` if the pen is a valid non-transparent pen.
`IsOk`	Returns `True` if the pen is initialised.
`IsTransparent`	Returns `True` if the pen is transparent.
`SetCap`	Sets the pen cap style, which may be one of `CAP_ROUND` , `CAP_PROJECTING` and `CAP_BUTT` .
`SetColour`	The pen’s colour is changed to the given colour.
`SetDashes`	Associates an array of dash values (defined as `char` in X, `DWORD` under Windows) with the pen.
`SetJoin`	Sets the pen join style, which may be one of `JOIN_BEVEL` , `JOIN_ROUND` and `JOIN_MITER` .
`SetQuality`	Sets the pen quality.
`SetStipple`	Sets the bitmap for stippling.
`SetStyle`	Set the pen style.
`SetWidth`	Sets the pen width.
`_copyFrom`	For internal use only.
`__ne__`	Inequality operator.
`__eq__`	Equality operator.

Properties Summary¶

`Cap`	See `GetCap` and `SetCap`
`Colour`	See `GetColour` and `SetColour`
`Dashes`	See `GetDashes` and `SetDashes`
`Join`	See `GetJoin` and `SetJoin`
`Quality`	See `GetQuality` and `SetQuality`
`Stipple`	See `GetStipple` and `SetStipple`
`Style`	See `GetStyle` and `SetStyle`
`Width`	See `GetWidth` and `SetWidth`

Class API¶

class wx.Pen(GDIObject)¶

Possible constructors:

Pen()

Pen(info)

Pen(colour, width=1, style=PENSTYLE_SOLID)

Pen(pen)

A pen is a drawing tool for drawing outlines.

Methods¶

__init__(self, *args, **kw)¶

Overloaded Implementations:

__init__ (self)

Default constructor.

The pen will be uninitialised, and IsOk will return False.

__init__ (self, info)

Creates a pen object using the specified pen description.

Parameters: info (wx.PenInfo) –

__init__ (self, colour, width=1, style=PENSTYLE_SOLID)

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

Parameters

colour (wx.Colour) – A colour object.
width (int) – Pen width. Under Windows, the pen width cannot be greater than 1 if the style is PENSTYLE_DOT , PENSTYLE_LONG_DASH , PENSTYLE_SHORT_DASH , PENSTYLE_DOT_DASH , or PENSTYLE_USER_DASH .
style (PenStyle) – The style may be one of the wx.PenStyle values.

Note

Different versions of Windows and different versions of other platforms support very different subsets of the styles above so handle with care.

See also

SetStyle , SetColour , SetWidth

__init__ (self, pen)

Copy constructor, uses Reference Counting.

Parameters: pen (wx.Pen) – A pointer or reference to a pen to copy.

GetCap(self)¶

Returns the pen cap style, which may be one of CAP_ROUND , CAP_PROJECTING and CAP_BUTT .

The default is CAP_ROUND .

Return type: wx.PenCap

See also

SetCap

GetColour(self)¶

Returns a reference to the pen colour.

Return type: wx.Colour

See also

SetColour

GetDashes(self)¶

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.

Return type: list of integers
Returns: The number of dashes associated with this pen.

See also

SetDashes

GetJoin(self)¶

Returns the pen join style, which may be one of JOIN_BEVEL , JOIN_ROUND and JOIN_MITER .

The default is JOIN_ROUND .

Return type: wx.PenJoin

See also

SetJoin

GetQuality(self)¶

Returns the pen quality.

The default is PEN_QUALITY_DEFAULT.

Return type: wx.PenQuality

See also

wx.PenQuality, SetQuality

GetStipple(self)¶

Gets a pointer to the stipple bitmap.

Return type: wx.Bitmap

See also

SetStipple

GetStyle(self)¶

Returns the pen style.

Return type: wx.PenStyle

See also

wx.Pen, SetStyle

GetWidth(self)¶

Returns the pen width.

Return type: int

See also

SetWidth

IsNonTransparent(self)¶

Returns True if the pen is a valid non-transparent pen.

This method returns True if the pen object is initialized and has a non-transparent style. Notice that this should be used instead of simply testing whether GetStyle returns a style different from wx.PENSTYLE_TRANSPARENT if the pen may be invalid as GetStyle would assert in this case.

Return type: bool

New in version 2.9.2..

See also

IsTransparent

IsOk(self)¶

Returns True if the pen is initialised.

Notice that an uninitialized pen object can’t be queried for any pen properties and all calls to the accessor methods on it will result in an assert failure.

Return type: bool

IsTransparent(self)¶

Returns True if the pen is transparent.

A transparent pen is simply a pen with wx.PENSTYLE_TRANSPARENT style.

Notice that this function works even for non-initialized pens (for which it returns False) unlike tests of the form GetStyle == wx.PENSTYLE_TRANSPARENT which would assert if the pen is invalid.

Return type: bool

New in version 2.9.2..

See also

IsNonTransparent

SetCap(self, capStyle)¶

Sets the pen cap style, which may be one of CAP_ROUND , CAP_PROJECTING and CAP_BUTT .

The default is CAP_ROUND .

Parameters: capStyle (PenCap) –

See also

GetCap

SetColour(self, *args, **kw)¶

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

See also

GetColour

Overloaded Implementations:

SetColour (self, colour)

Parameters: colour (wx.Colour) –

SetColour (self, red, green, blue)

Parameters

red (int) –
green (int) –
blue (int) –

SetDashes(self, dashes)¶

Associates an array of dash values (defined as char in X, DWORD under Windows) with the pen.

The array is not deallocated by wx.Pen, but neither must it be deallocated by the calling application until the pen is deleted or this function is called with a None array.

Parameters: dashes (list of integers) –

See also

GetDashes

SetJoin(self, join_style)¶

Sets the pen join style, which may be one of JOIN_BEVEL , JOIN_ROUND and JOIN_MITER .

The default is JOIN_ROUND .

Parameters: join_style (PenJoin) –

See also

GetJoin

SetQuality(self, quality)¶

Sets the pen quality.

Explicitly selecting low pen quality may be useful in wxMSW if drawing performance is more important than the exact appearance of the lines drawn with this pen.