 |
itom 1.3.0
|
|
itom 1.3.0
|
The itom standard API contains a bunch of functions that can be called by the core application itom as well as by every plugin or designer plugin. More...
Defines | |
| #define | apiFilterGetFunc (*(ito::RetVal (*)(const QString &name, ito::AddInAlgo::FilterDef *&filterDef)) ito::ITOM_API_FUNCS[0]) |
| looks for a given filter (algorithm) defined in any algo plugin. | |
| #define | apiFilterCall (*(ito::RetVal (*)(const QString &name, QVector<ito::ParamBase> *paramsMand, QVector<ito::ParamBase> *paramsOpt, QVector<ito::ParamBase> *paramsOut)) ito::ITOM_API_FUNCS[1]) |
| calls a filter (algorithm) defined in any algo plugin. | |
| #define | apiFilterParam (*(ito::RetVal (*)(const QString &name, QVector<ito::Param> *paramsMand, QVector<ito::Param> *paramsOpt, QVector<ito::Param> *paramsOut)) ito::ITOM_API_FUNCS[2]) |
| #define | apiFilterParamBase (*(ito::RetVal (*)(const QString &name, QVector<ito::ParamBase> *paramsMand, QVector<ito::ParamBase> *paramsOpt, QVector<ito::ParamBase> *paramsOut)) ito::ITOM_API_FUNCS[3]) |
| #define | apiAddInGetInitParams (*(ito::RetVal (*)(const QString &name, const int, int *, QVector<ito::Param> *&, QVector<ito::Param> *&)) ito::ITOM_API_FUNCS[4]) |
| #define | apiAddInOpenActuator (*(ito::RetVal (*)(const QString &name, const int, const bool, QVector<ito::ParamBase> *paramsMand, QVector<ito::ParamBase> *paramsOpt)) ito::ITOM_API_FUNCS[5]) |
| #define | apiAddInOpenDataIO (*(ito::RetVal (*)(const QString &name, const int, const bool, QVector<ito::ParamBase> *paramsMand, QVector<ito::ParamBase> *paramsOpt)) ito::ITOM_API_FUNCS[6]) |
| #define | apiValidateStringMeta (*(ito::RetVal (*)(const ito::StringMeta *meta, const char* value, bool mandatory)) ito::ITOM_API_FUNCS[7]) |
| validates a zero-terminated string with respect to given ito::StringMeta instance. | |
| #define | apiValidateDoubleMeta (*(ito::RetVal (*)(const ito::DoubleMeta *meta, double value)) ito::ITOM_API_FUNCS[8]) |
| validates a double value with respect to given ito::DoubleMeta instance. | |
| #define | apiValidateIntMeta (*(ito::RetVal (*)(const ito::IntMeta *meta, int value)) ito::ITOM_API_FUNCS[9]) |
| validates an integer value with respect to given ito::IntMeta instance. | |
| #define | apiValidateCharMeta (*(ito::RetVal (*)(const ito::CharMeta *meta, char value)) ito::ITOM_API_FUNCS[10]) |
| validates a char value with respect to given ito::CharMeta instance. | |
| #define | apiValidateHWMeta (*(ito::RetVal (*)(const ito::HWMeta *meta, ito::AddInBase *value, bool mandatory)) ito::ITOM_API_FUNCS[11]) |
| validates a plugin pointer with respect to given ito::HWMeta instance. | |
| #define | apiCompareParam (*(ito::tCompareResult (*)(const ito::Param ¶mTemplate, const ito::Param ¶m, ito::RetVal &ret)) ito::ITOM_API_FUNCS[12]) |
| #define | apiValidateParam (*(ito::RetVal (*)(const ito::Param &templateParam, const ito::ParamBase ¶m, bool strict, bool mandatory)) ito::ITOM_API_FUNCS[13]) |
| checks whether a given parameter fits to a template parameter. | |
| #define | apiValidateAndCastParam (*(ito::RetVal (*)(const ito::Param &templateParam, const ito::ParamBase ¶m, bool strict, bool mandatory, bool roundToStep)) ito::ITOM_API_FUNCS[25]) |
| checks whether a given parameter fits to a template parameter and possibly casts the param to the required type. | |
| #define | apiGetParamFromMapByKey (*(ito::RetVal (*)(QMap<QString,ito::Param> ¶mMap, const QString &key, QMap<QString,ito::Param>::iterator &found, bool errorIfReadOnly)) ito::ITOM_API_FUNCS[14]) |
| Finds reference to desired parameter in parameter map of any plugin. | |
| #define | apiParseParamName (*(ito::RetVal (*)(const QString &name, QString ¶mName, bool &hasIndex, int &index, QString &additionalTag)) ito::ITOM_API_FUNCS[15]) |
| parses a parameter name and splits it into specific parts | |
| #define | apiGetItemFromParamArray (*(ito::RetVal (*)(const ito::Param &arrayParam, const int index, ito::Param &itemParam)) ito::ITOM_API_FUNCS[16]) |
| #define | apiGetParam (*(ito::Param (*)(const ito::Param ¶m, const bool hasIndex, const int index, ito::RetVal &ret)) ito::ITOM_API_FUNCS[20]) |
| #define | apiUpdateParameters (*(ito::RetVal (*)(QMap<QString, ito::Param> ¶mMap, const QVector<QSharedPointer<ito::ParamBase> > &values)) ito::ITOM_API_FUNCS[23]) |
| update all values in paramMap | |
| #define | apiSaveQLIST2XML (*(ito::RetVal (*)(QMap<QString, ito::Param> *paramList , QString id, QFile ¶mFile)) ito::ITOM_API_FUNCS[17]) |
| #define | apiLoadXML2QLIST (*(ito::RetVal (*)(QMap<QString, ito::Param> *paramList , QString id, QFile ¶mFile)) ito::ITOM_API_FUNCS[18]) |
| #define | apiCreateFromDataObject (* (ito::DataObject* (*)(const ito::DataObject *dObj, int nrDims, ito::tDataType type, int *sizeLimits, ito::RetVal *retval)) ito::ITOM_API_FUNCS[19]) |
| returns a shallow or deep copy of a given data object that fits to given requirements | |
| #define | apiCreateFromNamedDataObject (* (ito::DataObject* (*)(const ito::DataObject *dObj, int nrDims, ito::tDataType type, const char *name, int *sizeLimits, ito::RetVal *retval)) ito::ITOM_API_FUNCS[24]) |
| returns a shallow or deep copy of a given data object that fits to given requirements | |
| #define | apiGetCurrentWorkingDir (* (QString (*)(void)) ito::ITOM_API_FUNCS[21]) |
| returns the current working directory of itom | |
| #define | apiShowConfigurationDialog (* (ito::RetVal (*)(ito::AddInBase *plugin, ito::AbstractAddInConfigDialog *configDialogInstance)) ito::ITOM_API_FUNCS[22]) |
| helper function to show and process a configuration dialog of a plugin | |
The itom standard API contains a bunch of functions that can be called by the core application itom as well as by every plugin or designer plugin.
Every function is given by a certain preprocessor definition that describes the return value, parameters and function name of the method to call. Each preprocessor definition is redirected to a function pointer that becomes valid at runtime. The initialization of these function pointers in any plugins is an automatic process by itom, called when loading the plugin.
How to read the following definitions?
Basically the first word after the #define word is the method to call. After the first star the return value follows (the star into brackets is not part of the return value). Then there is a list of different parameters for this method.
| #define apiCreateFromDataObject (* (ito::DataObject* (*)(const ito::DataObject *dObj, int nrDims, ito::tDataType type, int *sizeLimits, ito::RetVal *retval)) ito::ITOM_API_FUNCS[19]) |
returns a shallow or deep copy of a given data object that fits to given requirements
Use this simple api method to test a given data object if it fits some requirements. If this is the case, a shallow copy of the input data object is returned. Else, it is tried to convert into the required object and a converted deep copy is returned. If the input object does not fit the given requirements, NULL is returned and the ito::RetVal parameter contains an error status including error message.
| dObj | the input data object |
| nrDims | the required number of dimensions |
| type | the required type of the returned data object |
| sizeLimits | can be NULL if the sizes should not be checked, else it is an array with length (2*nrDims). Every adjacent pair describes the minimum and maximum size of each dimension. |
| retval | can be a pointer to an instance of ito::RetVal or NULL. If given, the status of this method is added to this return value. |
| #define apiCreateFromNamedDataObject (* (ito::DataObject* (*)(const ito::DataObject *dObj, int nrDims, ito::tDataType type, const char *name, int *sizeLimits, ito::RetVal *retval)) ito::ITOM_API_FUNCS[24]) |
returns a shallow or deep copy of a given data object that fits to given requirements
Use this simple api method to test a given data object if it fits some requirements. If this is the case, a shallow copy of the input data object is returned. Else, it is tried to convert into the required object and a converted deep copy is returned. If the input object does not fit the given requirements, NULL is returned and the ito::RetVal parameter contains an error status including error message.
| dObj | the input data object |
| nrDims | the required number of dimensions |
| type | the required type of the returned data object |
| name | name of the data object for an improved error message (zero-terminated string) or NULL if no name is known. |
| sizeLimits | can be NULL if the sizes should not be checked, else it is an array with length (2*nrDims). Every adjacent pair describes the minimum and maximum size of each dimension. |
| retval | can be a pointer to an instance of ito::RetVal or NULL. If given, the status of this method is added to this return value. |
| #define apiFilterCall (*(ito::RetVal (*)(const QString &name, QVector<ito::ParamBase> *paramsMand, QVector<ito::ParamBase> *paramsOpt, QVector<ito::ParamBase> *paramsOut)) ito::ITOM_API_FUNCS[1]) |
calls a filter (algorithm) defined in any algo plugin.
This api method calls another filter given by its specific name in any other plugin. The call is executed in the calling thread. You need to make sure, that all parameters that you provide as vectors to this function fully correspond to the number and type of the desired parameters. You can get the default vectors using the api method apiFilterParamBase.
| name | is the name of the desired filter or algorithm |
| paramsMand | is a pointer to a vector of type ParamBase containing all mandatory parameters. |
| paramsOpt | is a pointer to a vector of type ParamBase containing all optional parameters. |
| paramsOut | is a pointer to a vector of type ParamBase containing all output parameters. |
| #define apiFilterGetFunc (*(ito::RetVal (*)(const QString &name, ito::AddInAlgo::FilterDef *&filterDef)) ito::ITOM_API_FUNCS[0]) |
looks for a given filter (algorithm) defined in any algo plugin.
| name | is the name of the desired filter or algorithm |
| filterDef | reference to a ito::AddInAlgo::FilterDef struct pointer. If the filter is found, this reference points to the struct defined by the plugin. |
| #define apiGetCurrentWorkingDir (* (QString (*)(void)) ito::ITOM_API_FUNCS[21]) |
returns the current working directory of itom
The current working directory is the current working directory of both python and itom itself. Its absolute path is returned as string.
| #define apiGetParamFromMapByKey (*(ito::RetVal (*)(QMap<QString,ito::Param> ¶mMap, const QString &key, QMap<QString,ito::Param>::iterator &found, bool errorIfReadOnly)) ito::ITOM_API_FUNCS[14]) |
Finds reference to desired parameter in parameter map of any plugin.
The parameters of all plugins are contained in the map ito::AddInBase::m_params that maps the parameter name to its value (ito::Param). This method tries to find a given parameter name in this map and if found, returns its reference by providing an iterator to the specific value.
| paramMap | is the reference to th entire parameter map |
| key | is the parameter name that should be found (key-only, no index or additional tag) |
| iterator | if parameter has been found, this is an iterator to the specific parameter |
| errorIfReadonly | returns ito::retError if the found parameter is read-only (with specific error message). This can be used in the ito::AddInBase::setParam method of any plugin. |
| #define apiParseParamName (*(ito::RetVal (*)(const QString &name, QString ¶mName, bool &hasIndex, int &index, QString &additionalTag)) ito::ITOM_API_FUNCS[15]) |
parses a parameter name and splits it into specific parts
When reading or writing a parameter of any plugin instance, the parameter name must have a specific form:
This method checks the given name and splits it into the parts. If the name does not fit to the stated form, ito::retError is returned.
| name | is the full parameter name |
| paramName | is the simple parameter name |
| hasIndex | true if index is given, else false |
| index | is the provided integer index value |
| additionalTag | is any suffix provided after the colon-sign |
| #define apiShowConfigurationDialog (* (ito::RetVal (*)(ito::AddInBase *plugin, ito::AbstractAddInConfigDialog *configDialogInstance)) ito::ITOM_API_FUNCS[22]) |
helper function to show and process a configuration dialog of a plugin
Use this simple api method in the method showConfDialog of a plugin to show and process the configuration dialog, whose instance is passed by configDialogInstance. This api function shows the dialog, passes the current parameters of the plugin and processes the changes. The given dialog instance is automatically deleted at the end.
| plugin | the instance of the plugin itself |
| configDialogInstance | a new instance of the configuration dialog inherited from ito::AbstractAddInConfigDialog |
| #define apiUpdateParameters (*(ito::RetVal (*)(QMap<QString, ito::Param> ¶mMap, const QVector<QSharedPointer<ito::ParamBase> > &values)) ito::ITOM_API_FUNCS[23]) |
update all values in paramMap
For each value in vector values, their corresponding entry in paramMap is searched and if available set to the value given in the values vector. No validation besides a general type validation is done.
| paramMap | is the map with parameters to set |
| values | are the new values, their name is used as keyword for paramMap |
| #define apiValidateAndCastParam (*(ito::RetVal (*)(const ito::Param &templateParam, const ito::ParamBase ¶m, bool strict, bool mandatory, bool roundToStep)) ito::ITOM_API_FUNCS[25]) |
checks whether a given parameter fits to a template parameter and possibly casts the param to the required type.
This method checks whether a parameter param fits to the requirements of a template parameter.
At first the types of param and templateParam are checked. If they are not equal or not compatible (in case of strict==false), an error with an appropriate error message is returned. After this, the value of param is checked with respect to the meta information, that are optionally given in templateParam. If param does not fit to these requirements, an error is returned, too.
If templateParam is an array type and param is the corresponding non-array type, the validation succeeds if the name of param is an index-base name, e.g. myParam[0]. Then it is assumed, that param is the value at the first position of templateParam.
| templateParam | is the template parameter. Its type as well as optionally available meta information is used for the check |
| param | is the parameter to check. Only the current value and its type is used. |
| strict | indicates whether the types of param and templateParam must exactly fit (true) or if compatible types (e.g. int vs. double) are allowed as well (false). |
| mandatory | is a boolean value indicating if the given parameter must contain a value (NULL as value for strings or dataObjects is no value). |
| roundToStep | if true, double parameters are checked with respect to the given min,max and increment. If the given value does not fit to the increment, it is cast to the next allowed value. |
| #define apiValidateCharMeta (*(ito::RetVal (*)(const ito::CharMeta *meta, char value)) ito::ITOM_API_FUNCS[10]) |
validates a char value with respect to given ito::CharMeta instance.
| meta | pointer to a ito::CharMeta instance describing the requirements for the number |
| value | an integer value that sould be verified |
| #define apiValidateDoubleMeta (*(ito::RetVal (*)(const ito::DoubleMeta *meta, double value)) ito::ITOM_API_FUNCS[8]) |
validates a double value with respect to given ito::DoubleMeta instance.
| meta | pointer to a ito::DoubleMeta instance describing the requirements for the number |
| value | a double value that sould be verified |
| #define apiValidateHWMeta (*(ito::RetVal (*)(const ito::HWMeta *meta, ito::AddInBase *value, bool mandatory)) ito::ITOM_API_FUNCS[11]) |
validates a plugin pointer with respect to given ito::HWMeta instance.
The hardware pointer is an instance of an opened hardware plugin (dataIO, actuator)
| meta | pointer to a ito::HWMeta instance describing the requirements for the given plugin |
| value | an instance of a plugin (inherited from ito::AddInBase) that should be verified |
| #define apiValidateIntMeta (*(ito::RetVal (*)(const ito::IntMeta *meta, int value)) ito::ITOM_API_FUNCS[9]) |
validates an integer value with respect to given ito::IntMeta instance.
| meta | pointer to a ito::IntMeta instance describing the requirements for the number |
| value | an integer value that sould be verified |
| #define apiValidateParam (*(ito::RetVal (*)(const ito::Param &templateParam, const ito::ParamBase ¶m, bool strict, bool mandatory)) ito::ITOM_API_FUNCS[13]) |
checks whether a given parameter fits to a template parameter.
This method checks whether a parameter param fits to the requirements of a template parameter.
At first the types of param and templateParam are checked. If they are not equal or not compatible (in case of strict==false), an error with an appropriate error message is returned. After this, the value of param is checked with respect to the meta information, that are optionally given in templateParam. If param does not fit to these requirements, an error is returned, too.
If templateParam is an array type and param is the corresponding non-array type, the validation succeeds if the name of param is an index-base name, e.g. myParam[0]. Then it is assumed, that param is the value at the first position of templateParam.
| templateParam | is the template parameter. Its type as well as optionally available meta information is used for the check |
| param | is the parameter to check. Only the current value and its type is used. |
| strict | indicates whether the types of param and templateParam must exactly fit (true) or if compatible types (e.g. int vs. double) are allowed as well (false). |
| mandatory | is a boolean value indicating if the given parameter must contain a value (NULL as value for strings or dataObjects is no value). |
| #define apiValidateStringMeta (*(ito::RetVal (*)(const ito::StringMeta *meta, const char* value, bool mandatory)) ito::ITOM_API_FUNCS[7]) |
validates a zero-terminated string with respect to given ito::StringMeta instance.
| meta | pointer to a ito::StringMeta instance describing the requirements for the string |
| value | a zero-terminated string that should be verified |
| mandatory | if true, an error is returned if the string is empty, else an empty string returns ito::retOk |
1.7.4 
