///////////////////////////////////////////////////////////////////////////////
|
// Copyright (C) 2002-2016, 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 Teigha(R) software pursuant to a license
|
// agreement with Open Design Alliance.
|
// Teigha(R) Copyright (C) 2002-2016 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 _FdField_h_Included_
|
#define _FdField_h_Included_
|
|
#include "RxObject.h"
|
#include "RxDictionary.h"
|
#include "DbField.h"
|
|
class OdDbField;
|
class OdDbEvalVariant;
|
class OdFieldValue;
|
class OdFdFieldEngineImpl;
|
class OdFdFieldResult;
|
class OdDbDatabase;
|
|
#include "TD_PackPush.h"
|
|
/** \details
|
This class is an abstract base class that defines the field evaluator interface.
|
\remarks
|
Applications implement evaluators for fields by deriving from this class.
|
The evaluator object instantiated from this class is obtained from the field
|
evaluator loader using the evaluator ID stored in the field. An evaluator class
|
can be implemented for each type of field, or a single evaluator class can support
|
multiple types of fields.
|
<group Other_Classes>
|
*/
|
class TOOLKIT_EXPORT OdFdFieldEvaluator : public OdRxObject
|
{
|
public:
|
ODRX_DECLARE_MEMBERS(OdFdFieldEvaluator);
|
|
/** \details
|
Returns the evaluator IDs supported by this evaluator.
|
\remarks
|
This function can return more than one evaluator ID if the evaluator
|
supports multiple IDs. If more than one ID is returned, the evaluator
|
IDs are separated by commas.
|
*/
|
virtual const OdString evaluatorId() const = 0;
|
/** \details
|
Returns the evaluator ID for the specified field code.
|
\remarks
|
This version will be called to find an evaluator for a field code
|
that does not have an evaluator ID set. Implementations of this function
|
should examine the field code. If the field code is recognized by the evaluator
|
and can be handled by it, then this function should return the evaluator ID.
|
\param pField [in] Input field for which to return an evaluator ID
|
*/
|
virtual const OdString evaluatorId(OdDbField* pField) const = 0;
|
/** \details
|
This function is called by the
|
field framework calls this method to initialize a new field.
|
\remarks
|
This method is called after setting a field code in the field and
|
before compile() is called. The evaluator can change the default
|
options that are set in the field when it is created. This method
|
will be called only once for a field.
|
\param pField [in] Input field to initialize
|
*/
|
virtual OdResult initialize(OdDbField* pField) const = 0;
|
|
// The field framework calls this method to compile a field when the field code is changed.
|
|
/** \details
|
This function is called by the frame framework
|
to compile a field when the field code is changed.
|
\remarks
|
The evaluator can do any parsing of the field code here and store the parsed data in the
|
field. This method will be called only when the field code is changed, unlike evaluate(),
|
which is called whenever the field needs to be evaluated.
|
\param pField [in] Input field to compile
|
\param pDb [in] Input database pointer
|
\param pResult [in] Input field result object to set the compilation status
|
*/
|
virtual OdResult compile(OdDbField* pField,
|
OdDbDatabase* pDb,
|
OdFdFieldResult* pResult) const = 0;
|
|
// The field framework calls this method to evaluate a field whenever the field needs
|
// to be evaluated.
|
|
/** \details
|
This function is called by the field framework when the field needs to be evaluated.
|
\remarks
|
A field will be evaluated only when the evaluation option set in
|
the field matches the context in which the field evaluation is invoked. For example,
|
if a field option is set to evaluate only manually, then it will be evaluated only
|
when the user updates the specific field or all fields in the drawing manually.
|
|
The evaluator should evaluate the field and set the evaluated value using
|
OdFdFieldResult::setFieldValue() and the error status using OdFdFieldResult::setEvaluationStatus()
|
in the passed result object, which in turn will set them in the field object.
|
|
The passed database pointer may be null if the field is not database resident and a
|
database could not be obtained in the current context. If the field evaluation requires
|
a database, then this method can set the evaluation error status in the field result object
|
and return an error.
|
|
If the evaluation fails for any reason, the previously cached result in the field object can
|
be left intact and used as the field value. Alternatively, the cached result can be deleted
|
and substituted with an error string (for example, "#ERR"), which will be displayed as field
|
value.
|
|
\param pField [in] Input field to evaluate
|
\param nContext [in] Input context in which the field is evaluated; this context flag is passed to the evaluator and can be one of the predefined OdDbField::EvalContext enum flags or a user-defined context flag
|
\param pDb [in] Input database pointer, which can be null if a database could not be obtained in the current context
|
\param pResult [in] Input field result object to set the evaluation result and status
|
*/
|
virtual OdResult evaluate(OdDbField* pField,
|
int nContext,
|
OdDbDatabase* pDb,
|
OdFdFieldResult* pResult) const = 0;
|
|
// The field framework calls this method when a field is queried
|
// to get the evaluated field value as a string. The evaluator can
|
|
/** \details
|
This function is called by the field framework
|
when a field is queried to get the evaluated field value as a string.
|
\remarks
|
The evaluator can
|
implement this method to support custom formatting of field values.
|
If the evaluator does not implement this method, the standard data types will
|
be formatted using default formats.
|
|
\param pField [in] Field whose value is to be formatted
|
\param pszValue [out] Pointer to the string that is the field value formatted as a string
|
*/
|
virtual OdResult format(OdDbField* pField, OdString& pszValue) const = 0;
|
};
|
|
typedef OdSmartPtr<OdFdFieldEvaluator> OdFdFieldEvaluatorPtr;
|
|
/** \details
|
This class is used to load the evaluators required for evaluating fields.
|
\remarks
|
This class acts as the interface between the field framework and the applications
|
that implement evaluators. An application that implements evaluators should derive
|
from this class and register an object of this class with the field engine when
|
the application is loaded. The registered loader is used by the engine to obtain
|
the evaluator object. Only one loader object is required for an application and
|
it can support multiple evaluators. The loader objects are maintained globally and
|
are used by all open documents.
|
<group Other_Classes>
|
*/
|
class TOOLKIT_EXPORT OdFdFieldEvaluatorLoader : public OdRxObject
|
{
|
public:
|
ODRX_DECLARE_MEMBERS(OdFdFieldEvaluatorLoader);
|
|
/** \details
|
The field engine calls this method to get the evaluator using the evaluator ID
|
and uses the evaluator to evaluate the field.
|
\param pszEvalId [in] Input evaluator ID for which the evaluator is required
|
*/
|
virtual OdFdFieldEvaluator* getEvaluator(
|
const OdString& pszEvalId) = 0;
|
|
/** \details
|
Finds an evaluator for a field that does not have an evaluator ID.
|
\param pField [in] Input field for which to find an evaluator
|
\param pszEvalId [out] Output pointer to receive the evaluator ID
|
*/
|
virtual OdFdFieldEvaluator * findEvaluator(
|
OdDbField* pField,
|
OdString& pszEvalId) = 0;
|
};
|
|
/** \details
|
This class is used to get notifications when fields in a database are evaluated.
|
<group Other_Classes>
|
*/
|
class TOOLKIT_EXPORT OdFdFieldReactor : public OdRxObject
|
{
|
public:
|
ODRX_DECLARE_MEMBERS(OdFdFieldReactor);
|
|
/** \details
|
Notification function called before one or more fields in a database are evaluated.
|
\param nContext [in] Input evaluation context
|
\param pDb [in] Input pointer to database in which the fields are evaluated
|
*/
|
virtual void beginEvaluateFields(
|
int nContext,
|
OdDbDatabase* pDb);
|
|
/** \details
|
Notification function called after one or more fields in a database are evaluated.
|
\param nContext [in] Input evaluation context
|
\param pDb [in] Input pointer to database in which the fields are evaluated
|
*/
|
virtual void endEvaluateFields(
|
int nContext,
|
OdDbDatabase* pDb);
|
};
|
|
typedef OdArray<OdFdFieldReactor*> FieldReactors;
|
|
/** \details
|
This class manages the evaluation of fields.
|
\note
|
The field engine is a global one-per-session object.
|
|
The field evaluators should register their loader with
|
the engine during application startup
|
<group Other_Classes>
|
*/
|
class TOOLKIT_EXPORT OdFdFieldEngine : public OdRxObject
|
{
|
public:
|
ODRX_DECLARE_MEMBERS(OdFdFieldEngine);
|
virtual ~OdFdFieldEngine(){}
|
/** \details
|
Registers the evaluator loader with the engine.
|
\remarks The engine searches the registered
|
evaluator loaders to find the appropriate evaluator for evaluating fields. Field
|
evaluators should register the evaluator loader with the field engine during application
|
startup.
|
\param pLoader [in] Input evaluator loader to register
|
*/
|
virtual void registerEvaluatorLoader(OdFdFieldEvaluatorLoader* pLoader) = 0;
|
|
/** \details
|
Unregisters the evaluator loader from the engine.
|
\remarks
|
Field evaluator modules
|
should unregister the evaluator loader when the module is unloaded,
|
before deleting the loader object.
|
\param pLoader [in] Input evaluator loader to unregister
|
*/
|
virtual void unregisterEvaluatorLoader(OdFdFieldEvaluatorLoader* pLoader) = 0;
|
|
/** \details
|
Returns the number of registered field evaluator loaders.
|
*/
|
virtual int evaluatorLoaderCount() const = 0;
|
|
/** \details
|
Returns the field evaluator loader at the specified index.
|
\remarks
|
This function can be used with evaluatorLoaderCount() to
|
enumerate the evaluator loaders.
|
\param inputIndex [in] Input index for which to get the field evaluator loader; the index is zero based and should be less than the number of registered evaluator loaders.
|
*/
|
virtual OdFdFieldEvaluatorLoader * getEvaluatorLoader(int inputIndex) = 0;
|
|
/** \details
|
Returns the field evaluator for the specified evaluator ID.
|
\remarks
|
Returns null if a field evaluator could not be found for the evaluator ID.
|
\param pszEvalId [in] Input evaluator ID for which to find the field evaluator
|
*/
|
virtual OdFdFieldEvaluator * getEvaluator (
|
const OdString& pszEvalId) = 0;
|
|
/** \details
|
Returns an an evaluator for the specified field from the set of registered evaluators
|
if the field does not have an evaluator ID.
|
\param pField [in] Input field for which to find an evaluator
|
\param pszEvalId [out] Output pointer to receive the evaluator ID
|
\remarks
|
Returns the field evaluator for the specified field, or
|
null if a field evaluator could not be found.
|
|
*/
|
virtual OdFdFieldEvaluator * findEvaluator(
|
OdDbField* pField,
|
OdString& pszEvalId) = 0;
|
|
/** \details
|
Adds the field reactor to the field framework.
|
\param pReactor [in] Input pointer to the reactor to be added
|
*/
|
virtual void addFieldReactor(OdFdFieldReactor* pReactor) = 0;
|
|
/** \details
|
Removes the field reactor from the field framework.
|
\param pReactor [in] Input pointer to field reactor to remove
|
*/
|
virtual void removeFieldReactor(OdFdFieldReactor* pReactor) = 0;
|
};
|
|
typedef OdSmartPtr<OdFdFieldEngine> OdFdFieldEnginePtr;
|
#define ODFD_FIELD_ENGINE OD_T("FieldEngine")
|
/** \details
|
Returns the pointer to the field engine. There is only one field engine object per session.
|
*/
|
TOOLKIT_EXPORT OdFdFieldEnginePtr oddbGetFieldEngine();
|
|
/** \details
|
This class is used by the evaluators to set the evaluation status and
|
evaluation result in the field.
|
\remarks
|
This object is passed to the evaluators
|
during compilation and evaluation. This object cannot be instantiated.
|
<group Other_Classes>
|
*/
|
class TOOLKIT_EXPORT OdFdFieldResult : public OdRxObject
|
{
|
public:
|
ODRX_DECLARE_MEMBERS(OdFdFieldResult);
|
OdFdFieldResult();
|
|
/** \details
|
Sets the evaluation result in the field.
|
\param pValue [in] Input evaluation to set in the field.
|
\remarks
|
If pValue is null,the cached evaluation is deleted.
|
*/
|
virtual void setFieldValue(const OdFieldValue* pValue) = 0;
|
|
/** \details
|
Sets the evaluation status in the field.
|
\param errorStatus [in] Error status
|
\param errorCode [in] Extended error code or zero for success
|
\param errorMessage [in] Error message
|
*/
|
virtual void setEvaluationStatus(OdDbField::EvalStatus errorStatus, int errorCode = 0, const OdString& errorMessage = OdString()) = 0;
|
};
|
|
/** \details
|
This abstract class is the Field Engine Protocol Extension class.
|
Its purpose is to provide services necessary for fields evaluation implemented at the host application level.
|
<group Other_Classes>
|
*/
|
class TOOLKIT_EXPORT OdFdFieldEnginePE : public OdRxObject
|
{
|
public:
|
ODRX_DECLARE_MEMBERS(OdFdFieldEnginePE);
|
/** \details
|
Retrieves sheet set property value.
|
|
\param propValue [out] result property value
|
\param compName [in] component name
|
\param propName [in] property name
|
\param pDb [in] database
|
|
Returns 'true' if the property was successfully retrieved to 'propValue', otherwise returns 'false'.
|
*/
|
virtual bool getSheetSetProperty(OdString& propValue, const OdString& compName, const OdString& propName, OdDbDatabase* pDb) = 0;
|
|
/** \details
|
Parses property string of ObjProp field code retrieving object id and property type.
|
|
\param prop [in] property string: "Object(%<\_ObjId XXX>%).PropName"
|
\param pDb [in] database
|
\param objId [out] object id
|
\param propName [out] property name
|
|
Returns 'true' on success, otherwise returns 'false'.
|
*/
|
virtual bool parseObjProp(const OdString& prop, OdDbDatabase* pDb, OdDbObjectId& objId, OdString& propName) = 0;
|
|
/** \details
|
Retrieves object property value.
|
|
\param propName [in] property name
|
\param objId [in] object
|
\param result [out] result
|
|
Returns 'true' on success, otherwise returns 'false'.
|
*/
|
virtual bool getObjPropValue(const OdString& propName, const OdDbObjectId& objId, OdFdFieldResult& result) = 0;
|
|
/** \details
|
Retrieves the current database of the host application.
|
The purpose of the function is to allow using the current database's properties when processing NDBRO fields.
|
|
Returns pointer to the current OdDbDatabase object.
|
*/
|
virtual OdDbDatabase* getCurrentDb() = 0;
|
|
/** \details
|
Returns the name of the file associated with this database object.
|
Differs from the current behavior of OdDbDatabase::getFilename(),
|
which returns autobackup filename, because OdDbDatabase::writeFile()
|
always sets m_currentFileName.
|
|
\param pDb [in] database
|
*/
|
virtual OdString getFileName(OdDbDatabase* pDb) = 0;
|
|
/** \details
|
Retrieves value of lisp variable.
|
|
\param lispVar [in] lisp variable name
|
\param fValue [out] field value where the result is stored
|
*/
|
virtual void getLispVariable(const OdString& lispVar, OdFieldValue& fValue) = 0;
|
};
|
|
typedef OdSmartPtr<OdFdFieldEnginePE> OdFdFieldEnginePEPtr;
|
|
/** \details
|
Evaluates fields in database.
|
\param pDb [in] Pointer to the database for which fields are to be evaluated
|
\param nContext [in] Input context in which the field is evaluated, which can be a predefined *OdDbField::EvalContext* enum flag or a user-defined context flag; this context flag is passed to the evaluator
|
\param objIds [in] Input array of object IDs of objects, whose fields are to be evaluated. If this is not null only, fields will be evaluated only for these objects.
|
\param pFieldsToEvaluate [in] Input array of object IDs of fields to be evaluated. If this is not null only these fields in the specified objects will be evaluated. If this is null all the fields in the specified objects will be evaluated.
|
\param pszEvaluatorId [in] Input evaluator ID. If this is not null only the fields matching this evaluator ID will be evaluated. If this is null all the fields in the specified objects will be evaluated.
|
\param nEvalFlag [in] Input one or more OdFd::EvalFields option flags
|
\param pNumFound [out] Output pointer to store the number of fields found; can be null if this information is not required
|
\param pNumEvaluated [out] Output pointer to store the number of fields evaluated; can be null if this information is not required
|
*/
|
TOOLKIT_EXPORT OdResult oddbEvaluateFields(
|
OdDbDatabase* pDb,
|
int nContext,
|
const OdDbObjectIdArray* objIds = 0,
|
const OdDbObjectIdArray* pFieldsToEvaluate = 0,
|
const OdString& pszEvaluatorId = OdString(),
|
OdFd::EvalFields nEvalFlag = OdFd::kEvalRecursive,
|
int* pNumFound = 0,
|
int* pNumEvaluated = 0);
|
|
|
#include "TD_PackPop.h"
|
|
#endif //_FdField_h_Included_
|
