DG Kernel (ActiveX) Documentation

IElem is a slightly enhanced version of IElement interface. The only difference is that SetParam and SetNamedParam methods have additional parameter, which acts as the return value for higher level development environments like Visual Basic and .NET environments. This return value notifies the caller if the new value was accepted, rejected or did not have any effect on the model.

If IElem is implemented, it can be queried from the correspondent IElement interface. Note that some simple objects (IElement implemented by an axial point) always accept its modification, and hence do not implement IElem interface.

HRESULT GetParamCount(int *pnCount)

Parameters

pnCount - [out] pointer to the variable which will receive number of parameters in the element.

Return Values

S_OK in case of success.

DISP_E_PARAMNOTOPTIONAL - if pnCount is NULL.

Remarks

Call to get the number of parameters, which determine geometry of the element.

HRESULT GetParam( int id, double *pd)

Parameters

id - [in] zero-based index of the parameter.

pd - [out] pointer to a double variable that will receive value of the parameter.

Return Values:


S_OK in case of success.

DISP_E_BADINDEX - if id is greater than or equal to the number of parameters.
Remarks

Returns value of the parameter id.

All angles in the software are internally represented in radians, so when the parameter is an angle, the returned value will be in range (-PI, PI].

HRESULT SetParam( int id, double val, int* result)

Parameters:

id - [in] zero-based index of the parameter.

val - [in] new value of the parameter.

result - [out, retval] - Result of the modification. Values are enumerated in EModifResult. See remarks for details.

Return Values:

S_OK in case of success
DISP_E_BADINDEX - if id is greater than or equal to the number of parameters

DI_E_INVALIDGEOMETRY - if the modification was rejected because it would make geometry of the model invalid.


Remarks:


Call this method to set value of a parameter. After successful call to SetParam method and before any other modification of the same parameter, there should be a call to UpdateSurface method of the DG Kernel control or call to Update method of the IModel interface.



Possible values of result are listed in EModifResult enumeration. If the returned result is -1 it means that some arc in the current strip would become invalid after the modification so the modification has been rejected. If result is equal to 0 val coincides with the current value of the parameter so there where no changes. If result is equal to 1 it means that the new value has been accepted and the parameter has been modified.



Note that success return code means that only a simple validation succeeded. The geometry of the model may still be invalid and can be rejected later during the call to UpdateSurface() method of the control. In the later case all modifications since the previous call to UpdateSurface() will be discarded.

All angles in the software are internally represented in radians, so when the parameter is an angle, new value should be in range (-PI, PI] otherwise the methods returns EModifResult.eModifResInvalid (=-1) and the parameter will remain unchanged.

HRESULT GetNamedParam(char* szParamName, double *pd)

Parameters:

szParamName - [in] - pointer to a string containing the parameter name.

pd - [out] pointer to the double variable, which will receive the value of the parameter.

Return Values:

S_OK in case of success

DISP_E_PARAMNOTOPTIONAL - if szParamName is NULL.

DISP_E_UNKNOWNNAME - In case there is no parameter with this name.

Remarks:

Objects implementing IElem keep names for each parameter. See Elements for parameter names. Parameter names of an object can be queried at runtime with GetParamCount and GetParamName methods. Call GetNamedParam method to retrieve value of the parameter.
HRESULT SetNamedParam(char* szParamName, double val, int* result)

Parameters

szParamName - [in] - pointer to a string containing the parameter name.

val - [in] new value of the parameter.

result - [out, retval] - Result of the modification. Values are enumerated in EModifResult. See remarks for details.

Return Values

S_OK in case of success

DISP_E_PARAMNOTOPTIONAL - if szParamName is NULL.

DISP_E_UNKNOWNNAME - In case there is no parameter with this name.

Remarks:

Objects implementing IElem keep names for each parameter. See Elements for parameter names of 2D elements. Parameter names of an object can be queried at runtime with GetParamCount and GetParamName methods. This method is a shortcut for sequence of GetParamId and SetParam calls.

HRESULT GetParamName(int id, char* szParamName)

Parameters

id - [in] zero-based index of the parameter.

szParamName - [out] Pointer to a string which will receive the name. The string has to be allocated by the caller. Maximal length of any parameter name is limited by eMaxParamName member of EDIConst enumeration. In this release eMaxParamName = 30. C/C++ declaration of EDIConst is available in DITypes.h (include DIInterface.h)

Return Values

S_OK in case of success

DISP_E_PARAMNOTOPTIONAL - if szParamName is NULL.

DISP_E_BADINDEX - if id is greater than or equal to the number of parameters
Remarks:

Objects implementing IElem keep names for each parameter. See Elements for parameter names of 2D elements. Call this method to retrieve name of the parameter.



HRESULT GetParamId(char* szParamName, int *plId)
Parameters

szParamName - [in] pointer to a string containing the parameter name.

plId - [out] pointer to an integer variable, which will receive the id of the parameter

Returns

S_OK in case of success

DISP_E_PARAMNOTOPTIONAL. - if szParamName or plId is NULL or there is no parameter with this name.

Remarks:
Objects which implement IElem keep names for each parameter. See Elements for parameter names. Object's parameter names can be queried at runtime with GetParamCount and GetParamName methods. Call GetNamedParam method to retrieve the value of the parameter.

HRESULT GetElemClassName(char* szName)

Parameters

szName - [out] - pointer to a string which will receive the name. The string has to be allocated by the caller. Maximal length of any parameter name is limited by eMaxClassName member of EDIConst enumeration. In this release eMaxClassName = 50. C/C++ declaration of EDIConst is available in DITypes.h (include DIInterface.h)

Returns

S_OK.

DISP_E_PARAMNOTOPTIONAL - if szName is NULL.

Remarks
Objects implementing IElem keep name if its type. See Elements for available class names. Call this method to retrieve type name of the object at runtime.