Element Grouping

Functions to create, delete and use groups and sets of different elements. More...

Classes
struct	API_UserData
	Custom data record attached to element sets. More...

Enumerations
enum	API_ToolCmdID {   APITool_Group = 'GRUP' , APITool_Ungroup = 'UGRP' , APITool_SuspendGroups = 'SUSP' , APITool_Lock = 'LOCK' ,   APITool_Unlock = 'ULCK' , APITool_BringToFront = 'OFR0' , APITool_BringForward = 'OFR1' , APITool_SendBackward = 'OBA1' ,   APITool_SendToBack = 'OBA0' , APITool_ResetOrder = 'ORST' }
	It is used at the ACAPI_Grouping_Tool function.

Functions
GSErrCode	ACAPI_Grouping_ChangeSuspendGroup (bool suspendGroups)
	Set 'Suspend Groups' in Archicad.
GSErrCode	ACAPI_Grouping_GetMainGroupGuid (const API_Guid *groupGuid, API_Guid *mainGroupGuid)
	Returns the top level group of a nested group element.
GSErrCode	ACAPI_Grouping_GetConnectedElements (const API_Guid &guid, const API_ElemType &connectedElemType, GS::Array< API_Guid > *connectedElements, API_ElemFilterFlags filterBits=APIFilt_None, const API_Guid &renovationFilterGuid=APINULLGuid)
	Returns a list of elements connected to the given element.
GSErrCode	ACAPI_Grouping_Tool (const GS::Array< API_Guid > &elemGuids, API_ToolCmdID typeID, void *pars)
	Executes tool commands on elements.
GSErrCode	ACAPI_Grouping_CreateGroup (const GS::Array< API_Guid > &elemGuids, API_Guid *groupGuid=nullptr, const API_Guid *parentGroupGuid=nullptr)
	Create an element group.
GSErrCode	ACAPI_Grouping_GetGroup (const API_Guid &elemGuid, API_Guid *groupGuid)
	Returns the group unique ID of the given element.
GSErrCode	ACAPI_Grouping_GetRootGroup (const API_Guid &elemGuid, API_Guid *rootGroupGuid)
	Returns the top level group unique ID of a nested group element.
GSErrCode	ACAPI_Grouping_GetGroupedElems (const API_Guid &groupGuid, GS::Array< API_Guid > *elemGuids)
	Returns the immediate elements of the given group.
GSErrCode	ACAPI_Grouping_GetAllGroupedElems (const API_Guid &groupGuid, GS::Array< API_Guid > *elemGuids)
	Returns all elements of the given group.
GSErrCode	ACAPI_Grouping_GetUserData (const API_Guid &groupGuid, API_UserData *userData)
	Obtains the user data attached to an element group.
GSErrCode	ACAPI_Grouping_SetUserData (const API_Guid &groupGuid, const API_UserData *userData)
	Attaches the user data to the element group.

Detailed Description

Functions to create, delete and use groups and sets of different elements.

Function Documentation

ACAPI_Grouping_ChangeSuspendGroup()

GSErrCode ACAPI_Grouping_ChangeSuspendGroup

(

bool

suspendGroups

)

Set 'Suspend Groups' in Archicad.

Parameters

suspendGroups

[in] Suspend or unsuspend grouping in Archicad.

Returns

• NoError - The function completed with success.
• APIERR_NOPLAN - No user project is open.

Remarks

Suspend groups if you want to perform an operation on an element which is part of a group. Remember to set it back to its previous state when you finished your operation.

ACAPI_Grouping_CreateGroup()

GSErrCode ACAPI_Grouping_CreateGroup	(	const GS::Array< API_Guid > &	elemGuids,
		API_Guid *	groupGuid = nullptr,
		const API_Guid *	parentGroupGuid = nullptr
	)

Create an element group.

Parameters

elemGuids	[in] Array of unique IDs of the elements to group.
groupGuid	[out] Unique ID of the newly created group.
parentGroupGuid	[in] Optional parameter for setting unique ID of the parent group of the newly created group (making a group tree with it).

Returns

• NoError - The function has completed with success, a new element group has created.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADID - One or more of the passed IDs are invalid.
• APIERR_BADPARS - Invalid value passed in the parameters (nullptr pointer, empty ID list, etc.).

Remarks

This function create a simple element group, it becomes only a container of some elements. Passed elements have to be on the same floor.

ACAPI_Grouping_GetAllGroupedElems()

GSErrCode ACAPI_Grouping_GetAllGroupedElems	(	const API_Guid &	groupGuid,
		GS::Array< API_Guid > *	elemGuids
	)

Returns all elements of the given group.

Parameters

groupGuid	[in] Unique ID of the passed group.
elemGuids	[out] Array of all element unique IDs which below the passed group.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Passed group ID is invalid.
• APIERR_BADPARS - Invalid value passed in the parameters.

Remarks

This function is used to get all elements of a given group. The retrieved array contains all elements which are below the group subtree (root of subtree identified the passed groupGuid).

ACAPI_Grouping_GetConnectedElements()

GSErrCode ACAPI_Grouping_GetConnectedElements	(	const API_Guid &	guid,
		const API_ElemType &	connectedElemType,
		GS::Array< API_Guid > *	connectedElements,
		API_ElemFilterFlags	filterBits = APIFilt_None,
		const API_Guid &	renovationFilterGuid = APINULLGuid
	)

Returns a list of elements connected to the given element.

Since

Archicad 26

Parameters

guid	[in] Identifier of the element having other elements connected to it.
connectedElemType	[in] The type of the connected elements to be retrieved. Currently applicable types: API_WindowID, API_DoorID (with Wall elements), API_SkylightID (with Roof and Shell elements), API_LabelID (with all labelable elements, i.e. modeling elements, Curtain Wall subelements, and Fill elements), API_OpeningID
connectedElements	[out] Guid list of the connected elements retrieved.
filterBits	[in] The flags used for filtering (see ACAPI_Element_Filter). The default value is APIFilt_None.
renovationFilterGuid	[in] Optional global unique identifier of the renovation filter. This parameter is currently ignored.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The connectedElements pointer is nullptr.
• APIERR_BADID - The guid parameter does not identify a valid element. Or the given element type cannot be in connection with elements of the requested type.

Remarks

This function can be used to get the elements of the given type and variation, that are connected in an ownership relation with a given element, and match the criteria defined by filterbits (see the filterbits flag values described in the table of ACAPI_Element_Filter). Available connections:

Type of the owner element (specified with guid)	Connected element type (connectedElemTypeID)
API_WallID	API_WindowID, API_DoorID
API_RoofID, API_ShellID	API_SkylightID
All labelable elements	API_LabelID
API_OpeningID	API_WallID, API_SlabID, API_MeshID, API_BeamID

The windows and doors of a given wall element can also be retrieved with the ACAPI_Element_GetMemo function (wallWindows, wallDoors members of API_ElementMemo). When querying the Labels of an element, if the returned GUID array is not empty, the first GUID will be the GUID of the "Listing Label". It is the Label, which can be listed in Interactive Schedule. From version 26 the connectedElemTypeID and variationID parameters were merged into a single API_ElemType parameter.

Example

// list Skylights of the Shell elements
 
GS::Array<API_Guid> shells;
GSErrCode err = ACAPI_Element_GetElemList (API_ShellID, &shells);
if (err == NoError) {
    GS::UniString reportString;
    for (GS::Array<API_Guid>::ConstIterator it = shells.Enumerate (); it != nullptr; ++it) {
        API_Guid shellGuid = *it;
        GS::UniString shellGuidString = APIGuid2GSGuid (shellGuid).ToUniString ();
        GS::Array<API_Guid> skylights;
        err = ACAPI_Grouping_GetConnectedElements (shellGuid, API_SkylightID, &skylights);
        if (err == NoError) {
            if (skylights.IsEmpty ()) {
                reportString = GS::UniString::Printf ("Shell {%T} has no Skylights", shellGuidString.ToPrintf ());
            } else {
                reportString = GS::UniString::Printf ("Skylights in Shell {%T}:", shellGuidString.ToPrintf ());
                for (UIndex i = 0; i < skylights.GetSize (); i++) {
                    API_Element element;
                    BNZeroMemory (&element, sizeof (API_Element));
                    element.header.guid = skylights[i];
                    if (ACAPI_Element_Get (&element) == NoError) {
                        API_LibPart libPart;
                        BNZeroMemory (&libPart, sizeof (API_LibPart));
                        libPart.index = element.skylight.openingBase.libInd;
                        if (ACAPI_LibraryPart_Get (&libPart) == NoError) {
                            reportString.Append (" \"");
                            reportString.Append (libPart.docu_UName);
                            reportString.Append ("\"");
                        }
                        delete libPart.location;
                    }
                }
            }
        } else {
            reportString = GS::UniString::Printf ("Failed to get Skylights for Shell {%T}", shellGuidString.ToPrintf ());
        }
        ACAPI_WriteReport (reportString.ToCStr ().Get (), false);
    }
}

ACAPI_Grouping_GetGroup()

GSErrCode ACAPI_Grouping_GetGroup	(	const API_Guid &	elemGuid,
		API_Guid *	groupGuid
	)

Returns the group unique ID of the given element.

Parameters

elemGuid	[in] Unique ID of the element.
groupGuid	[out] Unique ID of the group which contains the element.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Passed element ID is invalid.
• APIERR_BADPARS - Invalid value passed in the parameters.

Remarks

This function is used to get unique ID of a group for a grouped element.

ACAPI_Grouping_GetGroupedElems()

GSErrCode ACAPI_Grouping_GetGroupedElems	(	const API_Guid &	groupGuid,
		GS::Array< API_Guid > *	elemGuids
	)

Returns the immediate elements of the given group.

Parameters

groupGuid	[in] Unique ID of the passed group.
elemGuids	[out] List of element unique IDs which directly belong to the given group.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Passed group ID is invalid.
• APIERR_BADPARS - Invalid value passed in the parameters.

Remarks

This function is used to get elements of a given group. The retrieved array contains only elements that are directly connected to the given group.

ACAPI_Grouping_GetMainGroupGuid()

GSErrCode ACAPI_Grouping_GetMainGroupGuid	(	const API_Guid *	groupGuid,
		API_Guid *	mainGroupGuid
	)

Returns the top level group of a nested group element.

Parameters

groupGuid	[in] The guid of a group element.
mainGroupGuid	[out] The guid of the root group in the group hierarchy which contains the tested group.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - The groupGuid or the mainGroupGuid parameter is nullptr
• APIERR_BADID - The passed groupGuid does not refer to an existing group element

Remarks

This function is used to obtain the top level group of a nested group element. If the passed group is not part of another group, the function returns the passed group guid as main group guid.

Example

bool    GetMainGroupOfAnElement (const API_Element& element, API_Element* mainGroup)
{
    bool grouped = false;
    API_Guid mainGroupGuid = APINULLGuid;
    ACAPI_Goodies (APIAny_GetMainGroupGuidID
, const_cast<API_Guid*> (&element.header.groupGuid), &mainGroupGuid);
    if (mainGroupGuid != APINULLGuid) {
        grouped = true;
        char msgStr[128];
        sprintf (msgStr, "Main Group Guid: %s", static_cast<const char *> (APIGuid2GSGuid (mainGroupGuid).ToUniString ().ToCStr ()));
        ACAPI_WriteReport (msgStr, false);
 
        if (mainGroup != nullptr) {
            BNZeroMemory (mainGroup, sizeof (API_Element));
            mainGroup->header.guid = mainGroupGuid;
            ACAPI_Element_Get (mainGroup);
        }
    }
    return grouped;
}

ACAPI_Grouping_GetRootGroup()

GSErrCode ACAPI_Grouping_GetRootGroup	(	const API_Guid &	elemGuid,
		API_Guid *	rootGroupGuid
	)

Returns the top level group unique ID of a nested group element.

Parameters

elemGuid	[in] Unique ID of the element.
rootGroupGuid	[out] Unique ID of the root group.

Returns

• NoError - The function has completed with success.
• APIERR_BADID - Passed element ID is invalid.
• APIERR_BADPARS - Invalid value passed in the parameters.

Remarks

This function is used to obtain the top level group of a nested group element. If the passed group is not part of another group, the function returns the passed group guid as main group guid.

ACAPI_Grouping_GetUserData()

GSErrCode ACAPI_Grouping_GetUserData	(	const API_Guid &	groupGuid,
		API_UserData *	userData
	)

Obtains the user data attached to an element group.

Parameters

groupGuid	[in] Unique ID of the element group.
userData	[in/out] Pointer to the new user data.

Returns

• NoError - The function has completed with success, a new user data has attached to the element group.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADID - Passed groupGuid ID is invalid.
• APIERR_BADPARS - One or more passed parameters are nullptr.
• APIERR_NOUSERDATA - No user data attached with the gived signature.
• APIERR_MEMFULL - Out of memory.

Remarks

This function is used to get the user attached data from an element group. Use the ACAPI_Grouping_SetUserData functions to push data into the element group.

ACAPI_Grouping_SetUserData()

GSErrCode ACAPI_Grouping_SetUserData	(	const API_Guid &	groupGuid,
		const API_UserData *	userData
	)

Attaches the user data to the element group.

Parameters

groupGuid	[in] Unique ID of the element group.
userData	[in] Pointer to the new user data.

Returns

• NoError - The function has completed with success, a new user data has attached to the element group.
• APIERR_NEEDSUNDOSCOPE - The function must be undoable, it wasn't called from an undoable command scope.
• APIERR_BADID - Passed groupGuid ID is invalid.
• APIERR_BADPARS - Passed groupGuid parameter is nullptr.
• APIERR_BADPLATFORMSIGN - The given platform sign is invalid (out of range).
• APIERR_MEMFULL - Out of memory.

Remarks

This function is used to attach user data to an element group. Use the ACAPI_Grouping_GetUserData function to get data from the element group. Existing user data can be deleted by setting userData input parameter to nullptr. Note that this function is not undoable. The caller should allocate and deallocate the userData->dataHdl handle.

ACAPI_Grouping_Tool()

GSErrCode ACAPI_Grouping_Tool	(	const GS::Array< API_Guid > &	elemGuids,
		API_ToolCmdID	typeID,
		void *	pars
	)

Executes tool commands on elements.

Parameters

elemGuids	[in] Array containing the GUIDs of the elements to work on.
typeID	[in] Type of the tool command. The possible values are listed below.
pars	Reserved for further use.

Returns

• NoError - The function has completed with success.
• APIERR_BADDATABASE - The current database is not proper for the operation
• APIERR_BADPARS - The passed parameter is incorrect; typeID
• APIERR_MEMFULL - not enough memory to complete the operation

Remarks

This function is used to execute tool commands on a set of elements. The elements are specified in the elemGuids array or if this parameter is an empty array, the function operates on the current selection. The functionality of each tool is equivalent to the corresponding commands of the Tools menu. The following tool commands are available:

API_ToolCmdID	Meaning
APITool_Group	Creates a new group with the passed elements.
APITool_Ungroup	Ungroups the passed elements.
APITool_SuspendGroups	Switches the Suspend Groups mode On/Off.
APITool_Lock	Locks the passed elements.
APITool_Unlock	Unlocks the passed elements.
APITool_BringToFront	Brings the passed elements above all the other.
APITool_BringForward	Moves forward the passed elements.
APITool_SendBackward	Moves backward the passed elements.
APITool_SendToBack	Sends behind the elements to be overlapped by all the other.
APITool_ResetOrder	Resets the default drawing order of the passed elements.

Example

// group all the walls together
 
GS::Array<API_Guid> elemList;
ACAPI_Element_GetElemList (API_WallID, &elemList);
if (!elemList.IsEmpty ()) {
    ACAPI_Grouping_Tool (&elemList, APITool_Group, nullptr);
}