Element Set

Provides functions to create and handle element sets for any kind of purpose. You may also add custom information to the element set. More...

Functions
GSErrCode __ACENV_CALL	ACAPI_ElementSet_Create (GS::Array< API_Guid > *guids, const API_UserData *userData, API_Guid *setGuid)
	Groups elements into an element set.
GSErrCode __ACENV_CALL	ACAPI_ElementSet_Delete (API_Guid setGuid)
	Deletes an existing element set.
GSErrCode __ACENV_CALL	ACAPI_ElementSet_GetData (API_Guid setGuid, GS::Array< API_Guid > *elemGuids, API_UserData *data)
	Retrieves the data of an existing element set.
GSErrCode __ACENV_CALL	ACAPI_ElementSet_Identify (API_Guid elemGuid, GS::Array< API_Guid > *setGuids)
	Retrieves the element sets that contain a given element.

Detailed Description

Provides functions to create and handle element sets for any kind of purpose. You may also add custom information to the element set.

Element Set Manager

The Element Set Manager lets your add-on mark a group of elements to be treated as a collection.

For example you have a building schedule database, and you want to assign elements to the tasks they are involved in. So you can create an element set for this task. Since an element can belong to more than one task, different element sets can contain the same element as well.

The elements in the set are referenced by their GUIDs. The Element Set Manager service automatically updates the GUID lists at merge or paste operations, when ID collision could happen.

You may also attach custom user data to an element set.

Note that from Archicad 12 element sets are referenced with their GUIDs rather than indices, because element sets can be re-indexed during the lifetime of a project, and that could have made difficult to follow up.

Functions

The Element Set Manager functions begin with the ACAPI_ElementSet_ prefix.

• ACAPI_ElementSet_Create
  
• ACAPI_ElementSet_Delete
  
• ACAPI_ElementSet_GetData
  
• ACAPI_ElementSet_Identify

If you would like to store data into the project file that independent from the element database (that is it does not contain element unique ID references), you can use the ModulData Manager service.

Function Documentation

ACAPI_ElementSet_Create()

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

Groups elements into an element set.

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.

Returns

• 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.

Remarks

You can use this function to create an element set for any kind of purpose. Similarly to ACAPI_ElementLink_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);

ACAPI_ElementSet_Delete()

GSErrCode __ACENV_CALL ACAPI_ElementSet_Delete

(

API_Guid

setGuid

)

Deletes an existing element set.

Parameters

setGuid

[in] The GUID of the element set to be deleted.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - 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_BADID - The setGuid parameter is invalid.
• APIERR_NOTMINE - The element set referenced by setGuid is owned by another user.
• APIERR_DELETED - The element set is already deleted.

Remarks

This function deletes an element set identified by the setGuid parameter. Note that you cannot delete element sets created by another add-ons.

Example

// delete all element sets that refer to the element (identify by guid)
void DeleteElementSets (const API_Guid& guid)
{
    GS::Array<API_Guid> setGuids;
    GSErrCode err = ACAPI_ElementSet_Identify (guid, &setGuids);
    if (err == NoError) {
        USize nSet = setGuids.GetSize ();
        ACAPI_CallUndoableCommand ("Delete Element Set",
            [&] () -> GSErrCode {
                for (UIndex i = 0; i < nSet; i++) {
                    err = ACAPI_ElementSet_Delete (setGuids[i]);
                    if (err != NoError) {
                        DBPRINTF ("Delete Element Set error: %d\n", err);
                    }
                }
 
                return NoError;
            });
    }
}

ACAPI_ElementSet_GetData()

GSErrCode __ACENV_CALL ACAPI_ElementSet_GetData	(	API_Guid	setGuid,
		GS::Array< API_Guid > *	elemGuids,
		API_UserData *	data
	)

Retrieves the data of an existing element set.

Parameters

setGuid	[in] The GUID that identifies the element set.
elemGuids	[out] Pointer to the array of element GUIDs.
data	[out] User data assigned to the set.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - The function cannot operate on the current database.
• APIERR_BADID - The setGuid parameter is invalid.
• APIERR_NOTMINE - The element set referenced by setGuid is owned by another user.
• APIERR_DELETED - The element set is already deleted.

Remarks

This function retrieves the element GUID list and the attached user data of an element set created by ACAPI_ElementSet_Create. Both of the output parameters are optional, can be nullptr. Remember to release the userdata.dataHdl handles when you don't need it any more.

ACAPI_ElementSet_Identify()

GSErrCode __ACENV_CALL ACAPI_ElementSet_Identify	(	API_Guid	elemGuid,
		GS::Array< API_Guid > *	setGuids
	)

Retrieves the element sets that contain a given element.

Parameters

elemGuid	[in] The element GUID to search for, or GS::NULLGuid to get all element sets.
setGuids	[out] Array of GUIDs of the element sets that contain the element.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The setGuids parameter is nullptr.
• APIERR_BADDATABASE - The function cannot operate on the current database.

Remarks

You can use this function to identify the element sets that refer to the passed element. Note that element sets created by other add-ons will not be examined. You can get all element sets created by your add-on if you pass GS::NULLGuid in the guid parameter.