.. oe:namespace:: OEDepict

.. meta::
   :keywords: OEPen


.. _OEDepict_OEPen:

.. oe:class:: OEPen

   .. oe:api::

      class OEPen

   The :ref:`OEPen <OEDepict_OEPen>` class encapsulates properties that
   determine the way various lines, curves and shapes are drawn.

   Currently the :ref:`OEPen <OEDepict_OEPen>` class stores the following properties:

   .. list-table::
      :widths: 60 150 100 150
      :header-rows: 1

      * - Property
        - Get method
        - Set method
        - Corresponding namespace/class
      * - background color
        - :oe:meth:`OEDepict::OEPen::GetBackColor`
        - :oe:meth:`OEDepict::OEPen::SetBackColor`
        - :ref:`OEColor <OESystem_OEColor>`
      * - foreground color
        - :oe:meth:`OEDepict::OEPen::GetForeColor`
        - :oe:meth:`OEDepict::OEPen::SetForeColor`
        - :ref:`OEColor <OESystem_OEColor>`
      * - fill
        - :oe:meth:`OEDepict::OEPen::GetFill`
        - :oe:meth:`OEDepict::OEPen::SetFill`
        - :oe:constns:`OEDepict::OEFill`
      * - line join
        - :oe:meth:`OEDepict::OEPen::GetLineJoin`
        - :oe:meth:`OEDepict::OEPen::SetLineJoin`
        - :oe:constns:`OEDepict::OELineJoin`
      * - line cap
        - :oe:meth:`OEDepict::OEPen::GetLineCap`
        - :oe:meth:`OEDepict::OEPen::SetLineCap`
        - :oe:constns:`OEDepict::OELineCap`
      * - line width
        - :oe:meth:`OEDepict::OEPen::GetLineWidth`
        - :oe:meth:`OEDepict::OEPen::SetLineWidth`
        - none
      * - line stipple
        - :oe:meth:`OEDepict::OEPen::SetLineStipple`
        - :oe:meth:`OEDepict::OEPen::GetLineStipple`
        - :oe:constns:`OEDepict::OEStipple`
      * - stipple factor
        - :oe:meth:`OEDepict::OEPen::SetStippleFactor`
        - :oe:meth:`OEDepict::OEPen::GetStippleFactor`
        - none

   .. ################################################################
      # Constructors
      ################################################################

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEPen()

      .. oe:language:: python

         .. oe:api:: python

            OEPen() -> OEPen

      Default constructor that initializes an :ref:`OEPen <OEDepict_OEPen>`
      object with the following properties:

      .. list-table::  Default parameters of OEPen
         :widths: 100 100
         :header-rows: 1

         * - Property
           - Default value
         * - background color
           - :oe:const:`OEWhite<OESystem::OESystem::OEWhite>` = OEColor(255,255,255)
         * - foreground color
           - :oe:const:`OEBlack<OESystem::OESystem::OEBlack>` = OEColor(0,0,0)
         * - fill
           - :oe:const:`OEDepict::OEFill::Default`
         * - line join
           - :oe:const:`OEDepict::OELineJoin::Default`
         * - line cap
           - :oe:const:`OEDepict::OELineCap::Default`
         * - line width
           - 1.0
         * - line stipple
           - :oe:const:`OEDepict::OEStipple::Default`
         * - stipple factor
           - 1

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEPen(const OESystem::OEColor& bg, const OESystem::OEColor& fg,
                  unsigned int fill = OEFill::Off, double linewidth = 1.0,
                  unsigned short stipple = OEStipple::Solid)

      .. oe:language:: python

         .. oe:api:: python

            OEPen(bg: OEColor, fg: OEColor, fill: int, linewidth: float = 1.0,
                  stipple: short) -> OEPen

      Creates and initializes an :ref:`OEPen <OEDepict_OEPen>` object
      with the given parameters. The other properties of the pen
      are set to the default values (see table above).

      *bg, fg*
         The background and foreground color of the pen.

      *fill*
         The *fill* property of the pen.

      *linewidth*
          The *line width* property of the pen.

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEPen(const OEPen& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OEPen(arg2: OEPen) -> OEPen

      Copy constructor.


   .. ################################################################
      # operator=
      ################################################################

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEPen &operator=(const OEPen &rhs)

      Assignment operator.


   .. ################################################################
      #  operator!=
      ################################################################

   .. oe:method:: operator!=
      :language: c++

      .. oe:api::

         bool operator!=(const OEPen &) const

      Determines whether two :ref:`OEPen <OEDepict_OEPen>` objects are
      different.
      Two :ref:`OEPen <OEDepict_OEPen>` objects are considered different,
      if any of their properties (such as line width, background color,
      etc.) are different.


   .. ################################################################
      # operator==
      ################################################################

   .. oe:method:: operator==
      :language: c++

      .. oe:api::

         bool operator==(const OEPen &) const

      Determines whether two :ref:`OEPen <OEDepict_OEPen>` objects are
      equal.
      Two :ref:`OEPen <OEDepict_OEPen>` objects are considered equivalent
      only if all of their properties (such as line width, background
      color, etc.) are identical.


   .. ################################################################
      # GetBackColor
      ################################################################

   .. oe:method:: GetBackColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            const OESystem::OEColor& GetBackColor() const

      .. oe:language:: python

         .. oe:api:: python

            GetBackColor() -> OEColor

      Returns the background color of the :ref:`OEPen <OEDepict_OEPen>`
      object that is used to fill shapes.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetBackColor` method
         * :oe:meth:`OEDepict::OEPen::SetFill` method
         * :ref:`OEColor <OESystem_OEColor>` class


   .. ################################################################
      # GetFill
      ################################################################

   .. oe:method:: GetFill

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetFill() const

      .. oe:language:: python

         .. oe:api:: python

            GetFill() -> int

      If the returned value is :oe:const:`OEDepict::OEFill::On`, than
      shapes drawn with the :ref:`OEPen <OEDepict_OEPen>` object are filled with
      the background color of the pen.
      If the returned value is :oe:const:`OEDepict::OEFill::Off`, than
      shapes drawn with the :ref:`OEPen <OEDepict_OEPen>` object are left
      "empty" *i.e.* only their outlines are drawn using the
      foreground color of the pen.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetFill` method
         * :oe:meth:`OEDepict::OEPen::SetBackColor` method
         * :oe:constns:`OEDepict::OEFill` namespace


   .. ################################################################
      # GetForeColor
      ################################################################

   .. oe:method:: GetForeColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            const OESystem::OEColor& GetForeColor() const

      .. oe:language:: python

         .. oe:api:: python

            GetForeColor() -> OEColor

      Returns the foreground color of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls the color of the strokes when drawing lines,
      curves and outlines of shapes.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetForeColor` method
         * :ref:`OEColor <OESystem_OEColor>` class


   .. ################################################################
      # GetLineCap
      ################################################################

   .. oe:method:: GetLineCap

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetLineCap() const

      .. oe:language:: python

         .. oe:api:: python

            GetLineCap() -> int

      Returns the *line cap* property of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls how the endpoints of lines are drawn.
      The return value is taken from the :oe:constns:`OEDepict::OELineCap`
      namespace.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetLineCap` method
         * :oe:constns:`OEDepict::OELineCap` namespace


   .. ################################################################
      # GetLineJoin
      ################################################################

   .. oe:method:: GetLineJoin

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned int GetLineJoin() const

      .. oe:language:: python

         .. oe:api:: python

            GetLineJoin() -> int

      Returns the *line join* property of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls how lines connect at corners when drawing
      outlines.
      The return value is taken from the :oe:constns:`OEDepict::OELineJoin`
      namespace.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetLineJoin` method
         * :oe:constns:`OEDepict::OELineJoin` namespace


   .. ################################################################
      # GetLineStipple
      ################################################################

   .. oe:method:: GetLineStipple

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned short GetLineStipple() const

      .. oe:language:: python

         .. oe:api:: python

            GetLineStipple() -> short

      Returns the *line stipple* property of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls the pattern of dashes and gaps used to draw
      lines and outlines.
      The return value is taken from the :oe:constns:`OEDepict::OEStipple`
      namespace.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetLineStipple` method
         * :oe:meth:`OEDepict::OEPen::SetStippleFactor` method
         * :oe:constns:`OEDepict::OEStipple` namespace


   .. ################################################################
      # GetLineWidth
      ################################################################

   .. oe:method:: GetLineWidth

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetLineWidth() const

      .. oe:language:: python

         .. oe:api:: python

            GetLineWidth() -> float

      Returns the *line width* of the :ref:`OEPen <OEDepict_OEPen>` object
      that controls the width of strokes used when drawing lines, curves
      and outlines of shapes.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetLineWidth` method


   .. ################################################################
      # GetStippleFactor
      ################################################################

   .. oe:method:: GetStippleFactor

      .. oe:language:: c++ java csharp

         .. oe:api::

            unsigned short GetStippleFactor() const

      .. oe:language:: python

         .. oe:api:: python

            GetStippleFactor() -> short

      Returns the *stipple factor* of the :ref:`OEPen <OEDepict_OEPen>` object.
      The stipple factor is a multiplier that is used when drawing
      stipple patterns. For example, if the factor is three, then the
      stipple pattern is stretched to three times of its original size.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetStippleFactor` method
         * :oe:meth:`OEDepict::OEPen::SetLineStipple` method


   .. ################################################################
      # SetBackColor
      ################################################################

   .. oe:method:: SetBackColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetBackColor(const OESystem::OEColor& col)

      .. oe:language:: python

         .. oe:api:: python

            SetBackColor(col: OEColor) -> None

      Sets the background color of the :ref:`OEPen <OEDepict_OEPen>`
      object that is used to fill shapes.

      Example (:ref:`Figure: Example of using the SetBackColor method<figure_OEPen_SetBackColor>`)

      .. oe:source:: OEPen_SetProperties.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-BACKCOLOR

      .. oe:source:: OEPen_SetProperties.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-BACKCOLOR

      .. oe:source:: OEPen_SetProperties.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-BACKCOLOR

      .. oe:source:: OEPen_SetProperties.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-BACKCOLOR

      .. _figure_OEPen_SetBackColor:

      .. figure:: ../images/OEPen_SetBackColor.*
         :align:  center

         **Example of using the SetBackColor method**

      .. note::

         In order to fill a shape using the background color, the fill
         property of the :ref:`OEPen <OEDepict_OEPen>` has to be turned on
         (:oe:const:`OEDepict::OEFill::On`).
         (See :oe:meth:`OEDepict::OEPen::SetFill` method and
         :oe:constns:`OEDepict::OEFill` namespace)

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::GetBackColor` method
         * :oe:meth:`OEDepict::OEPen::GetFill` method
         * :ref:`OEColor <OESystem_OEColor>` class


   .. ################################################################
      # SetFill
      ################################################################

   .. oe:method:: SetFill

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetFill(unsigned int fill)

      .. oe:language:: python

         .. oe:api:: python

            SetFill(f: int) -> None

      Sets the *fill* property of the :ref:`OEPen <OEDepict_OEPen>` object.

      *fill*
         This value has to be from the :oe:constns:`OEDepict::OEFill`
         namespace.

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::GetFill` method
         * :oe:meth:`OEDepict::OEPen::GetBackColor` method
         * :oe:constns:`OEDepict::OEFill` namespace


   .. ################################################################
      # SetForeColor
      ################################################################

   .. oe:method:: SetForeColor

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetForeColor(const OESystem::OEColor& col)

      .. oe:language:: python

         .. oe:api:: python

            SetForeColor(col: OEColor) -> None

      Sets the foreground color of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls the color of the stroke when drawing lines,
      curves and outlines of shapes.

      Example (:ref:`Figure: Example of using the SetForeColor method<figure_OEPen_SetForeColor>`)

      .. oe:source:: OEPen_SetProperties.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-FORECOLOR

      .. oe:source:: OEPen_SetProperties.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-FORECOLOR

      .. oe:source:: OEPen_SetProperties.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-FORECOLOR

      .. oe:source:: OEPen_SetProperties.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-FORECOLOR

      .. _figure_OEPen_SetForeColor:

      .. figure:: ../images/OEPen_SetForeColor.*
         :align:  center

         **Example of using the SetForeColor method**

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::GetForeColor` method
         * :ref:`OEColor <OESystem_OEColor>` class


   .. ################################################################
      # SetLineCap
      ################################################################

   .. oe:method:: SetLineCap

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetLineCap(unsigned int cap)

      .. oe:language:: python

         .. oe:api:: python

            SetLineCap(cap: int) -> None

      Sets the *line cap* property of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls how the endpoints of lines are drawn.

      *cap*
         This value has to be from the :oe:constns:`OEDepict::OELineCap`
         namespace.

      Example (:ref:`Figure: Example of using the SetLineCap method<figure_OEPen_SetLineCap>`)

      .. oe:source:: OEPen_SetProperties.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINECAP

      .. oe:source:: OEPen_SetProperties.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINECAP

      .. oe:source:: OEPen_SetProperties.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINECAP

      .. oe:source:: OEPen_SetProperties.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINECAP

      .. _figure_OEPen_SetLineCap:

      .. figure:: ../images/OEPen_SetLineCap.*
         :align:  center

         **Example of using the SetLineCap method**

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::GetLineCap` method
         * :oe:constns:`OEDepict::OELineCap` namespace


   .. ################################################################
      # SetLineJoin
      ################################################################

   .. oe:method:: SetLineJoin

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetLineJoin(unsigned int join)

      .. oe:language:: python

         .. oe:api:: python

            SetLineJoin(join: int) -> None

      Sets the *line join* property of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls how lines connect at corners when drawing
      outlines.

      *join*
         This value has to be from the :oe:constns:`OEDepict::OELineJoin`
         namespace.

      Example (:ref:`Figure: Example of using the SetLineJoin method<figure_OEPen_SetLineJoin>`)

      .. oe:source:: OEPen_SetProperties.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINEJOIN

      .. oe:source:: OEPen_SetProperties.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINEJOIN

      .. oe:source:: OEPen_SetProperties.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINEJOIN

      .. oe:source:: OEPen_SetProperties.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINEJOIN

      .. _figure_OEPen_SetLineJoin:

      .. figure:: ../images/OEPen_SetLineJoin.*
         :align:  center

         **Example of using the SetLineJoin method**

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::GetLineJoin` method
         * :oe:constns:`OEDepict::OELineJoin` namespace


   .. ################################################################
      # SetLineStipple
      ################################################################

   .. oe:method:: SetLineStipple

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetLineStipple(unsigned short pattern)

      .. oe:language:: python

         .. oe:api:: python

            SetLineStipple(p: short) -> None

      Sets the *line stipple* property of the :ref:`OEPen <OEDepict_OEPen>`
      object that controls the pattern of dashes and gaps used to draw
      lines and outlines.

      *pattern*
         This value has to be from the :oe:constns:`OEDepict::OEStipple`
         namespace.

      Example (:ref:`Figure: Example of using the SetLineStipple method<figure_OEPen_SetLineStipple>`)

      .. oe:source:: OEPen_SetProperties.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-STIPPLE

      .. oe:source:: OEPen_SetProperties.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-STIPPLE

      .. oe:source:: OEPen_SetProperties.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-STIPPLE

      .. oe:source:: OEPen_SetProperties.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-STIPPLE

      .. _figure_OEPen_SetLineStipple:

      .. figure:: ../images/OEPen_SetLineStipple.*
         :align:  center

         **Example of using the SetLineStipple method**

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::SetLineStipple` method
         * :oe:meth:`OEDepict::OEPen::SetStippleFactor` method
         * :oe:constns:`OEDepict::OEStipple` namespace


   .. oe:method:: SetLineWidth

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetLineWidth(double width)

      .. oe:language:: python

         .. oe:api:: python

            SetLineWidth(w: float) -> None

      Sets the *line width* of the :ref:`OEPen <OEDepict_OEPen>` object
      that controls the width of strokes used when drawing lines, curves
      and outlines of shapes.

      *width*
         This value has to be a positive number.

      Example (:ref:`Figure: Example of using the SetLineWidth method<figure_OEPen_SetLineWidth>`)

      .. oe:source:: OEPen_SetProperties.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-WIDTH

      .. oe:source:: OEPen_SetProperties.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-WIDTH

      .. oe:source:: OEPen_SetProperties.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-WIDTH

      .. oe:source:: OEPen_SetProperties.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-LINE-WIDTH

      .. _figure_OEPen_SetLineWidth:

      .. figure:: ../images/OEPen_SetLineWidth.*
         :align:  center

         **Example of using the SetLineWidth method**

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::GetLineWidth` method


   .. oe:method:: SetStippleFactor

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetStippleFactor(unsigned short factor)

      .. oe:language:: python

         .. oe:api:: python

            SetStippleFactor(f: short) -> None

      Sets the *stipple factor* of the :ref:`OEPen <OEDepict_OEPen>` object.
      The stipple factor is a multiplier that is used when drawing
      stipple patterns.

      Example (:ref:`Figure: Example of using the SetStippleFactor method<figure_OEPen_SetStippleFactor>`)

      .. oe:source:: OEPen_SetProperties.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-STIPPLE-FACTOR

      .. oe:source:: OEPen_SetProperties.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-STIPPLE-FACTOR

      .. oe:source:: OEPen_SetProperties.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-STIPPLE-FACTOR

      .. oe:source:: OEPen_SetProperties.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEPEN-SET-STIPPLE-FACTOR

      .. _figure_OEPen_SetStippleFactor:

      .. figure:: ../images/OEPen_SetStippleFactor.*
         :align:  center

         **Example of using the SetStippleFactor method**

      .. seealso::

         * :oe:meth:`OEDepict::OEPen::GetStippleFactor` method
         * :oe:meth:`OEDepict::OEPen::GetLineStipple` method
