ACAPI_ElementSet_Create

Groups elements into an element set.

    GSErrCode  ACAPI_ElementSet_Create (
        GS::Array<API_Guid>*     guids,
        const API_UserData*      userData,
        API_Guid*                setGuid
    );

Parameters

guids: [in] Handle to the array of element GUIDs.
userData: [in] User data assigned to the set (optional, can be nullptr).
setGuid: [out] The unique ID of the newly created element set.

Return Values

NoError: The function has completed with success.
APIERR_BADPARS: guids or setGuid parameter is nullptr.
APIERR_BADDATABASE, APIERR_NOTMINE: The function cannot operate on the current database.
APIERR_NEEDSUNDOSCOPE: The function must be undoable, it wasn’t called from an undoable command scope.
APIERR_BADPLATFORMSIGN: The given platform sign is invalid.
APIERR_MEMFULL: There is not enough memory to complete the operation.

For other common API errors see the API Errors document.

Remarks

You can use this function to create an element set for any kind of purpose. Similarly to ACAPI_Element_Link it creates a logical record which contains a list of element GUIDs you are interested in. You may also add custom information to the element set, as you can store user data to separate elements with ACAPI_Element_SetUserData.

The reference GUID of the newly created element set is returned in the setGuid parameter.

Example


    GS::Array<API_Guid>  guids;

    // get the guids of the first Wall, Column, Beam and Window (API_WallID + 4)
    for (USize i = API_WallID; i < static_cast<USize> (API_WallID) + 4; i++)
    {
        GS::Array<API_Guid> elemList;
        const API_ElemTypeID typeID = static_cast<API_ElemTypeID> (i);
        if (ACAPI_Element_GetElemList (typeID, &elemList, APIFilt_OnVisLayer | APIFilt_OnActFloor) == NoError) {
            if (!elemList.IsEmpty ())
                guids.Push (elemList[0]);
            else
                guids.Push (APNULLGuid);
        }
    }

    // write a note into the user data
    API_UserData userData;
    BNZeroMemory (&userData, sizeof (userData));
    userData.dataVersion = 4;
    userData.platformSign = GS::Act_Platform_Sign;
    userData.dataHdl = BMAllocateHandle (1024, ALLOCATE_CLEAR, 0);
    if (userData.dataHdl != nullptr) {
        sprintf (*userData.dataHdl, "Original element count: 4, guids [%s,%s,%s,%s]",
                 (const char *) APIGuid2GSGuid (guids[0]).ToUniString ().ToCStr (),
                 (const char *) APIGuid2GSGuid (guids[1]).ToUniString ().ToCStr (),
                 (const char *) APIGuid2GSGuid (guids[2]).ToUniString ().ToCStr (),
                 (const char *) APIGuid2GSGuid (guids[3]).ToUniString ().ToCStr ());
    }

    ACAPI_CallUndoableCommand ("Create Element Set",
        [&] () -> GSErrCode {

            API_Guid setGuid;
            GSErrCode err = ACAPI_ElementSet_Create (&guids, &userData, &setGuid);
            if (err != NoError) {
                DBPRINTF ("Create Element Set error: %d/n", err);
            }

            return err;
        });

    BMKillHandle (&userData.dataHdl);

Requirements

Version: API 4.1 or later

Header: ACAPinc.h

Parameters

Return Values

Remarks

Example

Requirements

See Also