///////////////////////////////////////////////////////////////////////////////
// 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 _ODTV_GROUP_H_INCLUDED_
#define _ODTV_GROUP_H_INCLUDED_

#include "TvSceneIObject.h"
#include "TvEntity.h"

/** \details
  This is an abstract interface class for an group object.
*/
class ODTV_EXPORT OdTvGroup : public OdTvSceneIObject
{
public:

  /** \details
    Retrieves the current name of the group object.

    \param rc [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the retrieve operation.
    \returns The current name of the group object.
    \remarks
    The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
    underscores, and some special characters, but cannot contain inadmissible letters
    ("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
    If the rc parameter is not null and the group object name was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
  */
  virtual OdString getName(OdTvResult* rc = NULL) const = 0;

  /** \details
    Sets a new name for the group object.

    \param sName [in]  A new name of the group object.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
    underscores, and some special characters, but cannot contain inadmissible letters
    ("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
    If the new name of the group object was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult setName(const OdString& sName) = 0;

  /** \details
    Appends an entity object to the group and returns the identifier of the appended entity.

    \param name [in] A name of the entity.
    \param rc   [out] A pointer to a value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns An identifier for the appended entity if it is successfully added, otherwise returns a null identifier.
    \remarks
    If the rc parameter is not null and the entity is created and added to the group, the rc parameter accepts the tvOk value,
    otherwise it contains an appropriate error code.
  */
  virtual OdTvEntityId appendEntity(OdString name = OdString::kEmpty, OdTvResult* rc = NULL) = 0;

  /** \details
    Appends an insert entity object to the group and returns the identifier of the appended insert entity.

    \param blockId  [in] An identifier of the block that should contain the appended insert object.
    \param name     [in] A name of the insert object.
    \param rc       [out] A pointer to a value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns An identifier for the appended insert entity if it is successfully added, otherwise returns a null identifier.
    \remarks
    If the rc parameter is not null and the insert entity is created and added to the group, the rc parameter accepts the tvOk value,
    otherwise it contains an appropriate error code.
  */
  virtual OdTvEntityId appendInsert(const OdTvBlockId& blockId, OdString name = OdString::kEmpty, OdTvResult* rc = NULL) = 0;
  
  /** \details
    Appends a group object to the group and returns the identifier of the appended group entity.

    \param name [in] A name of the group.
    \param rc   [out] A pointer to a value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns An identifier for the appended group if it is successfully added, otherwise returns a null identifier.
    \remarks
    If the rc parameter is not null and the group is created and added to the group, the rc parameter accepts the tvOk value,
    otherwise it contains an appropriate error code.
  */
  virtual OdTvEntityId appendGroup(OdString name = OdString::kEmpty, OdTvResult* rc = NULL) = 0;

  /** \details
    Removes an entity object, specified by its identifier, from the group.

    \param id [in] An identifier of the entity object.
    \returns A value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the entity specified by its identifier is found and removed from the group, the method returns the tvOk, otherwise it returns an appropriate error code.
  */
  virtual OdTvResult removeEntity(const OdTvEntityId& id) = 0;

  /** \details
    Retrieves a smart pointer to the entity iterator.
    The entity iterator provides sequential access to entities that the group contains.

    \param rc [out] A pointer to a value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns A smart pointer to the entity iterator. If the group contains no entities, the method returns a null smart pointer.
    \remarks
    If the rc parameter is not null and the smart pointer to the entity iterator is successfully returned, the rc parameter accepts the tvOk value, otherwise it contains an
    appropriate error code.
  */
  virtual OdTvEntitiesIteratorPtr getEntitiesIterator(OdTvResult* rc = NULL) const = 0;

  /** \details
  Returns true if and only if the group has no sub groups, entities or inserts.

  \param rc  [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
  \returns true if and only if the group has no sub groups, entities or inserts.
  \remarks
  If the rc parameter is not null and the flag value has been successfully returned, the rc parameter accepts tvOk value; otherwise it contains an
  appropriate error code.
  */
  virtual bool isEmpty(OdTvResult* rc = NULL) const = 0;

  /** \details
    Sets a new visual style for the group. The visual style should be compatible with the visual style assigned to the view.
    This functionality should be used very carefully. The typical case for it is the customization of the highlighting.

    \param vsId [in] An identifier of the visual style object.
    \returns A value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the visual style was successfully applied, the method returns tvOk; otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_visual_styles, Work with Visual Styles>
  */
  virtual OdTvResult setVisualStyle(const OdTvVisualStyleId& vsId) = 0;

  /** \details
    Retrieves the current visual style applied to the group.

    \param rc [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns The identifier of the current visual style object associated with the group.
    \remarks
    If the rc parameter is not null and the new visual style object's identifier was successfully returned, the rc parameter accepts the tvOk value;
    otherwise it contains an appropriate error code.
    \sa
    <link tv_working_with_attributes_visual_styles, Work with Visual Styles>
  */
  virtual OdTvVisualStyleId getVisualStyle(OdTvResult* rc = NULL) const = 0;

  /** \details
    Copies all groups's data to a specified group (attributes, entites etc).
    All current data in the target group will be deleted or overwritten.

    \param targetGroupId [in] A target <link OdTvEntityId, group identifier>. The data will be copied to the group the identifier refers.
    \returns A value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the operation was successfully performed, the method returns tvOk; otherwise it returns an appropriate error code.
    This function is designed for copying groups within the same database. If source and destination groupss belong to different databases
    default OdTvAttributeResolver will be created and used. Using copyTo(OdTvEntityId& targetGroupId, OdTvAttributeResolverPtr pResolver) will be
    more optimal in this case.
  */
  virtual OdTvResult copyTo(OdTvEntityId& targetGroupId) const = 0;

  /** \details
    Copies all groups's data to a specified group (attributes, entites etc).
    All current data in the target group will be deleted or overwritten.

    \param targetGroupId [in] A target <link OdTvEntityId, group identifier>. The data will be copied to the group the identifier refers.
    \param pResolver      [in] A smart pointer to the instance of OdTvAttributeResolver.
    \returns A value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the operation was successfully performed, the method returns tvOk; otherwise it returns an appropriate error code.
    This function is designed for copying groups from different databases. If source and destination groups belong to the same database using
    copyTo(OdTvEntityId& targetGroupId) will be more optimal.
  */
  virtual OdTvResult copyTo(OdTvEntityId& targetGroupId, OdTvAttributeResolverPtr pResolver) const = 0;
};

/** \details
  A data type that represents a smart pointer to an <link OdTvGroup, OdTvGroup> object.
*/
typedef OdTvSmartPtr<OdTvGroup> OdTvGroupPtr;

#endif // _ODTV_GROUP_H_INCLUDED_