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

#ifndef _PRCATTRIBUTE_INCLUDED_
#define _PRCATTRIBUTE_INCLUDED_ 
 

#include "PrcAttributeEntry.h"
#include "PrcContentSingleAttribute.h"

/** \details
The structure stores special external data that should be written to an <link OdPrcAttribute, attribute>. 
Special data can be read only by an external application. 
To determine the application to read the attribute data, PRC SDK uses the default application identifier. 
The application ID is stored in the <link OdPrcFileStructure, file structure> the <link OdPrcAttribute, attribute> belongs to.
The default application ID can be reset with a custom application ID.
<group PRC_Datatypes_Classes> 
*/
struct PRC_TOOLKIT OdPrcAttributeExternal
{
  /** \details
  Creates a new instance of the external attribute data (default constructor). 
  */
  OdPrcAttributeExternal ();

  /** \details
  Creates a new instance of the external attribute data with specified parameters.
  \param entryName  [in] A <exref target="https://docs.opendesign.com/tkernel/OdString.html">string</exref> that contains the name of the attribute entry to create.
  \param data       [in] The special data to store.
  */
  OdPrcAttributeExternal (const OdString &entryName, OdInt32 data);

  /** \details
  Checks whether the special data stored in the external attribute data instance is valid.
  \returns The true value if the data is valid; otherwise, the method returns false.
  */
  bool isValid(void) const;

  /** The name of the attribute entry.*/
  OdString  entryName;
  
  /** Special data of the attribute.*/
  OdInt32       data;  
  
  /** A flag that indicates whether the application ID for the attribute is the same as the application ID for the parent 
  <link OdPrcFileStructure, file structure> (equals true) or is different (equals false).*/
  bool          useSameAppIDAsFileStructure;
  
  /** An identifier for part 1.*/
  OdInt32       IDPart1;
  
  /** An identifier for part 2.*/
  OdInt32       IDPart2;
  
  /** An identifier for part 3.*/
  OdInt32       IDPart3;
  
  /** An identifier for part 4.*/
  OdInt32       IDPart4; 
};

/** \details 
A class that implements a repository for attribute data. Attribute data repository contains a title and a variable number of key-value pairs.
<group PRC_Datatypes_Classes> 
*/
class PRC_TOOLKIT OdPrcAttribute
{
private:
  OdPrcContentSingleAttributeArray  m_ContentSingleAttribute;
  OdPrcAttributeEntry               m_AttributeEntry;

public:
  //DOM-IGNORE-BEGIN
  PRC_DECLARE_CIO(OdPrcAttribute)
  //DOM-IGNORE-END

  /** \details
    Requests the current <link OdPrcContentSingleAttributeArray, array of single attributes>.
    \returns The current <link OdPrcContentSingleAttributeArray, array of single attributes>.
    \remarks 
    The method returns an <link OdPrcContentSingleAttributeArray, array of single attributes> via a reference; 
    therefore, it can be used to set a new single attribute array and affect the attribute object.
  */
  OdPrcContentSingleAttributeArray &contentSingleAttribute();

  /** \details
    Requests the current <link OdPrcContentSingleAttributeArray, array of single attributes>.
    \returns A constant reference to the current <link OdPrcContentSingleAttributeArray, array of single attributes>.
    \remarks 
    Call this method if you want to restrict modifications of the <link OdPrcContentSingleAttributeArray, array of single attributes> outside the attribute object.
  */
  const OdPrcContentSingleAttributeArray &contentSingleAttribute() const;

  /** \details
    Requests the current <link OdPrcAttributeEntry, attribute entry>.
    \returns The current <link OdPrcAttributeEntry, attribute entry> object. 
    \remarks 
    The method returns the <link OdPrcAttributeEntry, attribute entry> object via a reference;
    therefore, any modification of the returned <link OdPrcAttributeEntry, attribute entry> affects the attribute object.
  */
  OdPrcAttributeEntry &attributeEntry();

  /** \details
    Requests the current <link OdPrcAttributeEntry, attribute entry>.
    \returns A constant reference to the current <link OdPrcAttributeEntry, attribute entry> object.
    \remarks 
    Call this method if you want to restrict modifications of the <link OdPrcAttributeEntry, attribute entry> outside the attribute object.
  */
  const OdPrcAttributeEntry &attributeEntry() const;

  /** \details
    Sets a new value of the reserved attribute.
    \param data [in] A new value for the reserved attribute.
  */  
  void setReservedAttribute(const OdPrcAttributeExternal &data);

  /** \details
    Requests the current type of the PRC object.
    \returns An unsigned 32-bit integer value that contains the type of the PRC object.
  */
  OdUInt32 prcType() const;

  /** \details 
  Creates the attribute title and sets its text.
  \param attrTitle [in] A attribute entry that represents the new title to be set.
  */
  void SetTitle (const OdPrcAttributeEntry &attrTitle);

  /** \details 
  Add pair data to the attribute. Pair data contains an attribute title and data. 
  \param attrPair [in] A pair data to be added.
  */
  void AddDataPair (const OdPrcContentSingleAttribute &attrPair);

  /** \details 
  Clears the attribute. 
  \remarks 
  The method flushes the array of data fields stored in the attribute.
  */
  void ClearAttribute (void);
};
  
/** \details 
A data type that represents an <exref target="https://docs.opendesign.com/tkernel/OdArray@classT@classA.html">array</exref> of <link OdPrcAttribute, OdPrcAttribute> objects.
*/
typedef OdArray<OdPrcAttribute> OdPrcAttributeArray;

#endif // _PRCATTRIBUTE_INCLUDED_