Executes tool commands on elements.

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

 

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.

 

Return Values

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

For other common API errors see the API Errors document.

 

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_Element_Tool (&elemList, APITool_Group, nullptr);
}

 

Requirements

Version: API 2.1 or later

Header: ACAPinc.h

 

See Also

API_Elem_Head, API_Guid,
Element Manager, API Functions