.. oe:namespace:: OESystem

.. meta::
   :keywords: OEInterface, Interface


.. _OESystem_OEInterface:

.. oe:class:: OEInterface

   .. oe:api::


      class OEInterface

   This class represents `OEInterface`.

   
   .. oe:method:: Constructors

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

         .. oe:api::

            OEInterface()
            OEInterface(const OEInterface &)

      .. oe:language:: python

         .. oe:api:: python

            OEInterface() -> OEInterface
            OEInterface(arg2: OEInterface) -> OEInterface

      Default and copy constructors.

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

         .. oe:api::

            OEInterface(const unsigned char* dataptr)
            OEInterface(const char* dataptr)

      .. oe:language:: python

         .. oe:api:: python

            OEInterface(dataptr: str) -> OEInterface

      Constructs an :ref:`OEInterface <OESystem_OEInterface>` and configures it
      with the interface definition passed by ``dataptr``. This is
      equivalent to the following code: 

      .. oe:source:: OEInterfaceConfigureCtor.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OECONFIGURE-OEINTERFACE

      .. oe:source:: OEInterfaceConfigureCtor.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OECONFIGURE-OEINTERFACE

      .. oe:source:: OEInterfaceConfigureCtor.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OECONFIGURE-OEINTERFACE

      .. oe:source: OEInterfaceConfigureCtor.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OECONFIGURE-OEINTERFACE

      .. note:: 
         
         It is possible to configure an :ref:`OEInterface <OESystem_OEInterface>`
         from multiple interface definitions. Just call
         :oe:func:`OESystem::OEConfigure` once per interface definition
         on the same :ref:`OEInterface <OESystem_OEInterface>` object.

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

         .. oe:api::

            OEInterface(const unsigned char* dataptr, int argc, char** argv)
            OEInterface(const char* dataptr, int argc, char** argv)

      .. oe:language:: python

         .. oe:api:: python

            OEInterface(dataptr: str, argc: int, argv: str) -> OEInterface

      Constructs an :ref:`OEInterface <OESystem_OEInterface>` and configures it
      with the interface definition passed by ``dataptr``. Then parses
      the command line given by ``argv``. This is
      equivalent to the following code: 

      .. oe:source:: OEInterfaceConvenienceCtor.cpp
         :language: c++
         :noindent:
         :frag:     SNIPPET-OEINTERFACE-CONVENIENCE

      .. oe:source:: OEInterfaceConvenienceCtor.py
         :language: python
         :noindent:
         :frag:     SNIPPET-OEINTERFACE-CONVENIENCE 

      .. oe:source:: OEInterfaceConvenienceCtor.java
         :language: java
         :noindent:
         :frag:     SNIPPET-OEINTERFACE-CONVENIENCE 

      .. oe:source: OEInterfaceConvenienceCtor.cs
         :language: csharp
         :noindent:
         :frag:     SNIPPET-OEINTERFACE-CONVENIENCE 

      .. warning:: 

         These convenience constructors may force the program to exit
         and thus may not be appropriate when writing a library that
         should instead return errors.


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

      .. oe:api::

         OEInterface &operator=(const OEInterface &)

      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
      :ref:`OEInterface <OESystem_OEInterface>`. Returns ``true`` if the add was
      successful and ``false`` otherwise. (The current implementation
      never fails)

   .. oe:method:: AddInterface

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

         .. oe:api::

            OEInterface* AddInterface()

      .. oe:language:: python

         .. oe:api:: python

            AddInterface() -> OEInterface

      Adds a child :ref:`OEInterface <OESystem_OEInterface>` and returns a
      pointer to the newly created object (which is owned by the
      current :ref:`OEInterface <OESystem_OEInterface>` object).

   .. oe:method:: AddParameter

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

         .. oe:api::

            OEParameter* AddParameter(std::string classid)

      .. oe:language:: python

         .. oe:api:: python

            AddParameter(classid: str) -> OEParameter

      Adds a parameter to the :ref:`OEInterface <OESystem_OEInterface>`
      instance. The returned pointer points to the newly created
      :ref:`OEParameter <OESystem_OEParameter>` object. This memory is **owned** by
      the :ref:`OEInterface <OESystem_OEInterface>` object. If the add fails
      ``NULL`` will be returned.

      The implementation of the returned :ref:`OEParameter <OESystem_OEParameter>`
      pointer will always be a subclass of

      .. code-block:: c++

         template <TT> OETypedParameter


      The specific type depends upon the value of classid as follows :

      string
          ``TT`` is ``std::string`` parameter 

      double
          ``TT`` is ``double`` parameter
 
      float
          ``TT`` is ``float`` parameter 

      bool
          ``TT`` is ``bool`` parameter
 
      int
          ``TT`` is ``int`` parameter
 
      file
          ``TT`` is :ref:`oeisstream <OEPlatform_oeisstream>` parameter

      param_file
          ``TT`` is :ref:`oeisstream <OEPlatform_oeisstream>` and additionally the
          parameter is specially recognized by :oe:func:`OESystem::OEParseCommandLine` 
          as a text file holding parameter settings.

   .. oe:method:: Clear

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

         .. oe:api::

            bool Clear()

      .. oe:language:: python

         .. oe:api:: python

            Clear() -> bool

      Returns the :ref:`OEInterface <OESystem_OEInterface>` object to the default constructed
      state of an :ref:`OEInterface <OESystem_OEInterface>`.

   .. oe:method:: DeleteInterface

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

         .. oe:api::

            bool DeleteInterface(OEInterface& itf)

      .. oe:language:: python

         .. oe:api:: python

            DeleteInterface(itf: OEInterface) -> bool

      Deletes a child :ref:`OEInterface <OESystem_OEInterface>` object. 'itf' is
      the child :ref:`OEInterface <OESystem_OEInterface>` to be deleted. The
      method returns ``true`` if the deletion is successful and
      ``false`` otherwise. 'itf' must be directly owned by the
      :ref:`OEInterface <OESystem_OEInterface>`, not one of its child
      :oe:cls:`OEInterfaces<OESystem::OEInterface>`.

   .. 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 a parameter ('param') owned by this
      :ref:`OEInterface <OESystem_OEInterface>` object. The function returns
      ``true`` if the delete succeeds and ``false`` otherwise. The
      parameter must be **owned** by the :ref:`OEInterface <OESystem_OEInterface>`
      object to be deleted (it will not delete parameters that belong
      to child :ref:`OEInterface <OESystem_OEInterface>` objects of this
      :ref:`OEInterface <OESystem_OEInterface>`).

   .. oe:method:: Factory

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

         .. oe:api::

            static OESimpleFactory<std::string, OEParameter>& Factory()

      .. oe:language:: python

         .. oe:api:: python

            Factory() -> OESimpleFactory< str,OEParameter >

      Returns the :ref:`OEInterface <OESystem_OEInterface>` class's factory
      used to create new parameters.

   .. oe:method:: Get

      .. oe:api::

         template <class TT>
         TT Get(std::string name, unsigned int ilist = 0) const

      Returns the setting (either the value, or default if the value
      is not set) of the parameter with the given name and
      instance. The parameter must be of type ``TT``, and must have
      either have a value or default set. If the parameter cannot be
      found (*i.e.*, a call to :oe:meth:`OESystem::OEInterface::Has` with 
      the same ``TT`` and 'name' returns
      ``false``) a warning is issued and a default constructed ``TT`` is
      returned.

   .. oe:method:: GetBrief

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

         .. oe:api::

            std::string GetBrief() const

      .. oe:language:: python

         .. oe:api:: python

            GetBrief() -> str


      Returns the brief description of the :ref:`OEInterface <OESystem_OEInterface>` object.

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

      Returns the detailed description of the :ref:`OEInterface <OESystem_OEInterface>` object.

   .. oe:method:: GetInterface

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

         .. oe:api::

            OEInterface* GetInterface(std::string name)
            const OEInterface* GetInterface(std::string name) const

      .. oe:language:: python

         .. oe:api:: python

            GetInterface(name: str) -> OEInterface

      Returns a pointer to a child :ref:`OEInterface <OESystem_OEInterface>` with
      a given 'name' owned by any child
      :ref:`OEInterface <OESystem_OEInterface>`. The search is recursive
      searching through all child's child
      :oe:cls:`OEInterfaces<OESystem::OEInterface>`, etc. If no such
      :ref:`OEInterface <OESystem_OEInterface>` exists ``NULL`` is returned.


   .. oe:method:: GetInterfaces

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

         .. oe:api::

            OEIterBase< OEInterface>* GetInterfaces(bool recursive = false)
            OEIterBase<const OEInterface>* GetInterfaces(bool recursive = false) const

      .. oe:language:: python

         .. oe:api:: python

            GetInterfaces(recursive: bool = False) -> OEInterfaceIter
            GetInterfaces(recursive: bool = False) -> Iterable[OEInterface]

      Returns and iterator over all child
      :oe:cls:`OEInterfaces<OESystem::OEInterface>` of this object. If
      recursive is ``true``, the iterator will include all of the
      children's :oe:cls:`OEInterfaces<OESystem::OEInterface>`
      recursively in arbitrary order. If recursive is ``false`` only
      the immediate child :oe:cls:`OEInterfaces<OESystem::OEInterface>`
      will be returned, and they will be sorted by
      :oe:meth:`OESystem::OEInterface::GetOrderPriority` (lowest values
      first) and then name.

   .. oe:method:: GetList

      .. oe:api::

         template <class TT>
         OEIterBase<const TT>* GetList(std::string name) const

   .. seealso::

     .. oe:language:: c++

         * Example program :ref:`catmols.cpp<section_example_oechem_catmols>`

     .. oe:language:: python
   
         * Example program :ref:`catmols.py<section_example_oechem_catmols>`

     .. oe:language:: java

         * Example program :ref:`CatMols.java<section_example_oechem_catmols>`

     .. oe:language:: csharp

         * Example program :ref:`CatMols.cs<section_example_oechem_catmols>`

   .. oe:method:: GetName

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

         .. oe:api::

            std::string GetName() const

      .. oe:language:: python

         .. oe:api:: python

            GetName() -> str

      Returns the name of the :ref:`OEInterface <OESystem_OEInterface>` object.

   .. oe:method:: GetOrderPriority

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

         .. oe:api::

            int GetOrderPriority() const

      .. oe:language:: python

         .. oe:api:: python

            GetOrderPriority() -> int

      Returns the order priority of the :ref:`OEInterface <OESystem_OEInterface>` object.

   .. oe:method:: GetParameter

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            GetParameter(name: str) -> OEParameter

      Returns a pointer to a :ref:`OEParameter <OESystem_OEParameter>` with a
      given 'name' owned by the :ref:`OEInterface <OESystem_OEInterface>` object
      or one of its child :oe:cls:`OEInterfaces<OESystem::OEInterface>` 
      (or child's child
      :ref:`OEInterface <OESystem_OEInterface>`, etc). If no such parameter
      exists ``NULL`` is returned.

   .. oe:method:: GetParameters

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

         .. oe:api::

            OEIterBase<OEParameter>* GetParameters(bool recursive = true)
            OEIterBase<const OEParameter>* GetParameters(bool recursive = true) const

      .. oe:language:: python

         .. oe:api:: python

            GetParameters(recursive: bool = True) -> OEParameterIter
            GetParameters(recursive: bool = True) -> Iterable[OEParameter]


      Returns an iterator over all
      :oe:cls:`OEParameters<OESystem::OEParameter>` of the
      :ref:`OEInterface <OESystem_OEInterface>` object. If recursive is ``true``
      the search is recursive including parameters held by all child
      :oe:cls:`OEInterfaces<OESystem::OEInterface>` and their children
      in arbitrary order. If recursive is ``false`` parameters held by
      child :oe:cls:`OEInterfaces<OESystem::OEInterface>` will not be
      included and they will be sorted by the parameters order
      priority (lowest values first), followed by name.

   .. oe:method:: GetTypedParameter

      .. oe:api::

         template<class TT>
         OETypedParameter<TT> *GetTypedParameter(std::string name)
         template<class TT>
         const OETypedParameter<TT> *GetTypedParameter(std::string name) const

   .. oe:method:: Has

      .. oe:api::

         template<class TT>
         bool Has(std::string name, unsigned int ilist = 0) const

      Returns ``true`` if all of the following are ``true``:

      1. A parameter with name `name` is contained by the :ref:`OEInterface <OESystem_OEInterface>`.
      2. The parameter is of type ``TT``
      3. The parameters value of default is set.

      In all other cases the function returns ``false``. 

   .. oe:method:: Parent

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

         .. oe:api::

            OEInterface* Parent()
            const OEInterface* Parent() const

      .. oe:language:: python

         .. oe:api:: python

            Parent() -> OEInterface

      Returns a pointer to the parent :ref:`OEInterface <OESystem_OEInterface>` of
      this object, or ``NULL`` if this :ref:`OEInterface <OESystem_OEInterface>`
      object does not have a parent.

   .. 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
      :ref:`OEInterface <OESystem_OEInterface>`. Returns ``true`` if the brief
      was successfully set and ``false`` otherwise. (The current
      implementation never fails)

   .. 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 :ref:`OEInterface <OESystem_OEInterface>`. Returns
      ``true`` if the name was successfully set and ``false``
      otherwise. (The current implementation never fails).

   .. oe:method:: SetOrderPriority

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

         .. oe:api::

            bool SetOrderPriority(int priority)

      .. oe:language:: python

         .. oe:api:: python

            SetOrderPriority(priority: int) -> bool

      Sets the order priority of the
      :ref:`OEInterface <OESystem_OEInterface>`. The order priority overrides the
      default sorting by name that is used when calling the
      :oe:meth:`GetInterfaces(false)<OESystem::OEInterface::GetInterfaces>` 
      member function. Child :oe:cls:`OEInterfaces<OESystem::OEInterface>` with
      lower priority values will appear first.
      This function returns ``true`` if  the priority was successfully
      set and ``false`` otherwise.  (The current  implementation never
      fails).
