.. oe:namespace:: OEDepict


.. meta::
   :keywords: OE2DMolDisplay, 2DMolDisplay


.. _OEDepict_OE2DMolDisplay:

.. oe:class:: OE2DMolDisplay

   .. oe:api::

      class OE2DMolDisplay : public OEMolDisplayBase

   This class represents :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` that stores
   the depiction information (such as atom coordinates, molecule scaling,
   representation styles etc.) of a molecule.
   See :ref:`Figure: OEDepict TK molecule display class hierarchy<figure_OE2DMolDisplay_Hierarchy>`.

   .. _figure_OE2DMolDisplay_Hierarchy:

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

      **OEDepict TK molecule display class hierarchy**

   .. seealso::

      * :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` class
      * :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` class
      * :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` class

   The following methods are publicly inherited from :ref:`OEMolDisplayBase <OEDepict_OEMolDisplayBase>`:

   =============================================================== =============================================================== ==============================================================
   :oe:meth:`GetDataType<OEDepict::OEMolDisplayBase::GetDataType>` :oe:meth:`GetMolecule<OEDepict::OEMolDisplayBase::GetMolecule>` :oe:meth:`IsDataType<OEDepict::OEMolDisplayBase::IsDataType>`
   =============================================================== =============================================================== ==============================================================

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

   .. oe:method:: Constructors


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

         .. oe:api::

            OE2DMolDisplay(const OEChem::OEMolBase& mol)

      .. oe:language:: python

         .. oe:api:: python

            OE2DMolDisplay(arg2: Union[OEGraphMol,OEMol,OEQMol]) -> OE2DMolDisplay

      Initializes an :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object using
      default display options.

      *mol*
         The molecule for which display information is stored in the
         :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.

      .. seealso::

         * :oe:meth:`OEDepict::OE2DMolDisplayOptions::Constructors` method
           for the list of default display options
         * :oe:meth:`OEDepict::OE2DMolDisplay::IsValid` method

      .. ################################################################

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

         .. oe:api::

            OE2DMolDisplay(const OEChem::OEMolBase& mol,
                           const OE2DMolDisplayOptions& opts)

      .. oe:language:: python

         .. oe:api:: python

            OE2DMolDisplay(arg2: Union[OEGraphMol,OEMol,OEQMol],
                           arg3: OE2DMolDisplayOptions) -> OE2DMolDisplay

      Initializes an :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object using
      the given display options.

      *mol*
         The molecule for which display information is stored in the
         :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.

      *opts*
         The :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` object that stores
         properties that determine the styles of the molecule depiction.

      .. warning::

         * An :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object does not make a copy of the
           :ref:`OEMolBase <OEChem_OEMolBase>` object from which it is initialized but only stores
           its pointer.
           Therefore, the user responsibility is to not let the molecule
           go out of scope, before the corresponding :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>`
           object.

         * Changing the :ref:`OEMolBase <OEChem_OEMolBase>` object from which
           :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is initialized has no effect
           on the display itself after initialization.
           However, the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object become
           invalid if the molecule graph is modified (atoms or bonds added or
           deleted).

      .. note::

         * A warning is thrown when an :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object
           is initialized with a molecule with 3D coordinates.

         * An :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object is considered invalid
           and an error is thrown when it is initialized:

           * with an empty molecule (*i.e.* molecule with no atoms)

           * with a molecule that has neither 2D nor 3D coordinates

           See also: :oe:meth:`OEDepict::OE2DMolDisplay::IsValid` method


      .. ################################################################

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

         .. oe:api::

            OE2DMolDisplay(const OE2DMolDisplay& rhs)

      .. oe:language:: python

         .. oe:api:: python

            OE2DMolDisplay(rhs: OE2DMolDisplay) -> OE2DMolDisplay

      Copy constructor.


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

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

      .. oe:api::

         OE2DMolDisplay &operator=(const OE2DMolDisplay &rhs)

      Assignment operator.


   .. ################################################################
      # CreateCopy
      ################################################################

   .. 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 copy of the object. The
      memory for the returned :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object
      is dynamically allocated and owned by the caller.


   .. ################################################################
      # GetAtomDisplay
      ################################################################

   .. oe:method:: GetAtomDisplay

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

         .. oe:api::

            OE2DAtomDisplay* GetAtomDisplay(const OEChem::OEAtomBase* atom)

      .. oe:language:: python

         .. oe:api:: python

            GetAtomDisplay(atom: OEAtomBase) -> OE2DAtomDisplay

      Returns the pointer of the :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>`
      object that stores the depiction information of the given atom.

      .. ################################################################

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

         .. oe:api::

            const OE2DAtomDisplay* GetAtomDisplay(const OEChem::OEAtomBase* atom) const

      .. oe:language:: python

         .. oe:api:: python

            GetAtomDisplay(atom: OEAtomBase) -> OE2DAtomDisplay

      Returns the const pointer of the :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>`
      object that stores the depiction information of the given atom.

      .. note::

         The :oe:meth:`OEDepict::OE2DMolDisplay::GetAtomDisplay` methods
         returns a zero pointer if the given atom does not correspond to any
         display atom stored in the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.
         It is a good programming practice to check the returned pointer
         before using it. See code snippet below.

      .. oe:source:: AccessAtomDisplay.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAY

      .. oe:source:: AccessAtomDisplay.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAY

      .. oe:source:: AccessAtomDisplay.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAY

      .. oe:source:: AccessAtomDisplay.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAY

      .. seealso::

          * :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` class


   .. ################################################################
      # GetAtomDisplays
      ################################################################

   .. oe:method:: GetAtomDisplays

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

         .. oe:api::

            OESystem::OEIterBase<OE2DAtomDisplay>* GetAtomDisplays() const

      .. oe:language:: python

         .. oe:api:: python

            GetAtomDisplays() -> Iterable[OE2DAtomDisplay]

      Returns an iterator over all :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` objects
      stored in the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.


      .. ################################################################

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

         .. oe:api::

            OESystem::OEIterBase<OE2DAtomDisplay>* GetAtomDisplays(const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& pred) const

      .. oe:language:: python

         .. oe:api:: python

            GetAtomDisplays(pred: OEUnaryAtomPred) -> Iterable[OE2DAtomDisplay]

      Returns an iterator over only those  :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` objects
      for which the corresponding atom passes the given predicate.
      For example, the following code snippet shows how to access the atom
      displays of oxygen atoms:

      .. oe:source:: AccessAtomDisplay.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAYS-PREDICATE

      .. oe:source:: AccessAtomDisplay.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAYS-PREDICATE

      .. oe:source:: AccessAtomDisplay.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAYS-PREDICATE

      .. oe:source:: AccessAtomDisplay.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETATOMDISPLAYS-PREDICATE

      .. seealso::

          * :ref:`OE2DAtomDisplay <OEDepict_OE2DAtomDisplay>` class
          * :oe:src:`Listing 4<SNIPPET-DEPICT-MOL-GRAPH-DepictMolGraph>` example in the
            :ref:`section_mol_display_customize` section


   .. oe:method:: GetBondDisplay

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

         .. oe:api::

            OE2DBondDisplay* GetBondDisplay(const OEChem::OEBondBase* bond)

      .. oe:language:: python

         .. oe:api:: python

            GetBondDisplay(bond: OEBondBase) -> OE2DBondDisplay

      Returns the pointer of the :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>`
      object, that stores the depiction information of the given bond.

      .. ################################################################

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

         .. oe:api::

            const OE2DBondDisplay* GetBondDisplay(const OEChem::OEBondBase* bond) const

      .. oe:language:: python

         .. oe:api:: python

            GetBondDisplay(bond: OEBondBase) -> OE2DBondDisplay

      Returns the const pointer of the :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>`
      object, that stores the depiction information of the given bond.

      .. seealso::

          * :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` class

      .. note::

         The :oe:meth:`OEDepict::OE2DMolDisplay::GetBondDisplay` methods
         returns a zero pointer if the given bond does not correspond to any
         display bond stored in the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.
         It is a good programming practice to check the returned pointer
         before using it. See code snippet below.

      .. oe:source:: AccessBondDisplay.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAY

      .. oe:source:: AccessBondDisplay.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAY

      .. oe:source:: AccessBondDisplay.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAY

      .. oe:source:: AccessBondDisplay.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAY

      .. seealso::

          * :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` class


   .. ################################################################
      # GetBondDisplays
      ################################################################

   .. oe:method:: GetBondDisplays

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

         .. oe:api::

            OESystem::OEIterBase<OE2DBondDisplay>* GetBondDisplays() const

      .. oe:language:: python

         .. oe:api:: python

            GetBondDisplays() -> Iterable[OE2DBondDisplay]

      Returns an iterator over all :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` objects
      stored in the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object.

      .. ################################################################

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

         .. oe:api::

            OESystem::OEIterBase<OE2DBondDisplay>* GetBondDisplays(const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& pred) const

      .. oe:language:: python

         .. oe:api:: python

            GetBondDisplays(pred: OEUnaryBondPred) -> Iterable[OE2DBondDisplay]

      .. seealso::

          * :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` class

      Returns an iterator over only those :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` objects
      for which the corresponding bond passes the given predicate.
      For example, the following code snippet shows how to access the bond
      displays of aromatic bonds:

      .. oe:source:: AccessBondDisplay.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAYS-PREDICATE

      .. oe:source:: AccessBondDisplay.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAYS-PREDICATE

      .. oe:source:: AccessBondDisplay.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAYS-PREDICATE

      .. oe:source:: AccessBondDisplay.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OE2DMOLDISPLAY-GETBONDDISPLAYS-PREDICATE

      .. seealso::

          * :ref:`OE2DBondDisplay <OEDepict_OE2DBondDisplay>` class
          * :oe:src:`Listing 4<SNIPPET-DEPICT-MOL-GRAPH-DepictMolGraph>` example in the
            :ref:`section_mol_display_customize` section


   .. ################################################################
      # GetDataType
      ################################################################

   .. oe:method:: GetDataType

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

         .. oe:api::

            const void* GetDataType() const

      .. oe:language:: python

         .. oe:api:: python

            GetDataType() -> void

      This function is used to perform run-time type
      identification.

      .. seealso::

         * :oe:meth:`OESystem::OEBase::GetDataType` method in the **OEChem TK** manual


   .. ################################################################
      # GetHeight
      ################################################################

   .. oe:method:: GetHeight

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

         .. oe:api::

            double GetHeight() const

      .. oe:language:: python

         .. oe:api:: python

            GetHeight() -> float

      Returns the height of the displayed molecule.

      .. seealso::

          * :ref:`section_mol_display_size` section
          * :oe:meth:`OEDepict::OE2DMolDisplay::GetScale` method
          * :oe:meth:`OEDepict::OE2DMolDisplay::GetWidth` method


   .. ################################################################
      # GetLayer
      ################################################################

   .. oe:method:: GetLayer

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

         .. oe:api::

            OEImage& GetLayer(unsigned int position, unsigned int idx = 0)
            const OEImage& GetLayer(unsigned int position, unsigned int idx = 0) const

      .. oe:language:: python

         .. oe:api:: python

            GetLayer(position: int, idx: int = 0) -> OEImage

      Provides access to the layers of the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>`
      object.
      Currently, an :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object has two layers
      (one :oe:const:`OEDepict::OELayerPosition::Above` and
      one :oe:const:`OEDepict::OELayerPosition::Below` ) that allows
      drawing of objects over or underneath the molecular structure, respectively.

      *position*
         This value has to be from the :oe:constns:`OEDepict::OELayerPosition`
         namespace.

      *idx*
         This parameter is currently not used.

      .. seealso::

          * :ref:`OEImage <OEDepict_OEImage>` class
          * :oe:constns:`OEDepict::OELayerPosition` namespace


   .. ################################################################
      # GetOptions
      ################################################################

   .. oe:method:: GetOptions

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

         .. oe:api::

            const OE2DMolDisplayOptions& GetOptions() const

      .. oe:language:: python

         .. oe:api:: python

            GetOptions() -> OE2DMolDisplayOptions

      Returns the options used to initialized the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>`
      object.

      .. seealso::

          * :ref:`OE2DMolDisplayOptions <OEDepict_OE2DMolDisplayOptions>` class


   .. ################################################################
      # GetScale
      ################################################################

   .. oe:method:: GetScale

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

         .. oe:api::

            double GetScale() const

      .. oe:language:: python

         .. oe:api:: python

            GetScale() -> float

      Returns the scaling factor of the displayed molecule.

      .. seealso::

          * :ref:`section_mol_display_size` section
          * :oe:meth:`OEDepict::OE2DMolDisplay::GetHeight` method
          * :oe:meth:`OEDepict::OE2DMolDisplay::GetWidth` method


   .. ################################################################
      # GetWidth
      ################################################################

   .. oe:method:: GetWidth

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

         .. oe:api::

            double GetWidth() const

      .. oe:language:: python

         .. oe:api:: python

            GetWidth() -> float

      Returns the width of the displayed molecule.

      .. seealso::

          * :ref:`section_mol_display_size` section
          * :oe:meth:`OEDepict::OE2DMolDisplay::GetHeight` method
          * :oe:meth:`OEDepict::OE2DMolDisplay::GetScale` method


   .. ################################################################
      # IsDataType
      ################################################################

   .. oe:method:: IsDataType

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

         .. oe:api::

            bool IsDataType(const void *) const

      .. oe:language:: python

         .. oe:api:: python

            IsDataType(arg2: void) -> bool

      Returns whether type is the same as the instance this method is
      called on.

      .. seealso::

         * :oe:meth:`OESystem::OEBase::IsDataType` method in the **OEChem TK** manual

   .. ################################################################
      # IsValid
      ################################################################

   .. oe:method:: IsValid

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

         .. oe:api::

            bool IsValid() const

      .. oe:language:: python

         .. oe:api:: python

            IsValid() -> bool

      Returns whether the :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object
      was initialized successfully.  If initialization was attempted
      with an empty molecule or a molecule with no coordinates
      (neither 2D nor 3D), then this method returns false.
      An :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object becomes invalid
      if the molecule, from which it was initialized, is modified.
      For example, atom or bonds added to or deleted from the
      molecule.

      .. hint::

         It is highly recommend to check whether a molecule display
         is valid after initialization.
