.. include:: ../substitutions

.. oe:namespace:: OEDepict

.. meta::
   :keywords: OEAddHighlighting

.. _OEDepict_OEAddHighlighting:


.. oe:function:: OEAddHighlighting


   Highlights atoms and/or bonds of the displayed molecule.

   .. list-table:: **The overloaded versions of the OEAddHighlighting function using OEHighlightBase**
      :widths: 100 200
      :header-rows: 1

      * - Link
        - Description

      * - :ref:`OEAddHighlighting(disp, highlight, atompred)<api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_AtomPred>`
        - highlights atoms with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddHighlighting(disp, highlight, bondpred)<api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_BondPred>`
        - highlights bonds  with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddHighlighting(disp, highlight, atompred, bondpred)<api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_AtomAndBondPred>`
        - highlights atoms and bonds  with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddHighlighting(disp, highlight, match)<api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_OEMatchBase>`
        - highlights atoms and bonds of a match  with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddHighlighting(disp, highlight, abset)<api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_OEAtomBondSet>`
        - highlights atoms and bonds of a set with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddHighlighting(disp, highlight, subsearch)<api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_OESubSearch>`
        - highlights atoms and bonds of substructure matches :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`

   .. list-table:: **The overloaded versions of the OEAddHighlighting function using color and style**
      :widths: 100 200
      :header-rows: 1

      * - Link
        - Description

      * - :ref:`OEAddHighlighting(disp, color, style, atompred)<api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_AtomPred>`
        - highlights atoms with color and style
      * - :ref:`OEAddHighlighting(disp, color, style, bondpred)<api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_BondPred>`
        - highlights bonds with color and style
      * - :ref:`OEAddHighlighting(disp, color, style, atompred, bondpred)<api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_AtomAndBondPred>`
        - highlights atoms and bonds with color and style
      * - :ref:`OEAddHighlighting(disp, color, style, match)<api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_OEMatchBase>`
        - highlights atoms and bonds of a match with color and style
      * - :ref:`OEAddHighlighting(disp, color, style, abset)<api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_OEAtomBondSet>`
        - highlights atoms and bonds of a set with color and style
      * - :ref:`OEAddHighlighting(disp, color, style, subsearch)<api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_OESubSearch>`
        - highlights atoms and bonds of substructure matches

   **Parameters :**

   *disp*
      The :ref:`OE2DMolDisplay <OEDepict_OE2DMolDisplay>` object of which atoms
      add/or bonds being highlighted.

   *highlight*
      The :ref:`OEHighlightBase <OEDepict_OEHighlightBase>` object that specifies the style of the highlighting.

   *color*
      The :ref:`OEColor <OESystem_OEColor>` object that specifies the color of the highlighting.

   *style*
      The style of the highlighting from the
      :oe:constns:`OEDepict::OEHighlightStyle` namespace.

   *atompred*
      :oe:func:`OEDepict::OEAddHighlighting` function highlights
      only atoms for which the given atom predicate returns `true`.

   *bondpred*
      :oe:func:`OEDepict::OEAddHighlighting` function highlights
      only bonds for which the given bond predicate returns `true`.

   *match*
      :oe:func:`OEDepict::OEAddHighlighting` function highlights the
      target atoms and bonds of the :ref:`OEMatchBase <OEChem_OEMatchBase>` object.

   *abset*
      Stores the atoms and bonds being highlighted.

   *subsearch*
      The substructure search object of the matches being highlighted.


   **Highlights atom and/or bonds with the style implemented in the given**
   :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`  **object**

   The atoms and bonds being highlighted can be specified either
   by a predicate or an :ref:`OEMatchBase <OEChem_OEMatchBase>` object or an
   :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` object.

   The following code snippets show different ways to highlight any 6
   membered aromatic ring in a molecule using the
   :ref:`OEHighlightByBallAndStick <OEDepict_OEHighlightByBallAndStick>` highlighting class.
   They all generate the image shown in
   :ref:`Figure: Example of highlighting 6-membered aromatic rings
   <figure_OEAddHighlighting_OEHighlightBase>`.


   #. Highlighting using **atom** and **bond predicates**:

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_AtomPred:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OEHighlightBase& highlight,
                                const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& atompred)

      Highlights atoms with the style implemented in the given :ref:`OEHighlightBase <OEDepict_OEHighlightBase>` object.
      The atoms being highlighted are specified by given atom predicate.

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_BondPred:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OEHighlightBase& highlight,
                                const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& bondpred)

      Highlights bonds with the style implemented in the given :ref:`OEHighlightBase <OEDepict_OEHighlightBase>` object.
      The bonds being highlighted are specified by given bond predicates.

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_AtomAndBondPred:

      .. oe:api::

          void OEAddHighlighting(OE2DMolDisplay& disp,
                                 const OEHighlightBase& highlight,
                                 const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& atompred,
                                 const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& bondpred)

      Highlights atoms and bonds with the style implemented in the given :ref:`OEHighlightBase <OEDepict_OEHighlightBase>` object.
      The atoms and bonds being highlighted are specified by given atom and bond predicates, respectively.

      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightBase`)

      .. oe:source:: OEAddHighlighting_Base.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE

      .. oe:source:: OEAddHighlighting_Base.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE

      .. oe:source:: OEAddHighlighting_Base.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE

      .. oe:source:: OEAddHighlighting_Base.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE


   #. Highlighting using an :ref:`OEMatchBase <OEChem_OEMatchBase>` object that is
      initialized by substructure search or maximum common substructure search:

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_OEMatchBase:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OEHighlightBase& highlight,
                                const OEChem::OEMatchBase& match)

      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightBase`)

      .. oe:source:: OEAddHighlighting_Base.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH

      .. oe:source:: OEAddHighlighting_Base.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH

      .. oe:source:: OEAddHighlighting_Base.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH

      .. oe:source:: OEAddHighlighting_Base.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH

   #. Highlighting using an :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` object that stores
      the atoms and bonds being highlighted:

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_OEAtomBondSet:

      .. oe:api::

          void OEAddHighlighting(OE2DMolDisplay& disp,
                                 const OEHighlightBase& highlight,
                                 const OEChem::OEAtomBondSet& abset)

      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightBase`)

      .. oe:source:: OEAddHighlighting_Base.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET

      .. oe:source:: OEAddHighlighting_Base.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET

      .. oe:source:: OEAddHighlighting_Base.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET

      .. oe:source:: OEAddHighlighting_Base.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET


   #. Highlighting using an :ref:`OESubSearch <OEChem_OESubSearch>` of which matches are being highlighted:

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEHighlightBase_OESubSearch:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OEHighlightBase& highlight,
                                const OEChem::OESubSearch& subsearch)

      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightBase`)

      .. oe:source:: OEAddHighlighting_Base.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

      .. oe:source:: OEAddHighlighting_Base.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

      .. oe:source:: OEAddHighlighting_Base.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

      .. oe:source:: OEAddHighlighting_Base.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

   .. _figure_OEAddHighlighting_OEHighlightBase:

   .. figure:: ../images/OEAddHighlighting-OEHighlightBase-OEMatch.*
      :align:  center

      **Example of highlighting 6-membered aromatic rings**

   .. seealso::

      * :ref:`OEHighlightByColor <OEDepict_OEHighlightByColor>` class
      * :ref:`OEHighlightByCogwheel <OEDepict_OEHighlightByCogwheel>` class
      * :ref:`OEHighlightByBallAndStick <OEDepict_OEHighlightByBallAndStick>` class
      * :ref:`OEHighlightByStick <OEDepict_OEHighlightByStick>` class
      * :ref:`OEHighlightByLasso <OEDepict_OEHighlightByLasso>` class
      * :oe:func:`OEDepict::OEDrawHighlighting` function
      * :ref:`chapter_highlighting` chapter

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

   **Highlights atoms and/or bonds with the given color and style**

   The atoms and bonds being highlighted can be specified either
   by a predicate or an :ref:`OEMatchBase <OEChem_OEMatchBase>` object or an
   :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` object.

   The following code snippets show three different ways to highlight any 6
   membered aromatic ring in a molecule using the
   built-in highlighting styles.
   They all generate the image shown in
   :ref:`Figure: Example of highlighting 6-membered aromatic rings
   <figure_OEAddHighlighting_OEHighlightStyle>`.


   #. Highlighting using **atom** and **bond predicates**:

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_AtomPred:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OESystem::OEColor& color,
                                unsigned int style,
                                const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& atompred)

      Highlights atoms with the given color and style.
      The atoms being highlighted are specified by given atom predicate.

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_BondPred:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OESystem::OEColor& color,
                                unsigned int style,
                                const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& bondpred)

      Highlights bonds with the given color and style.
      The bonds being highlighted are specified by given bonds predicate.

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_AtomAndBondPred:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OESystem::OEColor& color,
                                unsigned int style,
                                const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& atompred,
                                const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& bondpred)

      Highlights atoms and bonds with the given color and style.
      The atoms and bonds being highlighted are specified by given atom and bond predicates, respectively.


      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightStyle`)

      .. oe:source:: OEAddHighlighting_Style.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE

      .. oe:source:: OEAddHighlighting_Style.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE

      .. oe:source:: OEAddHighlighting_Style.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE

      .. oe:source:: OEAddHighlighting_Style.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-PREDICATE


   #. Highlighting using an :ref:`OEMatchBase <OEChem_OEMatchBase>` object that is
      initialized by substructure search or maximum common substructure search:

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_OEMatchBase:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OESystem::OEColor& color,
                                unsigned int style,
                                const OEChem::OEMatchBase& match)

      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightStyle`)

      .. oe:source:: OEAddHighlighting_Style.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH

      .. oe:source:: OEAddHighlighting_Style.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH

      .. oe:source:: OEAddHighlighting_Style.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH

      .. oe:source:: OEAddHighlighting_Style.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEMATCH



   #. Highlighting using an :ref:`OEAtomBondSet <OEChem_OEAtomBondSet>` object that stores
      the atoms and bonds being highlighted:

      .. _api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_OEAtomBondSet:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OESystem::OEColor& color,
                                unsigned int style,
                                const OEChem::OEAtomBondSet& abset)


      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightStyle`)

      .. oe:source:: OEAddHighlighting_Style.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET

      .. oe:source:: OEAddHighlighting_Style.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET

      .. oe:source:: OEAddHighlighting_Style.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET

      .. oe:source:: OEAddHighlighting_Style.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OEATOMBONDSET


   #. Highlighting using an :ref:`OESubSearch <OEChem_OESubSearch>` of which matches are being highlighted:

   .. _api_OEAddHighlighting_OE2DMolDisplay_OEColor_OEHighlightStyle_OESubSearch:

      .. oe:api::

         void OEAddHighlighting(OE2DMolDisplay& disp,
                                const OESystem::OEColor& color,
                                unsigned int style,
                                const OEChem::OESubSearch& subsearch)


      **Example:** (See image generated in :ref:`figure_OEAddHighlighting_OEHighlightStyle`)

      .. oe:source:: OEAddHighlighting_Style.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

      .. oe:source:: OEAddHighlighting_Style.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

      .. oe:source:: OEAddHighlighting_Style.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

      .. oe:source:: OEAddHighlighting_Style.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEADDHIGHLIGHTING-OESUBSEARCH

   .. _figure_OEAddHighlighting_OEHighlightStyle:

   .. figure:: ../images/OEAddHighlighting-OEHighlightStyle-OEMatch.*
      :align:  center

      **Example of highlighting 6-membered aromatic rings**


   .. seealso::

      * :ref:`OEColor <OESystem_OEColor>` class
      * :oe:constns:`OEDepict::OEHighlightStyle` namespace
      * :ref:`chapter_highlighting` chapter
