ACAPI_Element_Change |

Modifies an element in the current database.

    GSErrCode  ACAPI_Element_Change (
        API_Element*               element,
        const API_Element*         mask,
        const API_ElementMemo*     memo,
        UInt64                     memoMask,
        bool                       withdel
    );

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: [in] Specifies the relevant parts of the memo parameter
withdel: [in] Delete the original instance of the element, or keep it and create a new one

Return Values

NoError: The function has completed with success.
APIERR_BADDATABASE: The current database should be the floor plan, a section/elevation, a detail or a worksheet
APIERR_BADPARS: The passed element parameter is nullptr,
or the element is grouped and suspend group mode is OFF
APIERR_BADID: The element reference is invalid (guid)
or the element type is not supported by the server application
APIERR_DELETED: The element does not exist in the database
APIERR_NOTMINE, APIERR_LOCKEDLAY, APIERR_HIDDENLAY, APIERR_NOTEDITABLE: The referenced element cannot be modified
APIERR_IRREGULARPOLY: Input polygon or polyline is irregular.

For other common API errors see the API Errors document.

Remarks

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 header is filled in. Element connections and dimension chains are updated automatically.

To change elements having associated markers use the ACAPI_Element_ChangeExt function instead.

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 type	📝 Notes
`API_WallID`	cannot switch between polygon-based and non-polygon-based wall types; `type`, `begC`, `endC` and `angle` fields can be modified for non-polygonal walls only; the `gables` of the wall can be changed
`API_ColumnID`	beside the setting parameters the `origoPos`, `axisRotationAngle` fields can be accessed directly; the `gables`, `columnSegments`, `assemblySegmentCuts`, `assemblySegmentSchemes` and `assemblySegmentProfiles` memos can be modified
`API_BeamID`	beside the setting parameters the `begC`, `endC` fields can be accessed directly; the `beamHoles`, `gables`, `beamSegments`, `assemblySegmentCuts`, `assemblySegmentSchemes` and `assemblySegmentProfiles` memos can be modified
`API_WindowID API_DoorID`	beside the setting parameters the following fields can be edited: `objLoc`, `reflected`, `oSide`, `refSide`, `wallCutUsing`, `libInd`; the `gables` and `params` memos can also be modified
`API_ObjectID API_LampID`	beside the setting parameters the following fields can be edited: `pos`, `libInd`; the `gables` and `params` memos can also be modified
`API_SlabID`	beside the setting parameters the polygon of the slab can be modified directly (`coords`, `pends`, `parcs` and `vertexIDs` memo handles)
`API_RoofID`	beside the setting parameters the `baseLine` field, the polygon of the roof and the roof sides can be modified directly (`coords`, `pends`, `parcs`, `vertexIDs` and `roofSides` memo handles)
`API_MeshID`	beside the setting parameters the polygon and ridge levels of the mesh can be modified directly (`coords`, `pends`, `parcs` `vertexIDs`, `meshPolyZ`, `meshLevelCoords` and `meshLevelEnds`memo handles)
`API_DimensionID`	beside the setting parameters the `dimElems` memo handle can be modified
`API_RadialDimensionID`	beside the setting parameters the following fields can be edited: `base`, `note`
`API_LevelDimensionID`	beside the setting parameters the following fields can be edited: `loc`, `note1`, `note2`, `parentType`, `parentGuid`
`API_AngleDimensionID`	beside the setting parameters the `note` and `base` fields can be modified
`API_TextID`	beside the setting parameters the following fields can be edited: `loc`, `width`, `nonBreaking`; the content and the style of the text can also be modified (`textContent`, `paragraphs` memo)
`API_LabelID`	beside the setting parameters the following fields can be edited: `begC`, `midC`, `endC`, `u.text` (the same as `API_TextID`), `u.symbol` (the same as `API_ObjectID`); for textual label the content and the style of the text can also be modified (`textContent`, `paragraphs` memo); an associative Label cannot be made independent, and an independent Label cannot be made associative.
`API_ZoneID`	beside the setting parameters the following fields can be edited: `libInd`, `pos` and the polygon of the zone (`coords`, `pends`, `parcs`, `vertexIDs` memo handles)
`API_HatchID`	beside the setting parameters the following fields can be edited: `note` and the polygon of the hatch (`coords`, `pends`, `parcs`, `vertexIDs` memo handles)
`API_LineID`	beside the setting parameters the `begC`, `endC` fields can be accessed directly
`API_ArcID` `API_CircleID`	both the setting and geometry parameters can be modified with ACAPI_Element_Change
`API_PolyLineID`	beside the setting parameters the the polygon data (`coords`, `pends`, `parcs`, `vertexIDs` memo handles) can be accessed directly
`API_SplineID`	only the setting parameters can be modified with ACAPI_Element_Change in this version; geometry data, `autoSmooth` and `closed` fields cannot be accessed
`API_HotspotID`	beside the setting parameters the following fields can be edited: `pos`, `height`
`API_CutPlaneID`	beside the setting parameters the following fields can be edited: `depth`, `leftDir`
`API_ChangeMarkerID`	beside the setting parameters the following fields can be edited: `pos`. It has effect only when the changed ChangeMarker has no polygon, i.e. it points to a single coordinate marked by `pos`.
`API_DetailID` `API_WorksheetID`	beside the setting parameters the `pos` field and the polygon of the detail or worksheet (`coords`, `pends`, `parcs`, `vertexIDs` memo handles) can be accessed directly
`API_SectElemID`	after modifying the parent element on the floor plan database, calling ACAPI_Element_Change for the section symbol element on the section database rebuilds the image of the modified element in the section window (use this to avoid unnecessary `APIDo_RebuildID` and `APIDb_RebuildCurrentDatabaseID` calls). The function returns `APIERR_DELETED` if the parent element has been deleted or got out of the scope of the section; otherwise it gives back the new index of the refreshed section element.
`API_MorphID`	in some cases changing the `tranmat` field effects the body points themselves and vice versa; the resulting body will be correct, but getting the `tranmat` field after setting might result different values inside
`API_HotlinkID`	the `type`, and `hotlinkGroupGuid` fields can not be changed.
`API_OpeningID`	Connected elements can not be removed or added.

You can modify more elements at once with a single call of the ACAPI_Element_ChangeMore function.

Example


GSErrCode   FlipWall (const API_Guid& wallGuid)
{
    API_Element         element, mask;
    API_Coord           c1, c2;
    GSErrCode           err = NoError;

    BNZeroMemory (&element, sizeof (API_Element));
    element.header.guid  = wallGuid;
    err = ACAPI_Element_Get (&element);
    if (err != NoError)
        return err;

    c1 = element.wall.begC;
    c2 = element.wall.endC;

    if (err == NoError) {
        ACAPI_ELEMENT_MASK_CLEAR (mask);
        ACAPI_ELEMENT_MASK_SET (mask, API_WallType, begC);
        ACAPI_ELEMENT_MASK_SET (mask, API_WallType, endC);

        element.wall.begC = c2;
        element.wall.endC = c1;

        err = ACAPI_Element_Change (&element, &mask, nullptr, 0, true);
    }

    return err;
}

Requirements

Version: API 3.1 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also