/////////////////////////////////////////////////////////////////////////////// // 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 DbAssocVariable_INCLUDED_ #define DbAssocVariable_INCLUDED_ /*!DOM*/ #include "DbConstraintsExports.h" #include "DbAssocValueProviderPE.h" #include "DbAssocAction.h" #include "OdString.h" #include "BoolArray.h" #include "DoubleArray.h" #include "Int16Array.h" #include "DbEvalVariant.h" #include "TD_PackPush.h" /** \details This class represents the variable which stores a scalar value of following types: double, int, or string. The value may be either a constant or be defined by an expression. The expression can refer to other symbols which the evaluate() method of the variable can transform to the evaluated value using the current values of the referenced symbols. Library: Source code provided. */ class DBCONSTRAINTS_EXPORT OdDbAssocVariable : public OdDbAssocAction { public: ODRX_DECLARE_MEMBERS(OdDbAssocVariable); /** \details Constructor creates an instance of this class. */ OdDbAssocVariable(); /** \details Returns the variable name as an arbitrary string. */ const OdString name() const; /** \returns Returns true if the variable name is empty or starts from *. */ bool isAnonymous() const; /** \details Returns the expression as an arbitrary string or an empty string if the variable is a constant. */ const OdString expression() const; /** \details Returns the evaluated value of the variable. */ const OdDbEvalVariantPtr value() const; /** \details Returns the variable description as an arbitrary string. */ const OdString description() const; /** \details Sets the name for this variable using a given string. */ OdResult setName(const OdString newName, bool updateReferencingExpressions); /** \details Searches the object using its name and returns an object ID if the object is found or kNull if the object is not found. */ OdDbObjectId findObjectByName(const OdString& objectName, const OdRxClass* pObjectClass) const; /** \details Validates the given name, expression or both, to check whether they can be used for this variable. It checks that the given name is a valid identifier and not duplicates any other variable name (in the same network). It checks syntax of the given expression, checks for undefined symbols references and checks for cyclic dependencies. After checks above pass it calls OdDbAssocVariableCallback::validateNameAndExpression() to perform additional validation by client code. \param nameToValidate [in] name to validate. Empty string means that name is not going to change. \param expressionToValidate [in] expression to validate. Empty string means that expression is not going to change. \param errorMessage [out] optional pointer to string to return error message. \returns eOk if the name and expression can be set to this variable. Otherwise returns an OdResult and explanation of the error in errorMessage. */ OdResult validateNameAndExpression(const OdString& nameToValidate, const OdString& expressionToValidate, OdString* errorMessage = 0) const; /** \details Sets the expression as a string and syntactically checks it. \param newExpression [in] new expression or empty string for no expression. \param evaluatorId [in] identifier of expression evaluator or empty string to use default evaluator. \param checkForCyclicalDependencies [in] tells to checks if there is a cyclical dependency between the variables. \param updateDependenciesOnReferencedSymbols [in] if true the OdDbAssocValueDependencies on the symbols referenced by the old expression are erased and new OdDbAssocValueDependencies on the symbols referenced by the new expression will be set up. \param errorMessage [out] optional pointer to string that contains error description if the function failed. \param silentMode [in] optional flag that tells application to do not display error message boxes. \remarks Only "AcDbCalc:1.0" evaluator is currently supported. Currently silentMode parameter is not used. */ OdResult setExpression(const OdString& newExpression, const OdString& evaluatorId, bool checkForCyclicalDependencies, bool updateDependenciesOnReferencedSymbols, OdString* errorMessage = 0, bool silentMode = false); /** \details Returns the ID of the expression evaluator for parsing the expression. */ const OdString evaluatorId() const; /** \details Sets the given ID of the expression evaluator to be used for parsing the expression. An empty string sets the default evaluator. */ OdResult setEvaluatorId(const OdString evalId); /** \details Sets the evaluated value. If the expression is not empty, this value will be overwritten and the expression will be evaluated. */ OdResult setValue(const OdDbEvalVariant& newValue); /** \details Sets the description for this variable as a string value. */ OdResult setDescription(const OdString newDescription); /*!DOM*/ bool isMergeable () const; /*!DOM*/ bool mustMerge () const; /*!DOM*/ OdString mergeableVariableName() const; /*!DOM*/ void setIsMergeable(bool isMerg, bool mustMerg = false, const OdString mergeableVariableName = OdString()); /** \details Evaluates the expression without modifying the variable. \param evaluatedExpressionValue [out] result of evaluation. \param errorMessage [out] optional pointer to string that contains error description if the function failed. */ OdResult evaluateExpression(OdDbEvalVariant* evaluatedExpressionValue, OdString* errorMessage = 0) const; /** \details Evaluates the expression without modifying the variable using explicitly providing values of the referenced value-providing objects. \param objectIds [in/out] value-providing objects ids. May be empty on input. \param objectValues [in/out] values of value-providing objects. May be empty on input. \param evaluatedExpressionValue [out] result of evaluation. \param errorMessage [out] optional pointer to string that contains error description if the function failed. \remarks The expression is evaluated using the provided values of the referenced objects. The objectIds array is an array of ids of value-providing objects (such as OdDbAssocVariables) and objectValues is an array of provided values of these objects. These arrays have the same lengths. If id of this variable is already in objectIds array, then the corresponding value from objectValues is returned. Otherwise the expression of this variable is evaluated, the variable id is added to objectIds array and value is added to objectValues array so the same variable not evaluated again during the expression evaluation. This function is recursively called for every symbol referenced by the expression. */ OdResult evaluateExpression(OdDbObjectIdArray& objectIds, OdArray& objectValues, OdDbEvalVariant* evaluatedExpressionValue, OdString* errorMessage = 0) const; /** \details Evaluates the expression in the context of the given OdDbAssocNetwork. \param evaluatorId [in] identifier of expression evaluator or empty string to use default evaluator. \param networkId [in] provides context for the names. \param evaluatedExpressionValue [out] result of evaluation. \param assignedToSymbolName [out] optional, reserved; do not use \param errorMessage [out] optional pointer to string that contains error description if the function failed. \remarks Only "AcDbCalc:1.0" evaluator is currently supported. */ static OdResult evaluateExpression(const OdString& expression, const OdString& evaluatorId, const OdDbObjectId& networkId, OdDbEvalVariant* evaluatedExpressionValue, OdString* assignedToSymbolName = 0, OdString* errorMessage = 0); /** \details Adds the global variable callback object. \remarks The client code can register callback(s) derived from associated callback that are then called when some events are triggered for variables. \param pCallback [in] callback object pointer to add. */ static void addGlobalCallback(class OdDbAssocVariableCallback* pCallback); /** \details Removes the global variable callback object. \param pCallback [in] callback object pointer to remove. */ static void removeGlobalCallback(class OdDbAssocVariableCallback* pCallback); /** \details Returns the global callback that is the collection of all callbacks registered by client code. */ static class OdDbAssocVariableCallback* globalCallback(); /** \details Overrides OdDbObject's method. \sa */ virtual void appendToOwner(OdDbIdPair& idPair, OdDbObject* pOwnerObject, OdDbIdMapping& idMap); }; /** \details The typified smart pointer. This template class is specialization of the OdSmartPtr class for the OdDbAssocVariable class. \sa */ typedef OdSmartPtr OdDbAssocVariablePtr; /** \details This class represents the associated callback. The client code can register callback(s) derived from associated callback that are then called when some events are triggered for variables. Library: Source code provided. */ class OdDbAssocVariableCallback { public: /** \details Constructor creates an instance of this class. */ OdDbAssocVariableCallback() {} /** \details Destructor destroys an instance of this class. */ virtual ~OdDbAssocVariableCallback() {} /** \details Checks whether the client code permits or forbids the erasing of callbacks. */ virtual bool canBeErased(const OdDbAssocVariable* pVariable) = 0; /** \details This method is called from the validateNameAndExpression() method of the associated variable object. This method assumes the client code perform additional testing to decide if a given name or expression are allowed to be used for the given variable. \param pVariable [in] the variable object from which the callback is called. \param nameToValidate [in] name to validate. \param expressionToValidate [in] expression to validate. \param errorMessage [out] optional pointer to string to return error message. \returns eOk if the name and expression can be set to this variable. Otherwise returns an OdResult and explanation of the error in errorMessage. */ virtual OdResult validateNameAndExpression(const OdDbAssocVariable* pVariable, const OdString& nameToValidate, const OdString& expressionToValidate, OdString* errorMessage = 0) = 0; }; /** \details This class represents the implementation of the associated value provider protocol extension to obtain the value of an associated variable. Library: Source code provided. */ class OdDbAssocVariableValueProviderPE : public OdDbAssocValueProviderPE { public: ODRX_DECLARE_MEMBERS(OdDbAssocVariableValueProviderPE); #if 0 /** \details Gets the value of the given variable using its name and pointer to the object. */ virtual OdResult getValue(const OdDbObject* pObject, const OdString valueName, OdDbEvalVariant& value); #endif }; /** \details The typified smart pointer. This template class is specialization of the OdSmartPtr class for the OdDbAssocVariableValueProviderPE class. \sa */ typedef OdSmartPtr OdDbAssocVariableValueProviderPEPtr; #include "TD_PackPop.h" #endif