Attaches the user data to an element or an element default.

    GSErrCode  ACAPI_Element_SetUserData (
        API_Elem_Head*                 elemHead,
        const API_ElementUserData*     userData
    );

 

Parameters

elemHead

[in] Header of the element (only fields type and guid are used).

userData

[in] Pointer to the new user data.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

Any of the passed parameters is nullptr

APIERR_BADPLATFORMSIGN

The given platform sign is invalid (out of range)

APIERR_MEMFULL

Out of memory

For other common API errors see the API Errors document.

 

Remarks

This function is used to push the user attached data into an element default or into an element. To set data to element default only elemHead->type is necessary and elemHead->guid should be APINULLGuid. To set data to an element only elemHead->guid is necessary and it should be set to element’s guid. Use the ACAPI_Element_GetUserData function to get data from the element record.

Note that this function is not undoable in case of element default setting.

The caller should allocate and deallocate the userData->dataHdl handle.

 

Example

//------------------------------------------------------------
// Set user data to wall default element
//------------------------------------------------------------

GSErrCode SetUserDataToWallDefaultElem (const CustomData& data)
{
    API_Elem_Head wallDefault = {};
    wallDefault.type = API_WallID;

    API_ElementUserData userData = {};
    userData.dataVersion = 1;
    userData.platformSign = GS::Act_Platform_Sign;
    userData.flags = APIUserDataFlag_FillWith | APIUserDataFlag_Pickup;
    userData.dataHdl = BMAllocateHandle (sizeof (data), ALLOCATE_CLEAR, 0);
    
    *reinterpret_cast<CustomData*> (*userData.dataHdl) = data;
    GSErrCode err = ACAPI_Element_SetUserData (&wallDefault, &userData);

    BMKillHandle (&userData.dataHdl);

    return err;
}

//------------------------------------------------------------
// Set user data to an element identified by guid
//------------------------------------------------------------

GSErrCode SetUserDataToElem (const API_Guid& selectedElemGuid, const CustomData& data)
{
    API_Elem_Head element = {};
    element.guid = selectedElemGuid;

    API_ElementUserData userData = {};
    userData.dataVersion = 1;
    userData.platformSign = GS::Act_Platform_Sign;
    userData.flags = APIUserDataFlag_FillWith | APIUserDataFlag_Pickup;
    userData.dataHdl = BMAllocateHandle (sizeof (data), ALLOCATE_CLEAR, 0);
    
    *reinterpret_cast<CustomData*> (*userData.dataHdl) = data;

    GSErrCode err = ACAPI_CallUndoableCommand ("Set user data to an elem",
        [&userData, &element] () -> GSErrCode {
            return ACAPI_Element_SetUserData (&element, &userData);
        }
    );

    BMKillHandle (&userData.dataHdl);

    return err;
}

        

 

Requirements

Version: API 3.1 or later

Header: ACAPinc.h

 

See Also

API_Elem_Head, API_ElementUserData,
ACAPI_Element_GetUserData,
Element Manager, API Functions