ACAPI_​Element_​ChangeDefaultsExt

Changes the default parameters of the Window, Door, Section, Elevation, Interior Elevation, ChangeMarker, Detail, Worksheet, or Stair default element and its marker(s). You are able to change Curtain Wall and its subelem default settings also via this function.

    GSErrCode  ACAPI_Element_ChangeDefaultsExt (
        API_Element*             element,
        API_ElementMemo*         memo,
        const API_Element*       mask,
        UInt32                   nSubElems,
        API_SubElemMemoMask*     subElems
    );

 

Parameters

element
[in] Contains the general parameters to which you would like to change the defaults. The element->header.typeID can be API_WindowID, API_DoorID, API_CutPlaneID, API_ElevationID, API_InteriorElevationID, API_ChangeMarkerID, API_DetailID, API_WorksheetID, API_CurtainWallID, API_CurtainWallPanelID, API_CurtainWallFrameID, API_CurtainWallJunctionID, API_CurtainWallAccessoryID or API_StairID.
memo
[in][ Contains the special parameters to which you would like to change the defaults.
mask
[in] Contains a mask that specifies which parameters you would like to change. The memo fields are always used when they contain valid data.
nSubElems Modified in API 12
[in] The number of subelems passed (0-3)
subElems Modified in API 12
[in]
Usually the first marker contains the general marker parameters to which you would like to change the defaults. If this parameter is not nullptr then the header.typeID must be API_ObjectID. The mask specifies which parameters of the marker you would like to change. These fields are always used when they contain valid data.
The second marker element is the Story Handle Marker where applicable.
The third marker element is the common marker of the interior elevation element.

 

Return Values

NoError
The function has completed with success.
APIERR_BADPARS
The passed element parameter is nullptr.
APIERR_BADID
The element type should be API_WindowID, API_DoorID, API_CutPlaneID, API_ElevationID, API_InteriorElevationID, API_ChangeMarkerID, API_DetailID, API_WorksheetID, API_CurtainWallID, API_CurtainWallPanelID, API_CurtainWallFrameID, API_CurtainWallJunctionID, API_CurtainWallAccessoryID or API_StairID.
APIERR_MEMFULL
Not enough memory to complete the operation.

For other common API errors see the API Errors document.

 

Remarks

This function is used to change the actual default settings for a Window, Door, Section, Elevation, Interior elevation, ChangeMarker, Detail or Worksheet element type, as an alternative of ACAPI_Element_ChangeDefaults.

The marker parameters are optional, pass nullptr to keep them unchanged. For the detailed interpretation of the parameters refer to the ACAPI_Element_ChangeExt function.

Only those parameters are changed where the corresponding field in the mask is not 0. The requested type is identified by the typeID and variationID field of the header.

The memo parameter is used only in the case of API_WindowID and API_DoorID. For library part-based elements, if memo is set to nullptr, the default parameters of the originating library part are used, otherwise the values are taken from the params field of memo.

To retrieve the actual settings defaults use the ACAPI_Element_GetDefaultsExt function.

Only those parameters are required to fill in the element argument, which are marked to be changed. There are macros to set up the mask values correctly. They are:

ACAPI_ELEMENT_MASK_CLEAR

Clear all the flags in the mask

ACAPI_ELEMENT_MASK_SETFULL

Set all the flags in the mask

ACAPI_ELEMENT_MASK_SET

Set only one flag in the mask according to one element parameter

ACAPI_ELEMENT_MASK_CHECK

Check the mask for one element parameter

Don’t forget to call ACAPI_DisposeElemMemoHdls to dispose of the passed handles.

 

Example


API_Element element;
API_MarkerMemoMask marker;

BNZeroMemory (&element, sizeof (API_Element));
BNZeroMemory (&marker, sizeof (API_MarkerMemoMask));

element.header.typeID = API_DoorID;
element.header.variationID = APIVarId_Generic;
marker.markType = (API_MarkerMemoMaskType) (APIMarkerMemoMask_MainMarker | APIMarkerMemoMask_NoParams);
GSErrCode err = ACAPI_Element_GetDefaultsExt (&element, nullptr, 1UL, &marker);
if (err == NoError) {
    ACAPI_ELEMENT_MASK_CLEAR (marker.mask);
    ACAPI_ELEMENT_MASK_SET (marker.mask, API_ObjectType, pen);
    marker.markElem.object.pen = 3;
    err = ACAPI_Element_ChangeDefaultsExt (&element, nullptr, nullptr, 1UL, &marker);
}

 

Requirements

Version: API 4.3 or later
Header: ACAPinc.h

 

See Also

API_Element, API_ElementMemo
ACAPI_Element_GetDefaultsExt, ACAPI_Element_ChangeDefaults, ACAPI_DisposeElemMemoHdls
ACAPI_Element_CreateExt, ACAPI_Element_ChangeExt
API_WindowType, API_CutPlaneType, API_ElevationType, API_InteriorElevationType, API_ChangeMarkerType, API_DetailType, API_WorksheetType
Element Manager, API Functions