.. oe:namespace:: OEDepict



.. meta::
   :keywords: OE2DAtomDisplay, 2DAtomDisplay


.. _OEDepict_OE2DAtomDisplay:

.. oe:class:: OE2DAtomDisplay

   .. oe:api::

      class OE2DAtomDisplay : public OEAtomDisplayBase

   This class stores 2D depiction information of an atom.
   See :ref:`Figure: OEDepict TK atom display class hierarchy<figure_OE2DAtomDisplay_Hierarchy>`.

   .. _figure_OE2DAtomDisplay_Hierarchy:

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

      **OEDepict TK atom display class hierarchy**


   The following figure
   (:ref:`Figure: Example of the layout of an atom<figure_OE2DAtomDisplay_Layout>`)
   illustrates how atoms are rendered in the **OEDepict TK**.

   * The atom label is positioned at the coordinates returned by the
     :oe:meth:`OEDepict::OE2DAtomDisplay::GetCoords` method.
     The string that is rendered as an atom label is returned by the
     :oe:meth:`OEDepict::OE2DAtomDisplay::GetLabel` method.

   * If the atom has a charge, then it is rendered as a super-script
     on the right side of the atomic label.

     .. seealso::

        * :oe:meth:`OEDepict::OE2DAtomDisplay::GetCharge` method

   * If the atom has isotope information, then it is rendered as a super-script
     on the left side of the atomic label.

     .. seealso::

        * :oe:meth:`OEDepict::OE2DAtomDisplay::GetMass` method

   * If the atom has implicit hydrogen(s), then the *hydrogen label*
     is positioned in a cardinal direction relative to
     the *atomic label*.
     The number of implicit hydrogens and the position can be accessed
     by calling the :oe:meth:`OEDepict::OE2DAtomDisplay::GetHCount`
     and the :oe:meth:`OEDepict::OE2DAtomDisplay::GetHPosition` methods,
     respectively.

     .. seealso::

        * :oe:constns:`OEDepict::OEHydrogenStyle` namespace
        * :oe:constns:`OEDepict::OEHydrogenPos` namespace

   * All labels (isotope, atomic, charge and explicit hydrogen) has the
     same color that is associated with the atomic number.

     .. seealso::

        * :oe:constns:`OEDepict::OEAtomColorStyle` namespace
        * :ref:`chapter_element_color` chapter


   .. _figure_OE2DAtomDisplay_Layout:

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

      **Example of the layout of an atom**


   The following methods are publicly inherited from :ref:`OEAtomDisplayBase <OEDepict_OEAtomDisplayBase>`:

   ================================================================ =============================================================== ===============================================================
   :oe:meth:`GetDataType<OEDepict::OEAtomDisplayBase::GetDataType>` :oe:meth:`IsDataType<OEDepict::OEAtomDisplayBase::IsDataType>`  :oe:meth:`SetVisible<OEDepict::OEAtomDisplayBase::SetVisible>`
   :oe:meth:`GetAtom<OEDepict::OEAtomDisplayBase::GetAtom>`         :oe:meth:`IsVisible<OEDepict::OEAtomDisplayBase::IsVisible>`
   ================================================================ =============================================================== ===============================================================

   The :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` class stores the following properties:

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

      * - Property
        - Get method
        - Set method
        - Corresponding namespace / class / type

      * - rendered formal charge
        - :oe:meth:`GetCharge<OEDepict::OE2DAtomDisplay::GetCharge>`
        - :oe:meth:`SetCharge<OEDepict::OE2DAtomDisplay::SetCharge>`
        - integer

      * - position of the atom label
        - :oe:meth:`GetCoords<OEDepict::OE2DAtomDisplay::GetCoords>`
        - :oe:meth:`SetCoords<OEDepict::OE2DAtomDisplay::SetCoords>`
        - :ref:`OE2DPoint <OEDepict_OE2DPoint>` class

      * - hydrogen count
        - :oe:meth:`GetHCount<OEDepict::OE2DAtomDisplay::GetHCount>`
        - :oe:meth:`SetHCount<OEDepict::OE2DAtomDisplay::SetHCount>`
        - unsigned int

      * - position of hydrogen label
        - :oe:meth:`GetHPosition<OEDepict::OE2DAtomDisplay::GetHPosition>`
        - :oe:meth:`SetHPosition<OEDepict::OE2DAtomDisplay::SetHPosition>`
        - :oe:constns:`OEDepict::OEHydrogenPos` namespace

      * - rendered atom label
        - :oe:meth:`GetLabel<OEDepict::OE2DAtomDisplay::GetLabel>`
        - :oe:meth:`SetLabel<OEDepict::OE2DAtomDisplay::SetLabel>`
        - string

      * - font of atom label
        - :oe:meth:`GetLabelFont<OEDepict::OE2DAtomDisplay::GetLabelFont>`
        - :oe:meth:`SetLabelFont<OEDepict::OE2DAtomDisplay::SetLabelFont>`
        - :ref:`OEFont <OEDepict_OEFont>` class

      * - rendered isotope number
        - :oe:meth:`GetMass<OEDepict::OE2DAtomDisplay::GetMass>`
        - :oe:meth:`SetMass<OEDepict::OE2DAtomDisplay::SetMass>`
        - integer

      * - rendered string as property
        - :oe:meth:`GetProperty<OEDepict::OE2DAtomDisplay::GetProperty>`
        - :oe:meth:`SetProperty<OEDepict::OE2DAtomDisplay::SetProperty>`
        - string

      * - font of property string
        - :oe:meth:`GetPropertyFont<OEDepict::OE2DAtomDisplay::GetPropertyFont>`
        - :oe:meth:`SetPropertyFont<OEDepict::OE2DAtomDisplay::SetPropertyFont>`
        - :ref:`OEFont <OEDepict_OEFont>` class

      * - position of property label
        - :oe:meth:`GetPropertyOffset<OEDepict::OE2DAtomDisplay::GetPropertyOffset>`
        - :oe:meth:`SetPropertyOffset<OEDepict::OE2DAtomDisplay::SetPropertyOffset>`
        - :ref:`OE2DPoint <OEDepict_OE2DPoint>` class

      * - rendered radical type
        - :oe:meth:`GetRadical<OEDepict::OE2DAtomDisplay::GetRadical>`
        - :oe:meth:`SetRadical<OEDepict::OE2DAtomDisplay::SetRadical>`
        - :oe:constns:`OEDepict::OERadicalDisplayType` namespace


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

   .. oe:method:: Constructors

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

         .. oe:api::

            OE2DAtomDisplay(const OEChem::OEAtomBase* atom)

      .. oe:language:: python

         .. oe:api:: python

            OE2DAtomDisplay(arg2: OEAtomBase) -> OE2DAtomDisplay

      Construct an :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` object that
      contains the style information for ``atom``.

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

         .. oe:api::

            OE2DAtomDisplay(const OE2DAtomDisplay& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OE2DAtomDisplay(rhs: OE2DAtomDisplay) -> OE2DAtomDisplay

      Copy constructor.

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

      .. oe:api::

         OE2DAtomDisplay &operator=(const OE2DAtomDisplay &rhs)

      Assignment operator.

   .. oe:method:: CreateCopy

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

         .. oe:api::

            OESystem::OEBase* CreateCopy() const

      .. oe:language:: python

         .. oe:api:: python

            CreateCopy() -> OEBase

      Deep copy constructor that returns a pointer to a copy of the
      object.  The memory returned is dynamically allocated and owned
      by the caller.

   .. oe:method:: GetCharge

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

         .. oe:api::

            int GetCharge() const

      .. oe:language:: python

         .. oe:api:: python

            GetCharge() -> int

      Returns the charge rendered next to the atomic label.
      See example in :ref:`Figure: Example of charge representation<figure_OE2DAtomDisplay_GetCharge>`.
      The number will be rendered in the following ways:

      :0: nothing is rendered
      :-1: negative sign "-" is rendered
      :1: positive sign "+" is rendered
      :less than -1: "-<n>" is rendered
      :greater than 1: "+<n>" is rendered

      .. _figure_OE2DAtomDisplay_GetCharge:

      .. figure:: ../images/OE2DAtomDisplay-GetCharge.*
         :align:  center

         **Example of charge representation**

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetCharge` method

   .. oe:method:: GetCoords

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

         .. oe:api::

            const OE2DPoint& GetCoords() const

      .. oe:language:: python

         .. oe:api:: python

            GetCoords() -> OE2DPoint


      Returns the coordinates of the atom in the coordinate system that
      is defined when a :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is
      constructed with a specific width and height. This is the
      exact location of the atom when it is rendered into an image.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetCoords` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` method

   .. oe:method:: GetHCount

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

         .. oe:api::

            unsigned int GetHCount() const

      .. oe:language:: python

         .. oe:api:: python

            GetHCount() -> int

      Returns the hydrogen count to render for this atom.
      See example in :ref:`Figure: Example of hydrogen count representation<figure_OE2DAtomDisplay_GetHCount>`.
      The number will be rendered in the following ways:

      :0: no "H" label is rendered
      :1: "H" is rendered next to the atomic label
      :greater than 1: this number is rendered as a
        sub-script of the "H" label

      .. _figure_OE2DAtomDisplay_GetHCount:

      .. figure:: ../images/OE2DAtomDisplay-GetHCount.*
         :align:  center

         **Example of hydrogen count representation**

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetHCount` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetHPosition` method

   .. oe:method:: GetHPosition

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

         .. oe:api::

            unsigned int GetHPosition() const

      .. oe:language:: python

         .. oe:api:: python

            GetHPosition() -> int

      Returns the position of the hydrogen label relative to the
      atomic label.  The return value is taken from the
      :oe:constns:`OEDepict::OEHydrogenPos` namespace.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetHPosition` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetHCount` method
         * :oe:constns:`OEDepict::OEHydrogenPos` namespace

   .. oe:method:: GetLabel

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

         .. oe:api::

            const std::string& GetLabel() const

      .. oe:language:: python

         .. oe:api:: python

            GetLabel() -> str

      Returns the string that is rendered as the atomic label at the
      coordinates returned by the
      :oe:meth:`OEDepict::OE2DAtomDisplay::GetCoords` method.
      The color of the font is set by the

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetLabel` method

   .. oe:method:: GetLabelFont

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

         .. oe:api::

            const OEFont& GetLabelFont() const

      .. oe:language:: python

         .. oe:api:: python

            GetLabelFont() -> OEFont

      Returns the font that is used when rendering the atomic label
      string of the :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` object.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetLabelFont` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetLabel` method
         * :ref:`OEFont <OEDepict_OEFont>` class

   .. oe:method:: GetMass

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

         .. oe:api::

            unsigned int GetMass() const

      .. oe:language:: python

         .. oe:api:: python

            GetMass() -> int

      Returns the isotope information rendered as a super-script next
      to the atomic label. If zero, nothing is rendered.
      See example in :ref:`Figure: Example of isotope representation<figure_OE2DAtomDisplay_GetMass>`.

      .. _figure_OE2DAtomDisplay_GetMass:

      .. figure:: ../images/OE2DAtomDisplay-GetMass.*
         :align:  center

         **Example of isotope representation**

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetMass` method

   .. oe:method: GetPen # IGNORE CURRENTLY NOT USED

      .. oe:api::

         const OEPen &GetPen() const

   .. oe:method:: GetProperty

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

         .. oe:api::

            const std::string& GetProperty() const

      .. oe:language:: python

         .. oe:api:: python

            GetProperty() -> str

      Returns the string rendered next to the atom. If the string is
      empty, nothing is rendered.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetProperty` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetPropertyFont` method

   .. oe:method:: GetPropertyFont

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

         .. oe:api::

            const OEFont& GetPropertyFont() const

      .. oe:language:: python

         .. oe:api:: python

            GetPropertyFont() -> OEFont

      Returns the font that is used when rendering the property string of the
      :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` object.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetPropertyFont` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetProperty` method
         * :ref:`OEFont <OEDepict_OEFont>` class

   .. oe:method:: GetPropertyOffset

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

         .. oe:api::

            const OE2DPoint& GetPropertyOffset() const

      .. oe:language:: python

         .. oe:api:: python

            GetPropertyOffset() -> OE2DPoint

      Returns the offset vector relative to the coordinates returned
      by :oe:meth:`OEDepict::OE2DAtomDisplay::GetCoords` that is used
      to position the property label of the atom. These vectors are
      calculated during :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` construction
      to minimize potentially clashing with the rest of the
      depiction.
      See :ref:`Figure: The property offset vector is relative to coordinates returned by
      the GetCoords method<figure_OE2DAtomDisplay_GetPropertyOffset>`.

      .. _figure_OE2DAtomDisplay_GetPropertyOffset:

      .. figure:: ../images/OE2DAtomDisplay-GetPropertyOffset.*
         :align:  center

         **The property offset vector is relative to coordinates returned by
         the OE2DAtomDisplay::GetCoords method**

      This allows for any string representable information to be
      rendered at a logical location near the atom.
      See example in :ref:`Example of indices as an atom property<figure_OE2DAtomDisplay_GetProperty>`.

      .. _figure_OE2DAtomDisplay_GetProperty:

      .. figure:: ../images/OE2DAtomDisplay-GetProperty.*
         :align:  center

         **Example of indices as an atom property**

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetPropertyOffset` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class

   .. oe:method:: GetRadical

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

         .. oe:api::

            unsigned int GetRadical() const

      .. oe:language:: python

         .. oe:api:: python

            GetRadical() -> int

      Returns the radical display type of the atom.  The return value
      is taken from the :oe:constns:`OEDepict::OERadicalDisplayType`
      namespace.
      See example in :ref:`Example of rendering radicals<figure_OE2DAtomDisplay_GetRadical>`.

      .. _figure_OE2DAtomDisplay_GetRadical:

      .. figure:: ../images/OE2DAtomDisplay-GetRadical.*
         :align:  center

         **Example of rendering radicals**

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetRadical` method
         * :oe:constns:`OEDepict::OERadicalDisplayType` namespace

   .. oe:method:: HasLabel

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

         .. oe:api::

            bool HasLabel() const

      .. oe:language:: python

         .. oe:api:: python

            HasLabel() -> bool

      Returns whether or not the atomic label string of the
      :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` object is empty.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetLabel` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetLabel` method

   .. oe:method:: HasProperty

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

         .. oe:api::

            bool HasProperty() const

      .. oe:language:: python

         .. oe:api:: python

            HasProperty() -> bool

      Returns whether or not the property string of the
      :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` object is empty.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetProperty` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetProperty` method

   .. oe:method:: SetCharge

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

         .. oe:api::

            void SetCharge(int charge)

      .. oe:language:: python

         .. oe:api:: python

            SetCharge(charge: int) -> None

      Sets the charge rendered next to the atomic label.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetCharge` method

   .. oe:method:: SetCoords

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

         .. oe:api::

            void SetCoords(const OE2DPoint& coords)

      .. oe:language:: python

         .. oe:api:: python

            SetCoords(coord: OE2DPoint) -> None

      Sets the exact coordinates of the atom in the rendered image.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetCoords` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` method

   .. oe:method:: SetHCount

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

         .. oe:api::

            void SetHCount(unsigned int hcount)

      .. oe:language:: python

         .. oe:api:: python

            SetHCount(hcount: int) -> None

      Set the hydrogen count to render for this atom.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetHCount` method for
           more information on the meaning of various input integers.

   .. oe:method:: SetHPosition

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

         .. oe:api::

            void SetHPosition(unsigned int hpos)

      .. oe:language:: python

         .. oe:api:: python

            SetHPosition(hpos: int) -> None

      Sets the position of hydrogen label relative to the atomic
      label.

      *hpos*
         This value has to be from the :oe:constns:`OEDepict::OEHydrogenPos`
         namespace.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetHPosition` method
         * :oe:constns:`OEDepict::OEHydrogenPos` namespace

   .. oe:method:: SetLabel

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

         .. oe:api::

            void SetLabel(const std::string& label)

      .. oe:language:: python

         .. oe:api:: python

            SetLabel(label: str) -> None

      Sets the string that is rendered as the "atomic" label at the position
      returned by the :oe:meth:`OEDepict::OE2DAtomDisplay::GetCoords`
      method.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetLabel` method

   .. oe:method:: SetLabelFont

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

         .. oe:api::

            void SetLabelFont(const OEFont& font)

      .. oe:language:: python

         .. oe:api:: python

            SetLabelFont(font: OEFont) -> None

      Sets the font that is used when rendering the atomic label of the
      :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` object.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetLabelFont` method

   .. oe:method:: SetMass

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

         .. oe:api::

            void SetMass(unsigned int mass)

      .. oe:language:: python

         .. oe:api:: python

            SetMass(mass: int) -> None

      Sets the isotope information rendered next to the atomic label.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetMass` method

   .. oe:method: SetPen  # IGNORE CURRENTLY NOT USED

      .. oe:api::

         void SetPen(const OEPen &pen)

   .. oe:method:: SetProperty

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

         .. oe:api::

            void SetProperty(const std::string& label)

      .. oe:language:: python

         .. oe:api:: python

            SetProperty(label: str) -> None

      Sets the string rendered next to the atom.

      .. warning::

         The preferred way to set the atom property strings is to use the
         :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomPropertyFunctor`
         method.
         See example in the :ref:`section_mol_display_atom_prop`
         section.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetProperty` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::SetPropertyFont` method
         * :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomPropertyFunctor` method

   .. oe:method:: SetPropertyFont

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

         .. oe:api::

            void SetPropertyFont(const OEFont& font)

      .. oe:language:: python

         .. oe:api:: python

            SetPropertyFont(font: OEFont) -> None

      Sets the font that is used when rendering the property string of the
      :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` object.

      .. warning::

         The preferred way to set the font of the atom property strings
         is to use the :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomPropLabelFont`
         method.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetPropertyFont` method
         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetProperty` method
         * :ref:`OEFont <OEDepict_OEFont>` class
         * :oe:meth:`OEDepict::OE2DMolDisplayOptions::SetAtomPropLabelFont` method

   .. oe:method:: SetPropertyOffset

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

         .. oe:api::

            void SetPropertyOffset(const OE2DPoint& offset)

      .. oe:language:: python

         .. oe:api:: python

            SetPropertyOffset(offset: OE2DPoint) -> None

      Sets the offset vector that is used to position the property label
      of the atom.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetPropertyOffset` method
         * :ref:`OE2DPoint <OEDepict_OE2DPoint>` class

   .. oe:method:: SetRadical

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

         .. oe:api::

            void  SetRadical(unsigned int radical)

      .. oe:language:: python

         .. oe:api:: python

            SetRadical(radical: int) -> None

      Sets the radical type of the atom.

      *radical*
         This value has to be from the :oe:constns:`OEDepict::OERadicalDisplayType`
         namespace.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DAtomDisplay::GetRadical` method
         * :oe:constns:`OEDepict::OERadicalDisplayType` namespace
