.. include:: ../substitutions

.. oe:namespace:: OEGrapheme

.. meta::
   :keywords: OEAddLigandHighlighting

.. oe:function:: OEAddLigandHighlighting


   Highlights atoms and/or bonds of the displayed ligand.

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

      * - Link
        - Description

      * - :ref:`OEAddLigandHighlighting(disp, highlight, atompred)<api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_AtomPred>`
        - highlights ligand atoms with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddLigandHighlighting(adisp, highlight, bondpred)<api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_BondPred>`
        - highlights ligand bonds  with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddLigandHighlighting(adisp, highlight, atompred, bondpred)<api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_AtomAndBondPred>`
        - highlights ligand atoms and bonds  with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddLigandHighlighting(adisp, highlight, match)<api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_OEMatchBase>`
        - highlights ligand atoms and bonds of a match  with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`
      * - :ref:`OEAddLigandHighlighting(adisp, highlight, abset)<api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_OEAtomBondSet>`
        - highlights ligand atoms and bonds of a set with :ref:`OEHighlightBase <OEDepict_OEHighlightBase>`

   **Parameters :**

   *adisp*
      The :ref:`OE2DActiveSiteDisplay <OEGrapheme_OE2DActiveSiteDisplay>` object of which ligand atoms
      add/or ligand bonds being highlighted.

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

   *atompred*
      :oe:func:`OEGrapheme::OEAddLigandHighlighting` function highlights
      only ligand atoms for which the given atom predicate returns `true`.

   *bondpred*
      :oe:func:`OEGrapheme::OEAddLigandHighlighting` function highlights
      only ligand bonds for which the given bond predicate returns `true`.

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

   *abset*
      Stores the ligand atoms and bonds being highlighted.


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


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

      .. _api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_AtomPred:

      .. oe:api::

         void OEAddLigandHighlighting(OE2DActiveSiteDisplay& adisp,
                                      const OEDepict::OEHighlightBase& highlight,
                                      const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& atompred)

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

      .. _api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_BondPred:

      .. oe:api::

         void OEAddLigandHighlighting(OE2DActiveSiteDisplay& adisp,
                                      const OEDepict::OEHighlightBase& highlight,
                                      const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& bondpred)

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


      .. _api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_AtomAndBondPred:

      .. oe:api::

         void OEAddLigandHighlighting(OE2DActiveSiteDisplay& adisp,
                                      const OEDepict::OEHighlightBase& highlight,
                                      const OESystem::OEUnaryPredicate<OEChem::OEAtomBase>& atompred,
                                      const OESystem::OEUnaryPredicate<OEChem::OEBondBase>& bondpred)


      Highlights ligand 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_OEAddLigandHighlighting_Predicate` and
      :ref:`figure_OEAddLigandHighlighting_AtomAndBondPredicate` )

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

      ..    oe:language:: python

            :ref:`Full listing. <listing-ActiveSiteHighlight.py>`


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

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

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

   .. _figure_OEAddLigandHighlighting_Predicate:

   .. figure:: ../images/OEAddHighlighting-ActiveSite-Predicate.*
      :align:  center

      **Example of highlighting 6-membered rings of a ligand using 'ball and stick' style**


   .. _figure_OEAddLigandHighlighting_AtomAndBondPredicate:

   .. figure:: ../images/OEAddHighlighting-ActiveSite-AtomAndBondPredicate.*
      :align:  center

      **Example of highlighting 6-membered rings of a ligand using 'color' style**

   .. seealso::

      * :ref:`chapter_predicates` chapter in the *OEChem TK* manual


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

      .. _api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_OEMatchBase:

      .. oe:api::

         void OEAddLigandHighlighting(OE2DActiveSiteDisplay& adisp,
                                      const OEDepict::OEHighlightBase& highlight,
                                      const OEChem::OEMatchBase& match)

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

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

      ..    oe:language:: python

            :ref:`Full listing. <listing-ActiveSiteHighlight.py>`

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

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

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

   .. _figure_OEAddLigandHighlighting_OEMatch:

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

      **Example of highlighting 6-membered rings of a ligand using 'lasso' style**

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

      .. _api_OEAddLigandHighlighting_OE2DActiveSiteDisplay_OEAtomBondSet:

      .. oe:api::

         void OEAddLigandHighlighting(OE2DActiveSiteDisplay& adisp,
                                      const OEDepict::OEHighlightBase& highlight,
                                      const OEChem::OEAtomBondSet& abset)

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

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

      :ref:`Full listing. <listing-ActiveSiteHighlight.py>`


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

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

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

   .. _figure_OEAddLigandHighlighting_OEAtomBondSet:

   .. figure:: ../images/OEAddHighlighting-ActiveSite-OEAtomBondSet.*
      :align:  center

      **Example of highlighting 6-membered rings of a ligand using 'cogwheel' style**
