Table Of Contents

Previous topic

PaperSize

Next topic

PenCap

This Page

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


class_hierarchy Inheritance Diagram

Inheritance diagram for class Pen

Inheritance diagram of Pen


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

api Class API



class Pen(GDIObject)

A pen is a drawing tool for drawing outlines.

Possible constructors:

Pen()

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

Pen(pen)

Methods



__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.

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



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

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

Parameters:
  • colour (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 PenStyle values.

Note

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



__init__ (self, pen)

Copy constructor, uses Reference Counting.

Parameters:pen (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: PenCap

See also

SetCap



GetColour(self)

Returns a reference to the pen colour.

Return type: 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: PenJoin

See also

SetJoin



GetStipple(self)

Gets a pointer to the stipple bitmap.

Return type: Bitmap

See also

SetStipple



GetStyle(self)

Returns the pen style.

Return type: PenStyle

See also

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 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 PENSTYLE_TRANSPARENT style.

Notice that this function works even for non-initialized pens (for which it returns False) unlike tests of the form GetStyle == 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


overload Overloaded Implementations:



SetColour (self, colour)

Parameters:colour (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 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



SetStipple(self, stipple)

Sets the bitmap for stippling.

Parameters:stipple (Bitmap) –

See also

GetStipple



SetStyle(self, style)

Set the pen style.

Parameters:style (PenStyle) –

See also

Pen



SetWidth(self, width)

Sets the pen width.

Parameters:width (int) –

See also

GetWidth



_copyFrom(self, other)

For internal use only.



__ne__(self)

Inequality operator.

See reference-counted object comparison for more info.

Parameters:pen (Pen) –


__eq__(self)

Equality operator.

See reference-counted object comparison for more info.

Parameters:pen (Pen) –

Properties



Cap

See GetCap and SetCap



Colour

See GetColour and SetColour



Dashes

See GetDashes and SetDashes



Join

See GetJoin and SetJoin



Stipple

See GetStipple and SetStipple



Style

See GetStyle and SetStyle



Width

See GetWidth and SetWidth