wxWidgets: wxPen Class Reference

| Version: 3.2.6

Public Member Functions | List of all members
wxPen Class Reference
Class List by Category » Graphics Device Interface (GDI)

`#include <wx/pen.h>`

Inheritance diagram for wxPen:
[legend]

## 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
- wxBLACK_DASHED_PEN
- wxBLACK_PEN
- wxBLUE_PEN
- wxCYAN_PEN
- wxGREEN_PEN
- wxYELLOW_PEN
- wxGREY_PEN
- wxLIGHT_GREY_PEN
- wxMEDIUM_GREY_PEN
- wxRED_PEN
- wxTRANSPARENT_PEN
- wxWHITE_PEN

See also
  wxPenList, wxDC, wxDC::SetPen()

## Public Member Functions
| wxPen ()
| Default constructor. More...
| wxPen (const wxPenInfo &info)
| Creates a pen object using the specified pen description. More...
| wxPen (const wxColour &colour, int width=1, wxPenStyle style=wxPENSTYLE_SOLID)
| Constructs a pen from a colour object, pen width and style. More...
| wxPen (const wxBitmap &stipple, int width)
| Constructs a stippled pen from a stipple bitmap and a width. More...
| wxPen (const wxPen &pen)
| Copy constructor, uses Reference Counting. More...
virtual | ~wxPen ()
| Destructor. More...
virtual wxPenCap | GetCap () const
| Returns the pen cap style, which may be one of `wxCAP_ROUND`, `wxCAP_PROJECTING` and `wxCAP_BUTT`. More...
wxPenQuality | GetQuality () const
| Returns the pen quality. More...
virtual wxColour | GetColour () const
| Returns a reference to the pen colour. More...
virtual int | GetDashes (wxDash **dashes) const
| Gets an array of dashes (defined as `char` in X, `DWORD` under Windows). More...
virtual wxPenJoin | GetJoin () const
| Returns the pen join style, which may be one of `wxJOIN_BEVEL`, `wxJOIN_ROUND` and `wxJOIN_MITER`. More...
virtual wxBitmap * | GetStipple () const
| Gets a pointer to the stipple bitmap. More...
virtual wxPenStyle | GetStyle () const
| Returns the pen style. More...
virtual int | GetWidth () const
| Returns the pen width. More...
virtual bool | IsOk () const
| Returns true if the pen is initialised. More...
bool | IsNonTransparent () const
| Returns true if the pen is a valid non-transparent pen. More...
bool | IsTransparent () const
| Returns true if the pen is transparent. More...
virtual void | SetCap (wxPenCap capStyle)
| Sets the pen cap style, which may be one of `wxCAP_ROUND`, `wxCAP_PROJECTING` and `wxCAP_BUTT`. More...
void | SetQuality (wxPenQuality quality)
| Sets the pen quality. More...
virtual void | SetDashes (int n, const wxDash *dash)
| Associates an array of dash values (defined as `char` in X, `DWORD` under Windows) with the pen. More...
virtual void | SetJoin (wxPenJoin join_style)
| Sets the pen join style, which may be one of `wxJOIN_BEVEL`, `wxJOIN_ROUND` and `wxJOIN_MITER`. More...
virtual void | SetStipple (const wxBitmap &stipple)
| Sets the bitmap for stippling. More...
virtual void | SetStyle (wxPenStyle style)
| Set the pen style. More...
virtual void | SetWidth (int width)
| Sets the pen width. More...
bool | operator!= (const wxPen &pen) const
| Inequality operator. More...
wxPen & | operator= (const wxPen &pen)
| Assignment operator, using Reference Counting. More...
bool | operator== (const wxPen &pen) const
| Equality operator. More...
virtual void | SetColour (wxColour &colour)
| The pen's colour is changed to the given colour. More...
virtual void | SetColour (unsigned char red, unsigned char green, unsigned char blue)
| The pen's colour is changed to the given colour. More...
Public Member Functions inherited from wxGDIObject
| wxGDIObject ()
| Default constructor. More...
Public Member Functions inherited from wxObject
| wxObject ()
| Default ctor; initializes to NULL the internal reference data. More...
| wxObject (const wxObject &other)
| Copy ctor. More...
virtual | ~wxObject ()
| Destructor. More...
virtual wxClassInfo * | GetClassInfo () const
| This virtual function is redefined for every class that requires run-time type information, when using the wxDECLARE_CLASS macro (or similar). More...
wxObjectRefData * | GetRefData () const
| Returns the wxObject::m_refData pointer, i.e. the data referenced by this object. More...
bool | IsKindOf (const wxClassInfo *info) const
| Determines whether this class is a subclass of (or the same class as) the given class. More...
bool | IsSameAs (const wxObject &obj) const
| Returns true if this object has the same data pointer as obj. More...
void | Ref (const wxObject &clone)
| Makes this object refer to the data in clone. More...
void | SetRefData (wxObjectRefData *data)
| Sets the wxObject::m_refData pointer. More...
void | UnRef ()
| Decrements the reference count in the associated data, and if it is zero, deletes the data. More...
void | UnShare ()
| This is the same of AllocExclusive() but this method is public. More...
void | operator delete (void *buf)
| The delete operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...
void * | operator new (size_t size, const wxString &filename=NULL, int lineNum=0)
| The new operator is defined for debugging versions of the library only, when the identifier `__WXDEBUG__` is defined. More...

## Additional Inherited Members
Protected Member Functions inherited from wxObject
void | AllocExclusive ()
| Ensure that this object's data is not shared with any other object. More...
virtual wxObjectRefData * | CreateRefData () const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and returns it. More...
virtual wxObjectRefData * | CloneRefData (const wxObjectRefData *data) const
| Creates a new instance of the wxObjectRefData-derived class specific to this object and initializes it copying data. More...
Protected Attributes inherited from wxObject
wxObjectRefData * | m_refData
| Pointer to an object which is the object's reference-counted data. More...

## Constructor & Destructor Documentation

## ◆ wxPen() [1/5]

wxPen::wxPen | ( |  | ) |

Default constructor.

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

## ◆ wxPen() [2/5]

wxPen::wxPen | ( | const wxPenInfo & | info | ) |

Creates a pen object using the specified pen description.

## ◆ wxPen() [3/5]

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 `wxPENSTYLE_DOT`, `wxPENSTYLE_LONG_DASH`, `wxPENSTYLE_SHORT_DASH`, `wxPENSTYLE_DOT_DASH`, or `wxPENSTYLE_USER_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 so handle with care.

See also
  SetStyle(), SetColour(), SetWidth()

## ◆ wxPen() [4/5]

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 `wxPENSTYLE_DOT`, `wxPENSTYLE_LONG_DASH`, `wxPENSTYLE_SHORT_DASH`, `wxPENSTYLE_DOT_DASH`, or `wxPENSTYLE_USER_DASH`.
  stipple | A stipple bitmap.

Availability: only available for the wxMSW, wxOSX/Cocoa ports.

See also
  SetWidth(), SetStipple()

## ◆ wxPen() [5/5]

wxPen::wxPen | ( | const wxPen & | pen | ) |

Copy constructor, uses Reference Counting.

Parameters

  pen | A pointer or reference to a pen to copy.

## ◆ ~wxPen()

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

## ◆ GetCap()

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()

## ◆ GetColour()

virtual wxColour wxPen::GetColour | ( |  | ) | const
| virtual

Returns a reference to the pen colour.

See also
  SetColour()

## ◆ GetDashes()

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()

## ◆ GetJoin()

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()

## ◆ GetQuality()

wxPenQuality wxPen::GetQuality | ( |  | ) | const

Returns the pen quality.

The default is wxPEN_QUALITY_DEFAULT.

See also
  wxPenQuality, SetQuality()

## ◆ GetStipple()

virtual wxBitmap* wxPen::GetStipple | ( |  | ) | const
| virtual

Gets a pointer to the stipple bitmap.

See also
  SetStipple()

## ◆ GetStyle()

virtual wxPenStyle wxPen::GetStyle | ( |  | ) | const
| virtual

Returns the pen style.

See also
  wxPen(), SetStyle()

## ◆ GetWidth()

virtual int wxPen::GetWidth | ( |  | ) | const
| virtual

Returns the pen width.

See also
  SetWidth()

## ◆ IsNonTransparent()

bool wxPen::IsNonTransparent | ( |  | ) | const

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 wxPENSTYLE_TRANSPARENT if the pen may be invalid as GetStyle() would assert in this case.

See also
  IsTransparent()

Since
  2.9.2.

## ◆ IsOk()

virtual bool wxPen::IsOk | ( |  | ) | const
| virtual

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.

## ◆ IsTransparent()

bool wxPen::IsTransparent | ( |  | ) | const

Returns true if the pen is transparent.

A transparent pen is simply a pen with wxPENSTYLE_TRANSPARENT style.

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

See also
  IsNonTransparent()

Since
  2.9.2.

## ◆ operator!=()

bool wxPen::operator!= | ( | const wxPen & | pen | ) | const

Inequality operator.

See reference-counted object comparison for more info.

## ◆ operator=()

wxPen& wxPen::operator= | ( | const wxPen & | pen | ) |

Assignment operator, using Reference Counting.

## ◆ operator==()

bool wxPen::operator== | ( | const wxPen & | pen | ) | const

Equality operator.

See reference-counted object comparison for more info.

## ◆ SetCap()

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()

## ◆ SetColour() [1/2]

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()

## ◆ SetColour() [2/2]

virtual void wxPen::SetColour | ( | wxColour & | colour | ) |
| virtual

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

See also
  GetColour()

## ◆ SetDashes()

virtual void wxPen::SetDashes | ( | int | n,
|  | const wxDash * | dash
| ) |  |
| virtual

Associates an array of dash values (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()

## ◆ SetJoin()

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()

## ◆ SetQuality()

void wxPen::SetQuality | ( | wxPenQuality | 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.

See also
  wxPenQuality

Since
  3.1.5

## ◆ SetStipple()

virtual void wxPen::SetStipple | ( | const wxBitmap & | stipple | ) |
| virtual

Sets the bitmap for stippling.

See also
  GetStipple()

## ◆ SetStyle()

virtual void wxPen::SetStyle | ( | wxPenStyle | style | ) |
| virtual

Set the pen style.

See also
  wxPen()

## ◆ SetWidth()

virtual void wxPen::SetWidth | ( | int | width | ) |
| virtual

Sets the pen width.

See also
  GetWidth()