.. include:: ../substitutions

.. oe:namespace:: OEDepict


.. _OEDepict_OEHighlightLabel:

.. oe:class:: OEHighlightLabel

   .. oe:api::

      class OEHighlightLabel

   The :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` class allows the
   customization the style of the label that can be position
   on molecule depiction by calling the :oe:func:`OEDepict::OEAddLabel`
   function.

   The :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` class stores the following properties:

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

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

      * - text
        - :oe:meth:`GetText<OEDepict::OEHighlightLabel::GetText>`
        - :oe:meth:`OEHighlightLabel constructors<OEDepict::OEHighlightLabel::Constructors>`
        - string

      * - bounding box pen
        - :oe:meth:`GetBoundingBoxPen<OEDepict::OEHighlightLabel::GetBoundingBoxPen>`
        - :oe:meth:`SetBoundingBoxPen<OEDepict::OEHighlightLabel::SetBoundingBoxPen>`
        - :ref:`OEPen <OEDepict_OEPen>`

      * - label font
        - :oe:meth:`GetFont<OEDepict::OEHighlightLabel::GetFont>`
        - :oe:meth:`SetFont<OEDepict::OEHighlightLabel::SetFont>`
        - :ref:`OEFont <OEDepict_OEFont>`

      * - label font scale
        - :oe:meth:`GetFontScale<OEDepict::OEHighlightLabel::GetFontScale>`
        - :oe:meth:`SetFontScale<OEDepict::OEHighlightLabel::SetFontScale>`
        - positive floating point number in the range of ``[0.25, 1.5]`` or ``0.0``


   .. ################################################################
      # Constructors
      ################################################################
   
   .. oe:method:: Constructors

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

         .. oe:api::

            OEHighlightLabel(const std::string& text)

      .. oe:language:: python

         .. oe:api:: python

            OEHighlightLabel(text: str) -> OEHighlightLabel
            OEHighlightLabel(arg2: OEHighlightLabel) -> OEHighlightLabel

      Creates an :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` object with default style.

      *text*
        The text that is going to be positioned on the molecule depiction.

      **Example:**

      .. oe:source:: OEHighlightLabel_SetProps.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-DEFAULT

      .. oe:source:: OEHighlightLabel_SetProps.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-DEFAULT

      .. oe:source:: OEHighlightLabel_SetProps.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-DEFAULT

      .. oe:source:: OEHighlightLabel_SetProps.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-DEFAULT

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

         **Example of adding label with default style**

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

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

         .. oe:api::

            OEHighlightLabel(const std::string& text, const OEFont& font)

      .. oe:language:: python

         .. oe:api:: python

            OEHighlightLabel(text: str, font: OEFont) -> OEHighlightLabel

      Creates an :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` object with user-defined font.

      *text*
         The text that is going to be positioned on the molecule depiction.

      *font*
         The :ref:`OEFont <OEDepict_OEFont>` object that encapsulates properties
         that determine the display style of text.

      .. seealso::

         * :ref:`OEFont <OEDepict_OEFont>` class

      **Example:**

      .. oe:source:: OEHighlightLabel_SetProps.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-FONT

      .. oe:source:: OEHighlightLabel_SetProps.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-FONT

      .. oe:source:: OEHighlightLabel_SetProps.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-FONT

      .. oe:source:: OEHighlightLabel_SetProps.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-FONT

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

         **Example of adding label with user-defined font**

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

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

         .. oe:api::

            OEHighlightLabel(const std::string& text,
                             const OESystem::OEColor& color)

      .. oe:language:: python

         .. oe:api:: python

            OEHighlightLabel(text: str, color: OEColor) -> OEHighlightLabel

      Creates an :ref:`OEHighlightLabel <OEDepict_OEHighlightLabel>` object with user-defined border color.

      *text*
         The text that is going to be positioned on the molecule depiction.

      *color*
         The color of the border around the label.

      **Example:**

      .. oe:source:: OEHighlightLabel_SetProps.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-COLOR

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

         **Example of adding label with user-defined border color**

      .. seealso::

         * :ref:`OEColor <OESystem_OEColor>` class


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

   .. oe:method:: GetBoundingBoxPen

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

         .. oe:api::

            const OEPen& GetBoundingBoxPen() const

      .. oe:language:: python

         .. oe:api:: python

            GetBoundingBoxPen() -> OEPen

      Returns the pen that is used to draw a border around the label.

      .. seealso::

         * :ref:`OEPen <OEDepict_OEPen>` class
         * :oe:cls:`OEDepict::OEHighlightLabel::SetBoundingBoxPen` method


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

   .. oe:method:: GetFont

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

         .. oe:api::

            const OEFont& GetFont() const

      .. oe:language:: python

         .. oe:api:: python

            GetFont() -> OEFont

      Returns the font of the label.

      .. seealso::

         * :ref:`OEFont <OEDepict_OEFont>` class
         * :oe:meth:`OEDepict::OEHighlightLabel::SetFont` method


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

   .. oe:method:: GetFontScale

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

         .. oe:api::

            double GetFontScale() const

      .. oe:language:: python

         .. oe:api:: python

            GetFontScale() -> float

      Returns the multiplier that can be used to increase or decrease the font size
      of the label relative to the font size used to render labels of the 
      of the depicted molecule.
      The default value is ``0.75``.

      .. seealso::

         * :ref:`OEFont <OEDepict_OEFont>` class
         * :oe:meth:`OEDepict::OEHighlightLabel::SetFontScale` method


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

   .. oe:method:: GetText

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

         .. oe:api::

            std::string GetText() const

      .. oe:language:: python

         .. oe:api:: python

            GetText() -> str

      Returns the text of the label.


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

   .. oe:method:: SetBoundingBoxPen

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

         .. oe:api::

            void SetBoundingBoxPen(const OEPen& pen)

      .. oe:language:: python

         .. oe:api:: python

            SetBoundingBoxPen(pen: OEPen) -> None

      Sets the pen that is used to draw a border around the label.

      **Example:**

      .. oe:source:: OEHighlightLabel_SetProps.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETBOUNDINGBOXPEN

      .. oe:source:: OEHighlightLabel_SetProps.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETBOUNDINGBOXPEN

      .. oe:source:: OEHighlightLabel_SetProps.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETBOUNDINGBOXPEN

      .. oe:source:: OEHighlightLabel_SetProps.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETBOUNDINGBOXPEN



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

         **Example of adding label with user-defined border**

      .. seealso::

         * :ref:`OEPen <OEDepict_OEPen>` class

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

   .. oe:method:: SetFont

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

         .. oe:api::

            void SetFont(const OEFont& font)

      .. oe:language:: python

         .. oe:api:: python

            SetFont(font: OEFont) -> None

      Set the font of the label.

      **Example:**

      .. oe:source:: OEHighlightLabel_SetProps.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONT

      .. oe:source:: OEHighlightLabel_SetProps.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONT

      .. oe:source:: OEHighlightLabel_SetProps.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONT

      .. oe:source:: OEHighlightLabel_SetProps.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONT

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

         **Example of adding label with user-defined font**

      .. note::

         The size of fonts of the label depends on:

         * the size of the font used  to render atom labels of the
           the depicted molecule
         * the multiplier set by the :oe:meth:`OEDepict::OEHighlightLabel::SetFontScale` method

      .. seealso::

         * :ref:`OEFont <OEDepict_OEFont>` class


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

   .. oe:method:: SetFontScale

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

         .. oe:api::

            void SetFontScale(double scale)

      .. oe:language:: python

         .. oe:api:: python

            SetFontScale(scale: float) -> None

      Sets the multiplier that can be used to increase or decrease the font size
      of the label relative to the font size used to render atom labels of the
      of the depicted molecule.

      *scale*
         This value has to be either ``0.0`` or in a range of ``[0.25, 1.50]``.
         The default value is ``0.75``.

         In case of ``0.0``, the label is not scaled with the molecule
         but rather fixed font size is used regardless of the size of
         the depicted molecule.

      **Example:**

      .. oe:source:: OEHighlightLabel_SetProps.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONTSCALE

      .. oe:source:: OEHighlightLabel_SetProps.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONTSCALE

      .. oe:source:: OEHighlightLabel_SetProps.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONTSCALE

      .. oe:source:: OEHighlightLabel_SetProps.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEHIGHLIGHTLABEL-SETFONTSCALE

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

         **Example of adding label with user-defined font scaling**
