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

#include "TD_PackPush.h"

#include "DbBlockElement.h"
#include "DbEvalGraph.h"
#include "Ge/GeMatrix3d.h"
#include "DbDynBlockReference.h"
#include "DbEvalVariant.h"

class OdDbBlockGrip;
typedef OdSmartPtr<OdDbBlockGrip> OdDbBlockGripPtr;
typedef OdArray< OdDbBlockGripPtr, OdObjectsAllocator<OdDbBlockGripPtr> > OdDbBlockGripPtrArray;

/** \details
  A structure describing a block parameter property.
  <group !!RECORDS_tdrawings_apiref>
*/
struct DYNBLOCKS_EXPORT OdDbBlkParamPropertyDescriptor
{
  OdString m_sName;               //< Property name
  OdString m_sConnection;         //< Property connection string
  DwgDataType m_nType = kDwgNull; //< Type of the property value
  bool m_bReadonly = false;       //< If the property is read-only
  bool m_bVisible = true;         //< If the property is visible to the user
  OdString m_sDescription;        //< Readable description
  bool m_bListPresent = false;    //< If true then *m_pAllowedValues* should be used
  OdDbDynBlockReferenceProperty::UnitsType m_nUnitsType = OdDbDynBlockReferenceProperty::kNoUnits; //< property value units type
  OdDbEvalVariantArray m_pAllowedValues; //< List of the allowed value for this property (valid if *m_bListPresent* is set)
};
typedef OdArray< OdDbBlkParamPropertyDescriptor > OdDbBlkParamPropertyDescriptorArray;

/** \details
    This is a base class for the dynamic block parameters.

    <group OdDb_Classes>
*/
class DYNBLOCKS_EXPORT OdDbBlockParameter : public OdDbBlockElement
{
public:
  ODDB_EVAL_DECLARE_MEMBERS(OdDbBlockParameter);

  /** \details
  * Enum used to identify parameter components. Grip points and actions always correspond to some component.
  */
  enum ParameterComponent
  {
    Base, //< Component corresponding to the parameter base point (for OdDbBlock1PtParameter this is the only valid component)
    End, //< Component corresponding to the parameter end point 
    BaseXEndY, //< Component corresponding to the combined point (base.x, end.y), actual e.g. for OdDbBlockXYParameter
    EndXBaseY, //< Component corresponding to the combined point (end.x, base.y), actual e.g. for OdDbBlockXYParameter
    InvalidComponent //< enum value indicating invalid component 
  };

  /** \details
    Notification function called whenever this Node object has been removed a Graph object.

    \param pGraph [in]  Pointer to the Graph object.

    \remarks
    Called by OdDbEvalGraph::removeNode().

    This function is called after the operation.
  */
  void removedFromGraph(OdDbEvalGraph*) override;

  /** \details
  * Returns the connection string for the given property name (empty if not found)
  */
  virtual OdString getPropertyConnectionName(const OdString&) const;

  /** \details
  * Returns the list of the property descriptors for this parameter
  */
  virtual void getPropertyDescription(OdDbBlkParamPropertyDescriptorArray&) const;

  /** \details
   Returns the value of a property with a given name
    \param name [in] Name of the property
    \remarks
    This function will return an empty OdDbEvalVariant() if the given name is not supported
  */
  virtual OdDbEvalVariant getPropertyValue(const OdString& name) const;

  /** \details
   Returns the value of a property with a given name
    \param name [in] Name of the property
    \param matrix [in] Block reference matrix (used to transform the values from the block space)
    \remarks
    This function will return an empty OdDbEvalVariant() if the given name is not supported
  */
  virtual OdDbEvalVariant getPropertyValue(const OdString& name, const OdGeMatrix3d& matrix)const;
  
  /** \details
  * Sets the value of a property with a given name
    \param name [in] Name of the property
  */
  virtual OdResult setPropertyValue(const OdString& name, const OdDbEvalVariant& value);
  
  /** \details
   Sets the value of a property with a given name
    \param name [in] Name of the property
    \param matrix [in] Block reference matrix (used to transform the values from the block space)
  */
  virtual OdResult setPropertyValue(const OdString& name, const OdGeMatrix3d& matrix, const OdDbEvalVariant& value);

  /** \details
  * Notification called when a grip points is erased
  */ 
  virtual void gripErased(ParameterComponent);
  
  /** \details
  * Returns a list of existing grip points for this parameter
  */
  void getGrips(OdDbBlockGripPtrArray&, OdDb::OpenMode = OdDb::kForRead);

  /** \details
  * Returns the number of grip points that may directly affect this parameter
  */
  virtual int getNumberOfGrips() const;

  /** \details
  * Returns a *ParameterComponent* identifier for a given grip id
  */
  virtual ParameterComponent getComponentForGrip(OdDbEvalNodeId);

  /** \details
  * Removes the grip point corresponding to a certain parameter
  */
  virtual void removeGrip(ParameterComponent);

  /** \details
  * Resets the grip points to a default state
  */
  virtual void resetGrips();

  /** \details
  * Sets the number of grips for this parameter
  */
  virtual void setNumberOfGrips(int);

  /** \details
  * Returns true if this parameter will trigger dependent actions when being indirectly affected by other actions
  */
  virtual bool chainActions()const;

  /** \details
  * Sets if this parameter will trigger dependent actions when being indirectly affected by other actions
  * Returns true if successfull. May fail if setting it will cause evaluation cycles.
  */
  virtual bool setChainActions(bool);

  /** \details
  * Returns true if this parameter properties should be shown in UI
  */
  virtual bool showProperties()const;

  /** \details
  * Set if this parameter properties should be shown in UI
  */
  virtual void setShowProperties(bool);

  /** \details
  * Add a grip point for a given component
  */
  OdDbEvalNodeId addGrip(ParameterComponent);

  /** \details
  * Return optional hint for positioning properties of this parameter in UI (0 by default)
  */
  OdInt16 orderInPropertyPalette();

  /** \details
  * Set optional hint for positioning properties of this parameter in UI (0 by default)
  */
  void setOrderInPropertyPalette(OdInt16 order);

  /** \details
   Checks if the given label is unique within the graph
   \param graph [in] Evaluation graph to check
   \param label [in] String to search for
   \param suffix [inout, optional] If suffix is passed in, it is set to the unique label by appending a digital index
   \returns Returns true if the given label is unique
  */
  static bool isPropertyLabelUnique(OdDbEvalGraph* graph, const OdString& label, OdString* suffix = nullptr);
  
  /** \details
  * Returns parameter description string
  */
  OdString toolTipString() const;
};

typedef OdSmartPtr<OdDbBlockParameter>OdDbBlockParameterPtr;

#include "TD_PackPop.h"

#endif // _DbBlockParameter_h_Included_