ACAPI_​Element_​ChangeParameters

Changes the parameters of a number of elements.

    GSErrCode  ACAPI_Element_ChangeParameters (
        const GS::Array<API_Guid>& elemGuids,
        const API_Element*         defPars,
        const API_ElementMemo*     defMemo,
        const API_Element*         mask
    );

 

Parameters

elemGuids
[in] Identifies the element(s).
defPars
[in] The parameters of the new element.
defMemo
[in] The memo of the new element. (Only if needed.)
mask
[in] The mask of the new element.

 

Return Values

NoError
The function has completed with success.
APIERR_BADPARS
defPars is nullptr
APIERR_BADDATABASE
The current database is not proper for the operation
APIERR_MEMFULL
Not enough memory to complete the operation

For other common API errors see the API Errors document.

 

Remarks

You can use this function to change the settings parameters of a number of elements, identified by elemGuids. If elemGuids is empty, then this function works on the selection. Only those elements are affected whose type is the same that passed in the defPars argument.

Elements which are not allowed for edit for some reason, are ignored. Such cases can be:

  • it is locked,
  • it is on a locked layer,
  • it is part of a group, and suspend group is OFF
  • it is not in the users workspace, etc.

This function can only be used to change the settings-type parameters of elements, but not their geometric parameters. Only those parameters are affected which are marked in the mask argument. Such elements which refer to Library Parts, the params handle from the memo is interpreted. If it is nullptr, nothing will happen. If it is passed, the actual parameter list will be changed.

Refer to the ACAPI_Element_Change and the ACAPI_Element_ChangeDefaults functions, which work similarly.

The following notes are absolutely important:

  • the list of target elements will be automatically extended by the other group members; if there are a group member in the set, and suspend group is OFF
  • all the edited elements keep their unique ID
  • all the inter-element links will be adjusted; including dimensioning also,

Do not forget to call ACAPI_DisposeElemMemoHdls to dispose of the handles when you’re finished.

 

Requirements

Version: API 2.1 or later
Header: ACAPinc.h

 

See Also

API_Elem_Head, API_Element, API_ElementMemo,
ACAPI_Element_Change,
ACAPI_Element_ChangeDefaults,
ACAPI_DisposeElemMemoHdls,
Element Manager, API Functions