ACAPI_​Element_​ChangeExt

Modifies a Window, Door, Section, Elevation, Interior Elevation, ChangeMarker, Detail, Worksheet, or Stair element in the current database.

    GSErrCode  ACAPI_Element_ChangeExt (
        API_Element*             element,
        const API_Element*       mask,
        API_ElementMemo*         memo,
        UInt64                   memoMask,
        UInt32                   nSubElems,
        API_SubElemMemoMask*     subElems,
        bool                     withdel,
        Int32                    subIndex
    );

 

Parameters

element
[in/out] Reference to the element to be modified, filled with the appropriate new parameters
mask
[in] Optional parameter for masking the relevant fields of element
memo
[in] The memo data to be changed. Optional parameter, can be nullptr
memoMask Featuring API 11
[in] Specifies the relevant parts of the memo parameter. You can use a special mask value (ACAPI_ELEMENT_CHANGEEXT_ALLSEGMENTS) to change all segment of an interior elevation element.
nSubElems Modified in API 12
[in] The number of subelems (markers) passed (0-3).
subElems Modified in API 12
[in] Contains the markers (default marker, story handle marker, interior elevation common marker) to be modified.
withdel
[in] Delete the original instance of the element, or keep it and create a new one
subIndex Featuring API 11
[in] The index of the section segment to be modified (for interior elevations only). The value is between 0 and the (number of segments – 1).

 

Return Values

NoError
The function has completed with success.
APIERR_BADDATABASE
The current database should be floor plan, section/elevation, detail or worksheet.
APIERR_BADPARS
The passed element parameter is nullptr,
or the element is grouped and suspend group mode is OFF, or the element type is invalid or not supported by the server application. The elementMarker->header.typeID is not API_ObjectID.
APIERR_BADID
The element reference is invalid (guid). The element type should be API_WindowID, API_DoorID, API_CutPlaneID, API_ElevationID, API_InteriorElevationID, API_ChangeMarkerID, API_DetailID, API_WorksheetID, or API_StairID.
APIERR_DELETED
The element does not exist in the database.
APIERR_NOTMINE,
APIERR_LOCKEDLAY,
APIERR_HIDDENLAY,
APIERR_NOTEDITABLE
The referenced element cannot be modified.

For other common API errors see the API Errors document.

 

Remarks

This function is an extension of ACAPI_Element_Change to modify elements with their linked sub-elements.

With this function not only the setting type parameters of an element can be modified, but geometry data too. Unlike ACAPI_Element_ChangeParameters and ACAPI_Element_Edit, it works only on one element at a time. On return the guid field of the element and elementMarker header is filled in. Element connections and dimension chains are updated automatically.
Do not forget to call ACAPI_DisposeElemMemoHdls to dispose the memo handles when they are not needed any more.

The following element types are supported:

element memo elementMarker memoMarker elementMarker2 memoMarker2
API_WindowType
API_DoorType
addpar window/door marker object marker object parameters
API_CutPlaneType cutplane coordinates section marker object on floorplan section marker object parameters story handle marker object on section story handle marker object parameters
API_ElevationType elevation coordinates elevation marker object on floorplan elevation marker object parameters story handle marker object on section story handle marker object parameters
API_ChangeMarkerType polygon data (optional) ChangeMarker marker object marker object parameters
API_DetailType
API_WorksheetType
polygon data (optional) detail drawing/worksheet marker object marker object parameters

 

Requirements

Version: API 4.3 or later
Header: ACAPinc.h

 

See Also

API_Element, API_ElementMemo, API_SubElemMemoMask
ACAPI_Element_Change, ACAPI_Element_ChangeMore
ACAPI_Element_ChangeMemo, ACAPI_Element_ChangeParameters
ACAPI_Element_Edit, ACAPI_DisposeElemMemoHdls
ACAPI_Element_CreateExt, ACAPI_Element_GetDefaultsExt, ACAPI_Element_ChangeDefaultsExt
API_WindowType, API_CutPlaneType, API_ElevationType, API_InteriorElevationType, API_ChangeMarkerType, API_DetailType, API_WorksheetType
Element Manager, API Functions