.. include:: ../../toolkit-substitutions

.. oe:namespace:: OESystem


.. meta::
   :keywords: OEOptions, Options


.. _OESystem_OEOptions:

.. oe:class:: OEOptions

   .. oe:api::

      class OEOptions

   The :ref:`OEOptions <OESystem_OEOptions>` is an abstract base class. The Options represent
   a collection of :ref:`OEParameter <OESystem_OEParameter>` class that defines the set of parameters
   associated with settings of various objects or calculations.

   .. seealso::

      * :ref:`OESimpleAppOptions <OEChem_OESimpleAppOptions>` class

   .. admonition:: Code Examples

      * :ref:`section_example_oechem_options` example

   The :ref:`OEOptions <OESystem_OEOptions>` class defines the following public methods:
    * :oe:meth:`AddDetail<OESystem::OEOptions::AddDetail>` and 
      :oe:meth:`GetDetail<OESystem::OEOptions::GetDetail>`
    * :oe:meth:`AddOption<OESystem::OEOptions::AddOption>`
    * :oe:meth:`AddParameter<OESystem::OEOptions::AddParameter>`
    * :oe:meth:`AddParameterPrefix<OESystem::OEOptions::AddParameterPrefix>`
    * :oe:meth:`AddParameterSuffix<OESystem::OEOptions::AddParameterSuffix>`
    * :oe:meth:`Clear<OESystem::OEOptions::Clear>`
    * :oe:meth:`DeleteOptions<OESystem::OEOptions::DeleteOptions>`
    * :oe:meth:`DeleteParameter<OESystem::OEOptions::DeleteParameter>`
    * :oe:meth:`FindDupParameters<OESystem::OEOptions::FindDupParameters>`
    * :oe:meth:`GetBrief<OESystem::OEOptions::GetBrief>` and
      :oe:meth:`SetBrief<OESystem::OEOptions::SetBrief>`
    * :oe:meth:`GetName<OESystem::OEOptions::GetName>` and
      :oe:meth:`SetName<OESystem::OEOptions::SetName>`
    * :oe:meth:`GetOption<OESystem::OEOptions::GetOption>`
    * :oe:meth:`GetOptions<OESystem::OEOptions::GetOptions>`
    * :oe:meth:`GetOrderPriority<OESystem::OEOptions::GetOrderPriority>` and
      :oe:meth:`SetOrderPriority<OESystem::OEOptions::SetOrderPriority>`
    * :oe:meth:`GetParameter<OESystem::OEOptions::GetParameter>`
    * :oe:meth:`GetParameters<OESystem::OEOptions::GetParameters>`
    * :oe:meth:`HasDupParameters<OESystem::OEOptions::HasDupParameters>`
    * :oe:meth:`HasOption<OESystem::OEOptions::HasOption>`
    * :oe:meth:`HasParameter<OESystem::OEOptions::HasParameter>`
    * :oe:meth:`SetParameterVisibility<OESystem::OEOptions::SetParameterVisibility>`
    * :oe:meth:`UpdateValues<OESystem::OEOptions::UpdateValues>`

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

      .. oe:api::

         OEOptions & operator=(const OEOptions &)

      Assignment operator.

   
   .. oe:method:: AddDetail

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

         .. oe:api::

            bool AddDetail(const std::string& detail)

      .. oe:language:: python

         .. oe:api:: python

            AddDetail(detail: str) -> bool

      Adds a line to the detailed description of the options.

   .. oe:method:: AddOption

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

         .. oe:api::

            OEOptions* AddOption(const OEOptions& opts)

      .. oe:language:: python

         .. oe:api:: python

            AddOption(opts: OEOptions) -> OEOptions

      Adds a copy of the specified options as sub-options to this options.

   .. oe:method:: AddParameter

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

         .. oe:api::

            OEParameter* AddParameter(const OEParameter&)

      .. oe:language:: python

         .. oe:api:: python

            AddParameter(param: OEParameter) -> OEParameter

      Adds a copy of the specified parameter to the options.

      .. oe:method:: AddParameterPrefix

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

         .. oe:api::

            bool AddParameterPrefix(const std::string& prefix,
                                    const bool underScore = true)

      .. oe:language:: python

         .. oe:api:: python

            AddParameterPrefix(prefix: str, underScore: bool = True) -> bool

      Add the specified prefix to the name of all the parameters.

   .. oe:method:: AddParameterSuffix

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

         .. oe:api::

            bool AddParameterSuffix(const std::string& suffix)

      .. oe:language:: python

         .. oe:api:: python

            AddParameterSuffix(suffix: str) -> bool

      Add the specified suffix to the name of all the parameters.

   .. oe:method:: Clear

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

         .. oe:api::

            void Clear()

      .. oe:language:: python

         .. oe:api:: python

            Clear() -> None

      Removes all parameters and sub-options.

   .. oe:method:: DeleteOptions

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

         .. oe:api::

            bool DeleteOptions(OEOptions&)

      .. oe:language:: python

         .. oe:api:: python

            DeleteOptions(arg2: OEOptions) -> bool

      Deletes the specified sub-options, if it belongs to this options.

   .. oe:method:: DeleteParameter

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

         .. oe:api::

            bool DeleteParameter(OEParameter& param)

      .. oe:language:: python

         .. oe:api:: python

            DeleteParameter(param: OEParameter) -> bool

      Deletes the specified parameter, if it belongs to this options.

   .. oe:method:: FindDupParameters

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

         .. oe:api::

            OEIterBase<OEParameter>* FindDupParameters(const bool visibleOnly = true)
            OEIterBase<const OEParameter>* FindDupParameters(const bool visibleOnly = true) const

      .. oe:language:: python

         .. oe:api:: python

            FindDupParameters(const: bool) -> OEParameterIter
            FindDupParameters(const: bool) -> Iterable[OEParameter]

      Returns duplicate parameters.  Two parameters are considered duplicates if they have
      a common name.  If ``visibleOnly`` is set to ``True``, parameters with visibility
      :oe:const:`OESystem::OEParamVisibility::Hidden` are ignored from this list. This operation 
      is always recursive to the associated sub-options.

   .. oe:method:: GetBrief

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

         .. oe:api::

            std::string GetBrief() const

      .. oe:language:: python

         .. oe:api:: python

            GetBrief() -> str

      See :oe:meth:`SetBrief<OESystem::OEOptions::SetBrief>` method.

   .. oe:method:: GetDetail

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

         .. oe:api::

            OEIterBase<const std::string>* GetDetail() const

      .. oe:language:: python

         .. oe:api:: python

            GetDetail() -> Iterable[str]

      See :oe:meth:`AddDetail<OESystem::OEOptions::AddDetail>` method.

   .. oe:method:: GetName

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

         .. oe:api::

            std::string GetName() const

      .. oe:language:: python

         .. oe:api:: python

            GetName() -> str

      See :oe:meth:`SetName<OESystem::OEOptions::SetName>` method.

   .. oe:method:: GetOption

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

         .. oe:api::

            OEOptions* GetOption(const std::string& name)
            const OEOptions* GetOption(const std::string& name) const

      .. oe:language:: python

         .. oe:api:: python

            GetOption(name: str) -> OEOptions

      Get the sub-options with the specified name. Returns a NULL pointer if a sub-options with
      specified name does not exist.

   .. oe:method:: GetOptions

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

         .. oe:api::

            OEIterBase<const OEOptions>* GetOptions(const bool recursive = true) const
            OEIterBase<OEOptions>* GetOptions(const bool recursive = true)

      .. oe:language:: python

         .. oe:api:: python

            GetOptions(const: bool) -> Iterable[OEOptions]

      Get the sub-options of this options. A value of ``true`` for ``recursive`` compiles all 
      the sub-options from the subsequent sub-options.

   .. oe:method:: GetOrderPriority

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

         .. oe:api::

            int GetOrderPriority() const

      .. oe:language:: python

         .. oe:api:: python

            GetOrderPriority() -> int

      See :oe:meth:`SetOrderPriority<OESystem::OEOptions::SetOrderPriority>` method.

   .. oe:method:: GetParameter

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

         .. oe:api::

            OEParameter* GetParameter(const std::string& name)
            const OEParameter* GetParameter(const std::string& name) const

      .. oe:language:: python

         .. oe:api:: python

            GetParameter(name: str) -> OEParameter

      Get the parameter with the specified name. Returns a NULL pointer if a parameter with
      specified name does not exist.

   .. oe:method:: GetParameters

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

         .. oe:api::

            OEIterBase<const OEParameter>* GetParameters(const bool recursive = true) const
            OEIterBase<OEParameter>* GetParameters(const bool recursive = true)
            OEIterBase<const OEParameter>* GetParameters(const std::string& name,
                                                         const bool recursive = true) const
            OEIterBase<OEParameter>* GetParameters(const std::string& name,
                                                   const bool recursive = true)

      .. oe:language:: python

         .. oe:api:: python

            GetParameters(const: bool) -> Iterable[OEParameter]
            GetParameters(const: bool) -> OEParameterIter
            GetParameters(arg1: str, recursive: bool = True) -> Iterable[OEParameter]
            GetParameters(arg1: str, recursive: bool = True) -> OEParameterIter

      Get the parameters from this options. If a name is specified only parameters with the specified 
      name are provided. A value of ``true`` for ``recursive`` compiles all the parameters from the
      subsequent sub-options.

   .. oe:method:: HasDupParameters

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

         .. oe:api::

            bool HasDupParameters(const bool visibleOnly = true) const

      .. oe:language:: python

         .. oe:api:: python

            HasDupParameters(visibleOnly: bool = True) -> bool

      Check if a there are duplicate parameters in this options. Two parameters are considered 
      duplicates if they have a common name.  If ``visibleOnly`` is set to ``True``, parameters with 
      visibility :oe:const:`OESystem::OEParamVisibility::Hidden` are ignored from this check. This 
      operation is always recursive to the associated sub-options.

   .. oe:method:: HasOption

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

         .. oe:api::

            bool HasOption(const std::string& name) const

      .. oe:language:: python

         .. oe:api:: python

            HasOption(name: str) -> bool

      Check if a sub-options with the specified name exists in the options.

   .. oe:method:: HasParameter

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

         .. oe:api::

            bool HasParameter(const std::string& name) const

      .. oe:language:: python

         .. oe:api:: python

            HasParameter(name: str) -> bool

      Check if a parameter with the specified name (or alias) exists in the options.

   .. oe:method:: SetBrief

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

         .. oe:api::

            bool SetBrief(std::string brief)

      .. oe:language:: python

         .. oe:api:: python

            SetBrief(brief: str) -> bool

      Sets the brief description of the Options.

   .. oe:method:: SetName

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

         .. oe:api::

            bool SetName(std::string name)

      .. oe:language:: python

         .. oe:api:: python

            SetName(name: str) -> bool

      Sets the name of the Options. 

   .. oe:method:: SetOrderPriority

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

         .. oe:api::

            bool SetOrderPriority(int order)

      .. oe:language:: python

         .. oe:api:: python

            SetOrderPriority(priority: int) -> bool

      Sets the order priority of the Options, which is used to
      control the order Options appear in help lists. **Default: 0**

   .. oe:method:: SetParameterVisibility

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

         .. oe:api::

            bool SetParameterVisibility(const unsigned visibility)
            bool SetParameterVisibility(const std::string& name,
                                        const unsigned visibility)

      .. oe:language:: python

         .. oe:api:: python

            SetParameterVisibility(visibility: int) -> bool
            SetParameterVisibility(name: str, visibility: int) -> bool

      Sets the visibility of the parameters to the specified value.  This operation is
      always recursive to the associated sub-options. Valid settings are defined in the :oe:constns:`OESystem::OEParamVisibility` namespace.

   .. oe:method:: UpdateValues

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

         .. oe:api::

            bool UpdateValues(const OEOptions& opts)

      .. oe:language:: python

         .. oe:api:: python

            UpdateValues(opts: OEOptions) -> bool

      Update parameters values of this options, from the parameter values of the soecified
      options.  Two parameters are considered same if they have a common name and data type. 
      This operation is always recursive to the associated sub-options.
