Opens a Library Part parameter list to edit.
GSErrCode ACAPI_Goodies ( APIAny_OpenParametersID, API_ParamOwnerType* paramOwner );
Parameters
- paramOwner
- [in] Reference to the owner of the parameter handle which should be edited
Return Values
NoError
- The function has completed with success.
APIERR_BADPARS
paramOwner
is nullptr or invalid parameters are passedAPIERR_GENERAL
- the library part do not has parameters
For other common API errors see the API Errors document.
Remarks
This function is used to prepare a parameter list to edit.
Generally to change a parameter of a parameter list is a very complex task. It is because the API_AddParType structure is quite complex, especially in case of array parameters, however this problem can be handled. Another issue is the parameter script. This script sets up rules and links which must be followed to provide a consistent parameter set, while editing it. There is no possibility to handle this issue in an addon.
The only way to ensure full parameter consistency while changing a value of a Library Part parameter is to use the functions provided for this operation. If you manipulate the API_AddParType handle directly, the parameter list may become invalid.
The function set is:
APIAny_OpenParametersID
- APIAny_ChangeAParameterID
- APIAny_GetActParametersID
- APIAny_GetParamValuesID
- APIAny_CloseParametersID
Once you want to change a parameter you should open the parameter list with the APIAny_OpenParametersID
function. You can specify here various targets to work on:
- the parameters of a placed element (Library Part instance)
- the default parameters of an element (default tool settings)
- the default parameters of a Library Part itself
Refer to the API_ParamOwnerType structure how to specify the required target of operation.
After you opened the the parameter list to edit you can use the APIAny_ChangeAParameterID function to change a value of a parameter. The reference to a variable can be either the name of the variable or its index.
You can get the current (modified) parameter list in API form (API_AddParType handle) any time by calling the APIAny_GetActParametersID function.
You can check the possible values of a parameter (as defined in the Parameter Script of the Library Part) in API form (API_GetParamValuesType handle) any time by calling the APIAny_GetParamValuesID function.
When you have finished working on a parameter list you should call the APIAny_CloseParametersID function to free any associated resources allocated by the server application.
This function is a non-undoable data structure modifier function. See more details on this topic at Command Overview.
Example
/* change parameter 'zzyzx' of the default object */ API_ParamOwnerType paramOwner; API_ChangeParamType chgParam; API_GetParamsType getParams; API_Element element, mask; API_ElementMemo memo; GSErrCode err; BNZeroMemory (¶mOwner, sizeof (API_ParamOwnerType)); paramOwner.libInd = 0; /* no library part */ paramOwner.type = API_ObjectID; /* object element */ paramOwner.guid = APINULLGuid; /* element default */ BNZeroMemory (&getParams, sizeof (API_GetParamsType)); err = ACAPI_Goodies (APIAny_OpenParametersID, ¶mOwner, nullptr); if (err == NoError) { BNZeroMemory (&chgParam, sizeof (API_ChangeParamType)); err = ACAPI_Goodies (APIAny_GetActParametersID, &getParams, nullptr); if (err == NoError) { chgParam.index = 0; CHCopyC ("zzyzx", chgParam.name); chgParam.realValue = 2.0; err = ACAPI_Goodies (APIAny_ChangeAParameterID, &chgParam, nullptr); if (err == NoError) err = ACAPI_Goodies (APIAny_GetActParametersID, &getParams, nullptr); } ACAPI_Goodies (APIAny_CloseParametersID, nullptr, nullptr); } if (err == NoError) { BNZeroMemory (&element, sizeof (API_Element)); BNZeroMemory (&memo, sizeof (API_ElementMemo)); element.header.type = API_ObjectID; element.object.xRatio = getParams.a; element.object.yRatio = getParams.b; ACAPI_ELEMENT_MASK_CLEAR (mask); ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, xRatio); ACAPI_ELEMENT_MASK_SET (mask, API_ObjectType, yRatio); memo.params = getParams.params; err = ACAPI_Element_ChangeDefaults (&element, &memo, &mask); } ACAPI_DisposeAddParHdl (&getParams.params);
Requirements
- Version: API 4.1 or later
- Header: APIdefs_Goodies.h
See Also
API_ParamOwnerType, API_AddParType, API_GetParamValuesType,
APIAny_GetParamValuesID, APIAny_ChangeAParameterID, APIAny_GetActParametersID, APIAny_CloseParametersID,
ACAPI_Goodies, API Functions