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