.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2018 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.Pen:

==========================================================================================================================================
|phoenix_title|  **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  :meth:`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 :ref:`wx.ThePenList`, and calling the member function :meth:`wx.PenList.FindOrCreatePen` . See :ref:`wx.PenList`  for more info. 

This class uses :ref:`reference counting and copy-on-write <reference counting>`  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.  







.. seealso:: :ref:`wx.PenList`, :ref:`wx.DC`, :meth:`wx.DC.SetPen`     







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>Pen</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.Pen_inheritance.png" alt="Inheritance diagram of Pen" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Pen.html" title="wx.Pen" alt="" coords="23,160,95,189"/> <area shape="rect" id="node2" href="wx.GDIObject.html" title="wx.GDIObject" alt="" coords="5,83,112,112"/> <area shape="rect" id="node3" href="wx.Object.html" title="wx.Object" alt="" coords="17,5,99,35"/> </map> 
   </p>

|


|method_summary| Methods Summary
================================

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


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.Pen.Cap`                                                              See :meth:`~wx.Pen.GetCap` and :meth:`~wx.Pen.SetCap`
:attr:`~wx.Pen.Colour`                                                           See :meth:`~wx.Pen.GetColour` and :meth:`~wx.Pen.SetColour`
:attr:`~wx.Pen.Dashes`                                                           See :meth:`~wx.Pen.GetDashes` and :meth:`~wx.Pen.SetDashes`
:attr:`~wx.Pen.Join`                                                             See :meth:`~wx.Pen.GetJoin` and :meth:`~wx.Pen.SetJoin`
:attr:`~wx.Pen.Stipple`                                                          See :meth:`~wx.Pen.GetStipple` and :meth:`~wx.Pen.SetStipple`
:attr:`~wx.Pen.Style`                                                            See :meth:`~wx.Pen.GetStyle` and :meth:`~wx.Pen.SetStyle`
:attr:`~wx.Pen.Width`                                                            See :meth:`~wx.Pen.GetWidth` and :meth:`~wx.Pen.SetWidth`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.Pen(GDIObject)

   **Possible constructors**::

       Pen()
       
       Pen(colour, width=1, style=PENSTYLE_SOLID)
       
       Pen(pen)
       
   
   A pen is a drawing tool for drawing outlines.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      **~~~**

      
      **__init__** `(self)`
      
      Default constructor.                  
      
      The pen will be uninitialised, and :meth:`IsOk`   will return ``False``.                   
      
      
      
      
      **~~~**

      
      **__init__** `(self, colour, width=1, style=PENSTYLE_SOLID)`
      
      Constructs a pen from a colour object, pen width and style.                  
      
      
      
      
      :param `colour`: A colour object.   
      :type `colour`: wx.Colour
      :param `width`: 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`` .    
      :type `width`: int
      :param `style`: The style may be one of the :ref:`wx.PenStyle`  values.  
      :type `style`: wx.PenStyle
      
      
      
      
      
      
      
      
                        
      
      
      
      .. 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. 
      
      
      
      
      
      
      
      
      
      
      .. seealso:: :meth:`SetStyle` , :meth:`SetColour` , :meth:`SetWidth`     
      
      
      
      
      
      
      
      **~~~**

      
      **__init__** `(self, pen)`
      
      Copy constructor, uses :ref:`Reference Counting <reference counting>`.                  
      
      
      
      
      :param `pen`: A pointer or reference to a pen to copy.   
      :type `pen`: wx.Pen
      
      
      
      
                        
      
      
      
      
      **~~~**






   .. method:: GetCap(self)

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

      The default is  ``CAP_ROUND`` . 

                

      :rtype: :ref:`wx.PenCap`







      .. seealso:: :meth:`SetCap`     








   .. method:: GetColour(self)

      Returns a reference to the pen colour.                  

                

      :rtype: :ref:`wx.Colour`







      .. seealso:: :meth:`SetColour`     








   .. method:: 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. 

                

      :rtype: `list of integers`







      :returns: 

         The number of dashes associated with this pen.  







      .. seealso:: :meth:`SetDashes`     








   .. method:: GetJoin(self)

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

      The default is  ``JOIN_ROUND`` . 

                

      :rtype: :ref:`wx.PenJoin`







      .. seealso:: :meth:`SetJoin`     








   .. method:: GetStipple(self)

      Gets a pointer to the stipple bitmap.                  

                

      :rtype: :ref:`wx.Bitmap`







      .. seealso:: :meth:`SetStipple`     








   .. method:: GetStyle(self)

      Returns the pen style.                  

                

      :rtype: :ref:`wx.PenStyle`







      .. seealso:: :ref:`wx.Pen`, :meth:`SetStyle`     








   .. method:: GetWidth(self)

      Returns the pen width.                  

                

      :rtype: `int`







      .. seealso:: :meth:`SetWidth`     








   .. method:: 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 :meth:`GetStyle`   returns a style different from ``wx.PENSTYLE_TRANSPARENT`` if the pen may be invalid as :meth:`GetStyle`   would assert in this case. 

                

      :rtype: `bool`







      .. versionadded:: 2.9.2.
      







      .. seealso:: :meth:`IsTransparent`   








   .. method:: 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.                  

      :rtype: `bool`








   .. method:: 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  :meth:`GetStyle`   == ``wx.PENSTYLE_TRANSPARENT``  which would assert if the pen is invalid. 

                

      :rtype: `bool`







      .. versionadded:: 2.9.2.
      







      .. seealso:: :meth:`IsNonTransparent`   








   .. method:: 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`` . 

                


      :param `capStyle`: 
      :type `capStyle`: wx.PenCap






      .. seealso:: :meth:`GetCap`     








   .. method:: SetColour(self, *args, **kw)

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

                 



      .. seealso:: :meth:`GetColour`     





      |overload| Overloaded Implementations:

      **~~~**

      
      **SetColour** `(self, colour)`
      
      
      
      
      :param `colour`: 
      :type `colour`: wx.Colour
      
      
      
      
      
      
      **~~~**

      
      **SetColour** `(self, red, green, blue)`
      
      
      
      
      :param `red`: 
      :type `red`: int
      :param `green`: 
      :type `green`: int
      :param `blue`: 
      :type `blue`: int
      
      
      
      
      
      
      **~~~**






   .. method:: 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 :ref:`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. 

                


      :param `dashes`: 
      :type `dashes`: list of integers






      .. seealso:: :meth:`GetDashes`     








   .. method:: 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`` . 

                


      :param `join_style`: 
      :type `join_style`: wx.PenJoin






      .. seealso:: :meth:`GetJoin`     








   .. method:: SetStipple(self, stipple)

      Sets the bitmap for stippling.                  

                


      :param `stipple`: 
      :type `stipple`: wx.Bitmap






      .. seealso:: :meth:`GetStipple`     








   .. method:: SetStyle(self, style)

      Set the pen style.                  

                


      :param `style`: 
      :type `style`: wx.PenStyle






      .. seealso:: :ref:`wx.Pen`    








   .. method:: SetWidth(self, width)

      Sets the pen width.                  

                


      :param `width`: 
      :type `width`: int






      .. seealso:: :meth:`GetWidth`     








   .. method:: _copyFrom(self, other)

      For internal use only.  





   .. method:: __ne__(self)

      Inequality operator.                  

      See :ref:`reference-counted object comparison <reference-counted object comparison>`  for more info.                  


      :param `pen`: 
      :type `pen`: wx.Pen







   .. method:: __eq__(self)

      Equality operator.                  

      See :ref:`reference-counted object comparison <reference-counted object comparison>`  for more info.                  


      :param `pen`: 
      :type `pen`: wx.Pen







   .. attribute:: Cap

      See :meth:`~wx.Pen.GetCap` and :meth:`~wx.Pen.SetCap`


   .. attribute:: Colour

      See :meth:`~wx.Pen.GetColour` and :meth:`~wx.Pen.SetColour`


   .. attribute:: Dashes

      See :meth:`~wx.Pen.GetDashes` and :meth:`~wx.Pen.SetDashes`


   .. attribute:: Join

      See :meth:`~wx.Pen.GetJoin` and :meth:`~wx.Pen.SetJoin`


   .. attribute:: Stipple

      See :meth:`~wx.Pen.GetStipple` and :meth:`~wx.Pen.SetStipple`


   .. attribute:: Style

      See :meth:`~wx.Pen.GetStyle` and :meth:`~wx.Pen.SetStyle`


   .. attribute:: Width

      See :meth:`~wx.Pen.GetWidth` and :meth:`~wx.Pen.SetWidth`