///////////////////////////////////////////////////////////////////////////////
// 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_TRAITS_H_INCLUDED_
#define _ODTV_TRAITS_H_INCLUDED_

#include "TvTraitsDef.h"
#include "TvIObject.h"

class OdTvGsViewId;

/** \details
  A data type that represents an array of OdTvGsViewId objects.
*/
typedef OdArray<OdTvGsViewId> OdTvGsViewIdsArray;

/** \details
  The abstract interface class for an object that supports work with traits.
*/
class ODTV_EXPORT OdTvTraitsIObject : public OdTvHandledIObject
{
public:

  /** \details
    Sets a new color for the object.

    \param color [in] A new color value to be set.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If a new color was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_colors, Work with Colors>
  */
  virtual OdTvResult setColor(const OdTvColorDef& color) = 0;

  /** \details
    Retrieves the current color of the 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 color represented with an <link OdTvColorDef, OdTvColorDef> object.
    \remarks
    The returned color definition object represents a color in RGB format, an inherited color, or a color index in the palette.
    If the rc parameter is not null and the current color definition object was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
    \sa
    <link tv_working_with_attributes_colors, Work with Colors>
  */
  virtual OdTvColorDef getColor(OdTvResult* rc = NULL) = 0;

  /** \details
    Sets a new  lineweight for the object.

    \param lw [in] A new lightweight definition to be set.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the new lightweight was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_lineweights, Work with Lineweights>
  */
  virtual OdTvResult setLineWeight(const OdTvLineWeightDef& lw) = 0;

  /** \details
    Retrieves the current lineweight for the 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 lineweight definition object applied to the object.
    \remarks
    If the rc parameter is not null and the current lightweight definition object was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
    \sa
    <link tv_working_with_attributes_lineweights, Work with Lineweights>
  */
  virtual OdTvLineWeightDef getLineWeight(OdTvResult* rc = NULL) = 0;

  /** \details
    Sets a new linetype for the object.

    \param lt [in] A new linetype definition object to be set.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the new linetype definition object was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_linetypes, Work with Linetypes>
  */
  virtual OdTvResult setLinetype(const OdTvLinetypeDef& lt) = 0;

  /** \details
    Retrieves the current linetype for the 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 linetype definition object applied to the object.
    \remarks
    If the rc parameter is not null and the current linetype definition object was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
    \sa
    <link tv_working_with_attributes_linetypes, Work with Linetypes>
  */
  virtual OdTvLinetypeDef getLinetype(OdTvResult* rc = NULL) = 0;

  /** \details
    Sets the linetype scale value for the group.

    \param linetypeScale  [in] A new linetype scale value.
    \returns A value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the linetype scale has been successfully applied, the method returns tvOk, otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_linetypes, Work with Linetypes>
  */
  virtual OdTvResult setLinetypeScale(double linetypeScale) = 0;

  /** \details
    Retrieves the current linetype scale of the group.

    \param rc       [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns The current linetype scale value.
    \remarks
    If the rc parameter is not null and the linetype scale value has been successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an
    appropriate error code.
    \sa
    <link tv_working_with_attributes_linetypes, Work with Linetypes>
  */
  virtual double getLinetypeScale(OdTvResult* rc = NULL) = 0;

  /** \details
    Sets a new layer for the object.

    \param layer [in] A new layer definition object to be set.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the new layer definition object was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_layers, Work with Layers>
  */
  virtual OdTvResult setLayer(const OdTvLayerDef& layer) = 0;

  /** \details
    Retrieves the current layer for the 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 layer definition object applied to the object.
    \remarks
    If the rc parameter is not null and the current layer definition object was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
    \sa
    <link tv_working_with_attributes_layers, Work with Layers>
  */
  virtual OdTvLayerDef getLayer(OdTvResult* rc = NULL) = 0;

  /** \details
    Set a new visibility property value for the object.

    \param visible [in] A new visibility definition object to be set.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the new visibility definition object was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult setVisibility(const OdTvVisibilityDef& visible) = 0;

  /** \details
    Retrieves the current visibility property value for the 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 visibility definition object applied to the object.
    \remarks
    If the rc parameter is not null and the current visibility definition object was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
  */
  virtual OdTvVisibilityDef getVisibility(OdTvResult* rc = NULL) const = 0;

  /** \details
    Sets the transparency property value for the object.

    \param transparency [in] A new transparency property value.
    \returns A value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the transparency property value has been successfully applied, the method returns tvOk; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult setTransparency(const OdTvTransparencyDef& transparency) = 0;

  /** \details
    Retrieves the transparency property value for the object.

    \param rc       [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns The current transparency property value for the object.
    \remarks
    If the rc parameter is not null and the transparency property value has been successfully returned; the rc parameter accepts the tvOk value, otherwise it contains an
    appropriate error code.
  */
  virtual OdTvTransparencyDef getTransparency(OdTvResult* rc = NULL) = 0;

  /** \details
    Sets the material for the .
    \param material [in] A material definition object.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the material has been successfully applied, the method returns tvOk; otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_materials, Work with Materials>
  */
  virtual OdTvResult setMaterial(const OdTvMaterialDef& material) = 0;

  /** \details
    Retrieves the current material applied to the .
    \param rc       [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns The current material definition for the .
    \remarks
    If the rc parameter is not null and the material definition has been successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an
    appropriate error code.
    \sa
    <link tv_working_with_attributes_materials, Work with Materials>
  */
  virtual OdTvMaterialDef getMaterial(OdTvResult* rc = NULL) const = 0;

  /** \details
    Sets a material mapper for the object. The material mapper is used to map the materials.

    \param mapper [in] A material mapper definition object to be applied.
    \returns A value of the <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If the material mapper has been successfully applied, the method returns tvOk; otherwise it returns an appropriate error code.
    \sa
    <link tv_working_with_attributes_materials_mapping, Overview of Mapping Properties>
  */
  virtual OdTvResult setMaterialMapper(const OdTvMapperDef& mapper) = 0;

  /** \details
    Retrieves the current material mapper definition that is applied to the object.
    The material mapper is used to map the materials.

    \param rc       [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns The current material mapper definition for the object.
    \remarks
    If the rc parameter is not null and the material mapper definition has been successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an
    appropriate error code.
    \sa
    <link tv_working_with_attributes_materials_mapping, Overview of Mapping Properties>
  */
  virtual OdTvMapperDef getMaterialMapper(OdTvResult* rc = NULL) const = 0;

  /** \details
    Sets new extents to the object.

    \param ext [in] A new extents object to be set.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If a new extents object was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult setExtents(const OdTvExtents3d& ext) = 0;

  /** \details
    Retrieves the current extents of a specified type for the object.

    \param ext    [out] A placeholder for current extents object.
    \param eType  [in]  A type of extents to be retrieved.
    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    The method fills the passed extents object and returns it to a calling subroutine.
    If the extents object was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult getExtents(OdTvExtents3d& ext, OdTv::ExtentsType eType = OdTv::kPreferred) const = 0;

  /** \details
    Adds a view object in which the object is displayed. By default the object is displayed in all views.

    \param viewId [in] An identifier of a view object.
    \returns A value of <link OdTvResult, OdTvResult> type that determines whether the addition of a view was successful or not.
    \remarks
    If the new view object was successfully added, the method returns the tvOk value; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult addViewDependency(const OdTvGsViewId& viewId) = 0;

  /** \details
    Removes a specified view object from the list of views in which the object can be displayed.

    \param viewId [in] An identifier of a view object that should be removed.
    \returns A value of <link OdTvResult, OdTvResult> type that determines whether the view object was successfully removed.
    \remarks
    If the specified view object was successfully removed, the method returns the tvOk value; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult removeViewDependency(const OdTvGsViewId& viewId) = 0;

  /** \details
    Removes all view dependencies of the object. This means that the object is displayed in all views.

    \returns A value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \remarks
    If all view dependencies were successfully removed, the method returns the tvOk value; otherwise it returns an appropriate error code.
  */
  virtual OdTvResult removeViewDependencies() = 0;

  /** \details
    Checks whether the object is a view-dependent object.

    The object is view dependent when it is displayed in specified views; otherwise it is view independent.
    \param rc [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns true if the object is view dependent; otherwise the method returns false.
    \remarks
    If the rc parameter is not null and the view-dependent check was successful, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
  */
  virtual bool isViewDependent(OdTvResult* rc = NULL) = 0;

  /** \details
    Retrieves the set of views in which the object is displayed, if it is view dependent.

    \param rc [out] A pointer to a value of <link OdTvResult, OdTvResult> type that contains the result of the operation.
    \returns An array of view identifiers in which the object is displayed.
    \remarks
    If the rc parameter is not null and the array of view identifiers was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
  */
  virtual OdTvGsViewIdsArray getViewDependencies(OdTvResult* rc = NULL) = 0;
};

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

#endif // _ODTV_TRAITS_H_INCLUDED_