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 passed

APIERR_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 (&paramOwner, 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, &paramOwner, 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