wxpen

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

wxgdiobject
wxobject

include files

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.

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.

see also

wxpenlist, wxdc, wxdc::setpen

members

wxpen::wxpen
wxpen::~wxpen
wxpen::getcap
wxpen::getcolour
wxpen::getdashes
wxpen::getjoin
wxpen::getstipple
wxpen::getstyle
wxpen::getwidth
wxpen::isok
wxpen::setcap
wxpen::setcolour
wxpen::setdashes
wxpen::setjoin
wxpen::setstipple
wxpen::setstyle
wxpen::setwidth
wxpen::operator =
wxpen::operator ==
wxpen::operator !=

wxpen::wxpen

wxpen()

default constructor. the pen will be uninitialised, and wxpen:isok 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, uses reference counting.

parameters

colour

a colour object.

colourname

a colour name.

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.

pen

a pointer or reference to a pen to copy.

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.

wxperl note: constructors supported by wxperl are:

wx::pen->new( colour, width, style )
wx::pen->new( colourname, width, style )
wx::pen->new( stipple, width )

wxpen::~wxpen

~wxpen()

destructor. see reference-counted object destruction for more info.

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.

wxpen::getcap

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

wxpen::setcap

wxpen::getcolour

wxcolour& getcolour() const

returns a reference to the pen colour.

see also

wxpen::setcolour

wxpen::getdashes

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

wxpen::setdashes

wxpen::getjoin

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

wxpen::setjoin

wxpen::getstipple

wxbitmap* getstipple() const

gets a pointer to the stipple bitmap.

see also

wxpen::setstipple

wxpen::getstyle

int getstyle() const

returns the pen style.

see also

wxpen::wxpen, wxpen::setstyle

wxpen::getwidth

int getwidth() const

returns the pen width.

see also

wxpen::setwidth

wxpen::isok

bool isok() const

returns true if the pen is initialised.

wxpen::setcap

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

wxpen::getcap

wxpen::setcolour

void setcolour(wxcolour& colour)

void setcolour(const wxstring& colourname)

void setcolour(unsigned char red, unsigned char green, unsigned char blue)

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

see also

wxpen::getcolour

wxpen::setdashes

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

wxpen::getdashes