ACAPI_​Element_​ChangeDefaults

Changes the default parameters of an element.

    GSErrCode  ACAPI_Element_ChangeDefaults (
        API_Element*           element,
        API_ElementMemo*       memo,
        const API_Element*     mask
    );

 

Parameters

element
[in] Contains the general parameters to which you would like to change the defaults.
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.

 

Return Values

NoError
The function has completed with success.
APIERR_BADPARS
The passed parameter is nullptr; element
APIERR_BADID
The element type is invalid, or
the element type is not supported by the server application
APIERR_REFUSEDCMD
The element type is not a valid target for the operation; API_SectElemID
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 an element type. Only those parameters are changed where the corresponding field in the mask is not 0. The requested type is identified by the type field of the header.

The memo parameter is used only in the case of API_WindowID, API_DoorID, API_ObjectID, API_LampID, API_RoomID, API_LabelID, and API_PictureID. 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_GetDefaults 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.

Note, that the ACAPI_SetDefaults function became obsolete; it was the solution in API 1.3.

In order to change the default settings of markered element types (API_WindowType, API_DoorType, API_CutPlaneType, API_ChangeMarkerType, API_DetailType and API_WorksheetType) use the ACAPI_Element_ChangeDefaultsExt function instead.

 

Example


API_Element    element, mask;
GSErrCode      err;

BNZeroMemory (&element, sizeof (API_Element));

element.header.type = API_WallID;
err = ACAPI_Element_GetDefaults (&element, nullptr);

if (err == NoError) {
    ACAPI_ELEMENT_MASK_CLEAR (mask);
    ACAPI_ELEMENT_MASK_SET (mask, API_Elem_Head, layer);
    element.header.layer = 27;
    err = ACAPI_Element_ChangeDefaults (&element, nullptr, &mask);
}

 

Requirements

Version: API 1.3 or later
Header: ACAPinc.h

 

See Also

API_Element, API_ElementMemo
ACAPI_Element_GetDefaults, ACAPI_DisposeElemMemoHdls
ACAPI_Element_GetDefaultsExt, ACAPI_Element_ChangeDefaultsExt
Element Manager, API Functions