/////////////////////////////////////////////////////////////////////////////// 
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance"). 
// All rights reserved. 
// 
// This software and its documentation and related materials are owned by 
// the Alliance. The software may only be incorporated into application 
// programs owned by members of the Alliance, subject to a signed 
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable  
// trade secrets of the Alliance and its suppliers. The software is also 
// protected by copyright law and international treaty provisions. Application  
// programs incorporating this software must include the following statement 
// with their copyright notices:
//   
//   This application incorporates Open Design Alliance software pursuant to a license 
//   agreement with Open Design Alliance.
//   Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance. 
//   All rights reserved.
//
// By use of this software, its documentation or related materials, you 
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////

#if !defined(ODA_ODMVDXMLELEMENT_H_INCLUDED_)
#define ODA_ODMVDXMLELEMENT_H_INCLUDED_

#if _MSC_VER > 1000
#pragma once
#endif // _MSC_VER > 1000

#include "MvdXmlCommon.h"
#include "OdString.h"
#include "StringArray.h"
#include "MvdXmlAuditInfo.h"
#include "tinyxml.h"

/** \details 
Contains declarations related to Model View Definition (MVD) functionality.
*/
namespace OdMvdXml
{
  class OdMvdXmlRoot;
  SMARTPTR(OdMvdXmlElement);

  /** \details 
    A class that implements storing and operating data that an XML element of the model view definition contains.
  */
  class MVDXML_EXPORT OdMvdXmlElement : public OdRxObject
  {
    ODRX_DECLARE_MEMBERS(OdMvdXmlElement);

  public:
  
    /** \details 
      Creates a new OdMvdXmlElement object with default parameters.
    */
    OdMvdXmlElement();

    /** \details
      Reads data from a specified XML element.
      \param pItem [out] A raw pointer to an XML element object that contains data to read.
      \returns eOk if the data was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult inFields(TiXmlElement* pItem);
    
    /** \details 
      Writes an XML element data to a specified XML node.
      \param pParent [in] A raw pointer to an XML node that accepts data (the data is written in it).
      \returns eOk if the data was successfully written; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult outFields(TiXmlNode* pParent);
    
    /** \details 
      Retrieves the root MVDXML element.
      \returns A raw pointer to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlRoot.html">OdMvdXmlRoot</exref> object.
    */
    OdMvdXmlRoot* getRoot() const;
    
    /** \details 
      Appends a new XML error message to a specified parent element.
      \param pParent  [in] A raw pointer to an XML element. 
      \param text     [in] An ANSI string that contains the error message text.
      \param caption  [in] An ANSI string that contains the error message caption.
      \param code     [in] An <exref target="../tkernel_api_cpp/OdResult.html">error code</exref>.
    */
    void appendXmlErrorMessage(TiXmlElement* pParent, const char* text, const char* caption = NULL, OdResult code = eOk);
    
    /** \details 
      Appends a new XML warning message to a specified parent element.
      \param pParent  [in] A raw pointer to an XML element. 
      \param text     [in] An ANSI string that contains the warning message text.
      \param caption  [in] An ANSI string that contains the warning message caption.
      \param code     [in] An <exref target="../tkernel_api_cpp/OdResult.html">error code</exref>.
    */
    void appendXmlWarningMessage(TiXmlElement* pParent, const char* text, const char* caption = NULL, OdResult code = eOk);
    
    /** \details 
      Appends a new error message.
      \param text     [in] An ANSI string that contains the error message text.
      \param caption  [in] An ANSI string that contains the error message caption.
    */
    void appendErrorMessage(const char* text, const char* caption = NULL) const;
    
    /** \details 
      Appends a new warning message.
      \param text     [in] An ANSI string that contains the warning message text.
      \param caption  [in] An ANSI string that contains the warning message caption.
    */
    void appendWarningMessage(const char* text, const char* caption = NULL) const;

    /** \details
      The assignment operator for MVDXML elements.
      \param other [in] Another OdMvdXmlElement object to be assigned (the right-hand operand of the assignment operation).
      \returns A reference to the <exref target="../tifc_api_cpp/OdMvdXml__OdMvdXmlElement.html">MVDXML element</exref> modified by the assignment operation.
    */
    OdMvdXmlElement& operator=(const OdMvdXmlElement& other);

  protected:
    /** \details
      Copy data from the other element.

      \param other [in] Object to copy from.
    */
    void assign(const OdMvdXmlElement* other);

    /** \details
      Retrieves the name of the element. This name is used to write the element to a file.

      \returns The name of the element.
    */
    virtual OdAnsiString getElementName();

    /** \details
      Reads attributes from a xml element.

      \param pItem [in] Pointer to a xml element containing attributes.

      \returns eOk if the data was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult inAttributes(TiXmlElement* pItem);

    /** \details
      Reads child element from a xml element.

      \param nodeName [in] The node name of the xml element containing the child data.
      \param pChild [in] Pointer to a xml element containing child data.

      \returns eOk if the data was successfully read; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult inChildNode(const char *nodeName, TiXmlElement* pChild);

    /** \details
      Writing attributes to the xml element.

      \param pItem [in] Pointer to the xml element to which you want to add attributes.

      \returns eOk if the data was written successfully; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult outAttributes(TiXmlElement* pItem);

    /** \details
      Writing child elements to the xml element.

      \param pParent [in] Pointer to the xml element to which you want to add children.

      \returns eOk if the data was written successfully; otherwise, the method returns an appropriate error code.
    */
    virtual OdResult outChildNodes(TiXmlNode* pParent);

    OdString getString(const char* buffer, const OdString& lang);
    OdResult getText(TiXmlElement* pItem, OdAnsiString& result);
    OdResult getText(TiXmlElement* pItem, const OdString& lang, OdString& result);
    void setText(TiXmlElement* pItem, const OdString& lang, const OdString& value);
    void setText(TiXmlElement* pItem, const OdString& lang, const OdAnsiString& value);

    void SetAttribute(TiXmlElement* pItem, const char* attrName, const OdAnsiString& value, bool opt = false);
    void SetAttribute(TiXmlElement* pItem, const char* attrName, const OdString& value, bool opt = false);

    void SplitToArray(const char* buffer, const char separator, OdStringArray& items);
    void SplitToArray(const char* buffer, const char separator, OdAnsiStringArray& items);
    OdString ArrayToString(const char separator, const OdStringArray& items);
    OdAnsiString ArrayToAnsiString(const char separator, const OdAnsiStringArray& items);

    OdMvdXmlRoot* m_root;
  }; 
}

#endif // !defined(ODA_ODMVDXMLELEMENT_H_INCLUDED_)