Archicad API DevKit

https://graphisoft.github.io/archicad-api-devkit
Admin
The Archicad API DevKit provides C++ tools and documentation for developing add-ons and extending...
Tokens:2,735,744
Snippets:20,130
Trust Score:8.3
Update:18 hours ago
Show doc for...
Tokens:
Raw
### Element observer callback and installation example

Source: https://graphisoft.github.io/archicad-api-devkit/group___element.html

Example for ACAPI_Element_InstallElementObserver. Defines a helper to get element type string, an element event handler callback, and shows how to attach an observer when an element is copied. The callback uses ACAPI_Notification_GetParentElement and ACAPI_Element_AttachObserver.

```cpp
#define ELEMSTR_LEN 256

bool GetElementTypeString (const API_ElemType& type, char *elemStr)

{

GS::UniString ustr;

GSErrCode err = ACAPI_Element_GetElemTypeName (type, ustr);

if (err == NoError) {

CHTruncate (ustr.ToCStr (), elemStr, ELEMSTR_LEN - 1);

return true;

}

return false;

}

// -----------------------------------------------------------------------------

// Element observer callback function

// -----------------------------------------------------------------------------

static GSErrCode ElementEventHandler (const API_NotifyElementType *elemType)

{

GSErrCode err = NoError;

char msgStr[256];

char elemStr[32];

API_Element parentElement {};

ACAPI_Notification_GetParentElement (&parentElement, nullptr, 0, nullptr);

switch (elemType->notifID) {

case APINotifyElement_Copy:

if (parentElement.header.guid != APINULLGuid && GetElementTypeString (elemType->elemHead.type, elemStr)) {

sprintf (msgStr, "### Element_Manager: %s #%s copied from #%s",

elemStr, APIGuidToString (elemType->elemHead.guid).ToCStr ().Get (),

APIGuidToString (parentElement.header.guid).ToCStr ().Get ());

err = ACAPI_Element_AttachObserver (elemType->elemHead.guid, 0);

}

break;

default:

err = APIERR_NOTSUPPORTED;

break;

}

if (err == NoError)

ACAPI_WriteReport (msgStr, false);

return err;

}

// -----------------------------------------------------------------------------
```

--------------------------------

### Install property visibility handler in Initialize

Source: https://graphisoft.github.io/archicad-api-devkit/group___add_on_integration.html

Example showing how to install a property visibility handler using ACAPI_Property_InstallPropertyVisibilityHandler. It is called from the Initialize function after registering the property handler. The example also installs a menu handler and calls ACAPI_KeepInMemory.

```cpp
//------------------------------------------------------
// Called after the add-on has been loaded into memory
//------------------------------------------------------
GSErrCode APIMenuCommandProc_Main (const API_MenuParams *menuParams);

bool PropertyVisibilityHandler (API_PropertyVisibilityMode visibilityMode, const GS::Array<API_Guid>& classificationGuids, const API_Guid& propertyDefinitionGuid);

GSErrCode Initialize (void)
{
	GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (32500, APIMenuCommandProc_Main);
	if (err != NoError) {
		return err;
	}

	err = ACAPI_Property_InstallPropertyVisibilityHandler (PropertyVisibilityHandler);
	if (err != NoError) {
		return err;
	}

	ACAPI_KeepInMemory (true);
	return NoError;
}
```

--------------------------------

### GetAllDesignOptions example

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_design_options_1_1_design_option_manager.html

Example from the Test / Design Options section. It creates a DesignOptionManager, checks for errors, and iterates over the design options to write their names and GUIDs. The code uses ACAPI::Result and WriteReport.

```cpp
ACAPI::Result<ACAPI::DesignOptions::DesignOptionManager> manager = CreateDesignOptionManager ();

if (manager.IsErr ()) {

WriteReport ("Failed to get Design Option Manager.");

return;

}

const auto options = manager->GetAllDesignOptions ();

if (options.IsErr ()) {

WriteReport ("Failed to get design options.");

return;

}

if (options.Unwrap ().empty ()) {

WriteReport ("There are no design options.");

return;

}

for (const auto& option : options.Unwrap ()) {

WriteReport ("%s (%s)", option.GetName ().ToCStr ().Get (), option.GetGuid ().ToUniString ().ToCStr ().Get ());

}
```

--------------------------------

### Install file type handler in Initialize

Source: https://graphisoft.github.io/archicad-api-devkit/group___add_on_integration.html

Example call to ACAPI_AddOnIntegration_InstallFileTypeHandler3D in the add-on's Initialize function. The handler is installed with command ID 1 and the callback CustomAPIIO3DCommandProc.

```cpp
// -----------------------------------------------------------------------------
// Called when the add-on has been loaded into memory
// -----------------------------------------------------------------------------
GSErrCode Initialize (void)
{
	GSErrCode err = NoError;

	err = ACAPI_AddOnIntegration_InstallFileTypeHandler3D (1, CustomAPIIO3DCommandProc);

	return err;
}
```

--------------------------------

### Initialize() example: register help, menu handler, and notification handlers

Source: https://graphisoft.github.io/archicad-api-devkit/group___add_on_lifetime.html

Shows the typical implementation of Initialize(), the add-on's main entry point. It registers a context-sensitive help location via DG::RegisterAdditionalHelpLocation, installs a menu handler with ACAPI_MenuItem_InstallMenuHandler, and installs change-defaults and project-event notification handlers. The function returns the last error code, which is NoError on success.

```cpp
typedef struct {

	double len;

	Int32 index;

} NType;

GSHandle** handle;

Int32 nAlloc;

Int32 nElem;

// -----------------------------------------------------------------------------

// Called after the Add-On has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize ()

{

	// If the add-on has user interface and wants to use context sensitive help engine

	IO::Location helpLoc;

	ACAPI_GetOwnLocation (&helpLoc);

	DG::RegisterAdditionalHelpLocation (MDID_DeveloperID, MDID_LocalID, &helpLoc, &GS::EmptyUniString, &GS::EmptyUniString, nullptr, &GS::EmptyUniString);

	//

	// Install the menu handler procedure

	//

	GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (32500, MenuCommandHandler);

	if (err != NoError)

		DBPrintf ("Initialize():: ACAPI_MenuItem_InstallMenuHandler failed\n");

	//

	// Install the change defaults notification handler procedure

	//

	API_ToolBoxItem toolBoxItem {};

	toolBoxItem.type = API_ZombieElemID; // for all types

	err = ACAPI_Element_CatchChangeDefaults (&toolBoxItem, APIDefaultsChangeHandler);

	if (err == NoError) {

		err = ACAPI_ProjectOperation_CatchProjectEvent (APINotify_Close, APIProjectEventHandler);

	}

	return err;

} // Initialize
```

--------------------------------

### CreateElementObjectID example: iterate elements and create object IDs

Source: https://graphisoft.github.io/archicad-api-devkit/group___i_f_c.html

Example for IFCAPI::ObjectAccessor::CreateElementObjectID. It retrieves all element GUIDs using ACAPI_Element_GetElemList, then for each GUID creates an API_Elem_Head and calls CreateElementObjectID to get an ObjectID, which is then passed to AddObjectID. Requires IFC In-Out add-on.

```cpp
GS::Array<API_Guid> elementGuids;

ACAPI_Element_GetElemList(API_ElemTypeID::API_ZombieElemID, &elementGuids);

for (const auto& elementGuid : elementGuids) {

API_Elem_Head head{};

head.guid = elementGuid;

auto objectID = IFCAPI::GetObjectAccessor().CreateElementObjectID(head);

AddObjectID(objectID);

}
```

--------------------------------

### Get group name with ACAPI_ProjectInfo_GetGroupName

Source: https://graphisoft.github.io/archicad-api-devkit/group___project_info.html

Retrieves the name of a ProjectInfo group by its GUID. Returns NoError on success or APIERR_BADID if the group GUID does not exist. The example writes the group name to the report window using ACAPI_WriteReport.

```C++
GSErrCode GetGroupName (const API_Guid& groupGuid)

{

GS::UniString name;

GSErrCode err = ACAPI_ProjectInfo_GetGroupName (groupGuid, name);

if (err == NoError) {

ACAPI_WriteReport ("Group name: %s", false, name.ToCStr ().Get ());

}

return err;

}
```

--------------------------------

### Open a project file with ACAPI_ProjectOperation_Open()

Source: https://graphisoft.github.io/archicad-api-devkit/group___project_operation.html

Example from the documentation showing how to open a project file. It sets up API_FileOpenPars, retrieves the application folder, appends the example path, and calls ACAPI_ProjectOperation_Open(). The example also checks the return value and reports an error if opening fails.

```cpp
API_FileOpenPars openPars {};

openPars.fileTypeID = APIFType_PlanFile;

openPars.useStoredLib = true;

IO::Location folderLoc;

API_SpecFolderID specID = API_ApplicationFolderID;

ACAPI_ProjectSettings_GetSpecFolder (&specID, &folderLoc);

folderLoc.AppendToLocal (IO::Name ("Archicad Examples"));

folderLoc.AppendToLocal (IO::Name ("Residential House"));

openPars.file = new IO::Location (folderLoc, IO::Name ("Residential House.pla"));

GSErrCode err = ACAPI_ProjectOperation_Open (&openPars);

if (err != NoError)

ACAPI_WriteReport ("Cannot open the file", true);

delete openPars.file;
```

--------------------------------

### GetActiveDesignOptionsOfCombination usage example

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_design_options_1_1_design_option_manager.html

Shows how to obtain the DesignOptionManager, retrieve design option combinations, and get the active design options of the first combination. The example reports errors and prints the active options with their names and GUIDs.

```cpp
ACAPI::Result<ACAPI::DesignOptions::DesignOptionManager> manager = CreateDesignOptionManager ();

if (manager.IsErr ()) {

WriteReport ("Failed to get Design Option Manager.");

return;

}

const auto combinations = manager->GetDesignOptionCombinations ();

if (combinations.IsErr ()) {

WriteReport ("Failed to get design option combinations.");

return;

}

if (combinations.Unwrap ().empty ()) {

WriteReport ("There are no design option combinations.");

return;

}

const auto combination = combinations.Unwrap ()[0];

const auto options = manager->GetActiveDesignOptionsOfCombination (combination);

if (options.IsErr ()) {

WriteReport ("Failed to get active design options of first combination.");

return;

}

WriteReport ("Active options of combination %s:", combination.GetName ().ToCStr ().Get ());

for (const auto& option : options.Unwrap ()) {

WriteReport ("%s (%s)", option.GetName ().ToCStr ().Get (), option.GetGuid ().ToUniString ().ToCStr ().Get ());

}
```

--------------------------------

### GetRootFolder example from Test / Keynote

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_keynote_1_1_keynote_manager.html

Shows how to create a KeynoteManager, call GetRootFolder(), and handle errors. The example reports failures and returns an error result if the manager or root folder cannot be obtained.

```cpp
ACAPI::Result<ACAPI::Keynote::KeynoteManager> manager = ACAPI::Keynote::CreateKeynoteManager ();

if (manager.IsErr ()) {

Report (GS::UniString ("Failed to get Keynote Manager: ") + manager.UnwrapErr ().text.c_str ());

return ACAPI::Result<ACAPI::Keynote::KeynoteFolder> {manager.UnwrapErr (), manager.Token ()};

}

const ACAPI::Result<ACAPI::Keynote::KeynoteFolder> rootFolder = manager->GetRootFolder ();

if (rootFolder.IsErr ()) {

Report (GS::UniString ("Failed to get keynote root folder: ") + rootFolder.UnwrapErr ().text.c_str ());

return ACAPI::Result<ACAPI::Keynote::KeynoteFolder> {rootFolder.UnwrapErr (), rootFolder.Token ()};

}
```

--------------------------------

### Create and Place EquipmentDefault

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_m_e_p_1_1_equipment_default.html

Example from the 'Test / New MEP' section showing how to create an EquipmentDefault, place it at a given position and direction, and report success. It checks for errors at each step and returns the error kind on failure.

```cpp
auto equipmentDefault = CreateEquipmentDefault ();

if (equipmentDefault.IsErr ())

return equipmentDefault.UnwrapErr ().kind;

ACAPI::Result<UniqueID> equipmentId = equipmentDefault->Place ({ 20.0, 11.5, 0.0 }, { { 1.0, 0.0, 0.0 }, { 0.0, 1.0, 0.0 } }, GenerateAPIGuid ());

if (equipmentId.IsErr ())

return equipmentId.UnwrapErr ().kind;

ACAPI_WriteReport ("Equipment placed successfully", false);
```

--------------------------------

### Get property group name using ACAPI_Property_GetPropertyGroup

Source: https://graphisoft.github.io/archicad-api-devkit/group___property.html

Example function that retrieves a property group by GUID and returns its name. It sets the group's guid, calls ACAPI_Property_GetPropertyGroup, and on success assigns the group's name to the output parameter.

```cpp
GSErrCode GetPropertyGroupName (const API_Guid& guid, GS::UniString& name)

{

API_PropertyGroup group;

group.guid = guid;

GSErrCode error = ACAPI_Property_GetPropertyGroup (group);

if (error == NoError)

name = group.name;

return error;

}
```

--------------------------------

### Create Library Part with Parameters and 2D Script Sections

Source: https://graphisoft.github.io/archicad-api-devkit/group___library_part.html

Legacy example showing how to create a Library Part from scratch, add a parameters section and a 2D binary section, write a 2D script, and save. Uses ACAPI_LibraryPart_Create, ACAPI_LibraryPart_AddSection, ACAPI_LibraryPart_NewSection, ACAPI_LibraryPart_WriteSection, ACAPI_LibraryPart_EndSection, and ACAPI_LibraryPart_Save. Warning: legacy function, use ACAPI::LM::GSMObject setters instead.

```cpp
/* ... ACAPI_Element_Create ... */

/* ... ACAPI_Element_Create ... */

/* ... */

err = ACAPI_LibraryPart_GetSect_2DDrawHdl (&draw2DHdl);

}

if (err == NoError)

err = ACAPI_LibraryPart_Create (&libPart); /* Create the Library Part from scratch */

if (err == NoError) {

section = {};

section.sectType = API_SectParamDef;

err = ACAPI_LibraryPart_AddSection (&section, paramsHdl, nullptr); /* Add parameters section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DDraw;

err = ACAPI_LibraryPart_AddSection (&section, draw2DHdl, nullptr); /* Add 2D binary section */

}

if (err == NoError) {

section = {};

section.sectType = API_Sect2DScript;

err = ACAPI_LibraryPart_NewSection (&section); /* Open the 2D Script section */

if (err == NoError) {

CHCopyC ("rect2 0,0,a,b\n", buffer); /* ...write it */

err = ACAPI_LibraryPart_WriteSection (static_cast<GS::Int32> (strlen (buffer)), buffer);

}

err = ACAPI_LibraryPart_EndSection (); /* ...close it */

}

err = ACAPI_LibraryPart_Save (&libPart); /* Save and register the Library Part */

BMKillHandle (&paramsHdl);

BMKillHandle (&draw2DHdl);
```

--------------------------------

### Initialize function with ACAPI_RegisterModelessWindow

Source: https://graphisoft.github.io/archicad-api-devkit/group___add_on_integration.html

Example of calling ACAPI_RegisterModelessWindow from the Initialize function. It installs a menu handler and registers a modeless palette with various API_PalEnabled flags. The palette GUID is converted using GSGuid2APIGuid. If the menu handler installation fails, an error message is printed.

```cpp
GSErrCode Initialize (void)

{

GSErrCode err = ACAPI_MenuItem_InstallMenuHandler (DGTEST_MENU_STRINGSID, MenuCommandHandler);

// If the palette is constructed and registered, the add-on will be not unloaded from the memory while Archicad runs.

ACAPI_RegisterModelessWindow (OwnerDrawnListBoxPalette::ODLBPaletteRefId (),

OwnerDrawnListBoxPalette::PaletteAPIControlCallBack,

API_PalEnabled_FloorPlan + API_PalEnabled_Section + API_PalEnabled_Elevation +

API_PalEnabled_InteriorElevation + API_PalEnabled_3D +

API_PalEnabled_Detail + API_PalEnabled_Worksheet + API_PalEnabled_Layout +

API_PalEnabled_DocumentFrom3D + API_PalEnabled_ModelCompare, GSGuid2APIGuid (OwnerDrawnListBoxPalette::ODLBPaletteGuid ()));

if (err != NoError)

DBPrintf ("DG_Test:: Initialize() ACAPI_MenuItem_InstallMenuHandler failed\n");

return err;

}
```

--------------------------------

### Merge selected elements with ACAPI_Element_Merge_Elements

Source: https://graphisoft.github.io/archicad-api-devkit/group___element.html

C++ example that gets the current selection, collects the GUIDs of construction elements (handling section elements by using their parent type and GUID), and merges them. It handles errors, including APIERR_NO3D which indicates that only construction elements can be merged.

```cpp
void Do_Merge_Elements (void)
{

	API_SelectionInfo selectionInfo;
	GS::Array<API_Neig> selNeig;
	API_Element element;

	// Get selection
	GSErrCode err = ACAPI_Selection_Get (&selectionInfo, &selNeig, true);
	if (err != NoError && err != APIERR_NOSEL) {
		ErrorBeep ("ACAPI_Selection_GetInfo", err);
		return;
	}

	BMKillHandle ((GSHandle *) &selectionInfo.marquee.coords);

	GS::Array<API_Guid> guid_ElementsToMerge;

	for (Int32 i = 0; i < selectionInfo.sel_nElemEdit; i++) {

		// Get selected element
		element = {};
		element.header.guid = selNeig[i].guid;
		if (ACAPI_Element_Get (&element) != NoError)
			continue;

		API_ElemType tmpType = element.header.type;
		API_Guid tmpGuid = element.header.guid;

		if (tmpType == API_SectElemID) {
			tmpType = element.sectElem.parentType;
			tmpGuid = element.sectElem.parentGuid;
		}

		guid_ElementsToMerge.Push (tmpGuid);
	}

	BMKillHandle ((GSHandle *) &selNeig);

	if (!guid_ElementsToMerge.IsEmpty ()) {
		GSErrCode err = ACAPI_Element_Merge_Elements (guid_ElementsToMerge);
		if (err != NoError) {
			if (err == APIERR_NO3D)
				WriteReport_Alert ("Elements To Merge can be construction elements only.");
			else
				WriteReport_Alert ("ACAPI_Element_Merge_Elements failed: %d", err);
		}
	} else {

```

--------------------------------

### Example: Using ACAPI_LibraryPart_GetSect_ParamDef to create a parameter section

Source: https://graphisoft.github.io/archicad-api-devkit/group___library_part.html

This example shows how to prepare a parameter section for a Library Part using ACAPI_LibraryPart_GetSect_ParamDef. It first searches for an existing Library Part, then creates the parameter section with a=2.0 and b=3.0, and finally sets up the 2D binary section. The example includes placeholder comments for element creation.

```cpp
API_LibPartDetails details {};
API_LibPart libPart {};
GSHandle paramsHdl, draw2DHdl;
API_LibPartSection section;
double a, b;
char buffer[256] = {};
GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);
CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype
GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)
	delete libPart.location;

if (libPart.index != 0) {
	ACAPI_WriteReport ("Test LibPart already exists", true);
	return;
}

paramsHdl = nullptr;
draw2DHdl = nullptr;
a = 2.0; /* Create the parameter section */
b = 3.0;

if (err == NoError) {
	err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);
	if (err == NoError) {
		details.object.fixSize = false;
		details.object.autoHotspot = true;
		err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);
	}
}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */
if (err == NoError) {
	/* ... */
	/* ... ACAPI_Element_Create ... */
	/* ... ACAPI_Element_Create ... */
	/* ... ACAPI_Element_Create ... */
	/* ... */
}
```

--------------------------------

### Retrieve hotlink node tree with ACAPI_Hotlink_GetHotlinkNodeTree

Source: https://graphisoft.github.io/archicad-api-devkit/group___hotlink.html

Shows how to get the root node GUID for a hotlink type and then retrieve the tree structure under it. The example checks for errors, verifies the root node exists in the tree, and writes the GUIDs of main-level hotlink nodes to the report.

```cpp
API_HotlinkTypeID type = APIHotlink_Module;

API_Guid hotlinkRootNodeGuid = APINULLGuid;

if (ACAPI_Hotlink_GetHotlinkRootNodeGuid (&type, &hotlinkRootNodeGuid) == NoError) {

GS::HashTable<API_Guid, GS::Array<API_Guid> > hotlinkNodeTree;

if (ACAPI_Hotlink_GetHotlinkNodeTree (&hotlinkRootNodeGuid, &hotlinkNodeTree) == NoError) {

if (hotlinkNodeTree.ContainsKey (hotlinkRootNodeGuid)) {

ACAPI_WriteReport ("List of main level hotlink nodes:", false);

const GS::Array<API_Guid>& nodeRefList = hotlinkNodeTree.Get (hotlinkRootNodeGuid);

for (UInt32 i = 0; i < nodeRefList.GetSize (); i++) {

char guidStr[64];

APIGuid2GSGuid (nodeRefList[i]).ConvertToString (guidStr);

ACAPI_WriteReport (guidStr, false);

}

} else {

ACAPI_WriteReport ("No hotlink node was found", false);

}

}

}
```

--------------------------------

### Create Library Part with sections using ACAPI_LibraryPart_NewSection

Source: https://graphisoft.github.io/archicad-api-devkit/group___library_part.html

Example showing how to create a Library Part from scratch, including searching for existing parts, setting up parameter definitions, and creating a 2D drawing section. The example uses ACAPI_LibraryPart_NewSection() to open sections and ACAPI_LibraryPart_WriteSection() to add data.

```cpp
API_LibPartDetails details {};
API_LibPart libPart {};

GSHandle paramsHdl, draw2DHdl;
API_LibPartSection section;
double a, b;
char buffer[256] = {};
GSErrCode err;

const GS::UnID unID = BL::BuiltInLibraryMainGuidContainer::GetInstance ().GetUnIDWithNullRevGuid (BL::BuiltInLibPartID::StairLibPartID);

CHCopyC (unID.ToUniString ().ToCStr (), libPart.parentUnID); // General Stair subtype
GS::ucscpy (libPart.docu_UName, L("Test LibPart"));

err = ACAPI_LibraryPart_Search (&libPart, false);

if (libPart.location != nullptr)
	delete libPart.location;

if (libPart.index != 0) {
	ACAPI_WriteReport ("Test LibPart already exists", true);
	return;
}

paramsHdl = nullptr;
draw2DHdl = nullptr;

a = 2.0; /* Create the parameter section */
b = 3.0;

if (err == NoError) {
	err = ACAPI_LibraryPart_GetSect_ParamDef (&libPart, nullptr, &a, &b, nullptr, &paramsHdl);
	if (err == NoError) {
		details.object.fixSize = false;
		details.object.autoHotspot = true;
		err = ACAPI_LibraryPart_SetDetails_ParamDef (&libPart, paramsHdl, &details);
	}
}

err = ACAPI_LibraryPart_SetUpSect_2DDrawHdl (); /* Create the 2DBinary section */
```

--------------------------------

### GetOverrideRuleNames: Retrieve and convert override rule GUIDs to names

Source: https://graphisoft.github.io/archicad-api-devkit/group___graphical_override.html

Example function that calls ACAPI_GraphicalOverride_GetOverrideRuleList to get all override rule GUIDs, then iterates through them, retrieves each rule by ID, and pushes the rule name into an array. Returns NoError on success or the error from the API calls.

```cpp
GSErrCode GetOverrideRuleNames (GS::Array<GS::UniString>& ruleNames)

{

GS::Array<API_Guid> rulesGuids;

GSErrCode error = ACAPI_GraphicalOverride_GetOverrideRuleList (rulesGuids);

if (error == NoError) {

for (USize i = 0; i < rulesGuids.GetSize(); ++i) {

API_OverrideRule rule = {rulesGuids[i]};

error = ACAPI_GraphicalOverride_GetOverrideRuleById (rule);

if (error == NoError) {

ruleNames.Push (rule.name);

}

}

}

return error;

}
```

--------------------------------

### Place routes using placement data

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_m_e_p_1_1_routing_element_default.html

This example shows how to place routes using the placement data. It reserves space for route IDs and creates a RoutingElementDefault using CreateRoutingElementDefault with the given domain.

```cpp
std::vector<UniqueID> routeIds;

routeIds.reserve (placementData.size ());

ACAPI::Result<RoutingElementDefault> routingElementDefault = CreateRoutingElementDefault (domain);
```

--------------------------------

### Get user data from element by GUID using ACAPI_Element_GetUserData

Source: https://graphisoft.github.io/archicad-api-devkit/group___user_data.html

Shows how to retrieve user data from a specific element by setting only the guid field in API_Elem_Head and passing it to ACAPI_Element_GetUserData. The example checks for NoError, valid data handle, and platform sign before casting, then kills the handle.

```cpp
//------------------------------------------------------------
// Obtain user data from an element identified by guid
//------------------------------------------------------------
GSErrCode GetUserDataFromElem (const API_Guid selectedElemGuid, CustomData** data)
{
    API_Elem_Head element {};
    element.guid = selectedElemGuid;
    API_ElementUserData userData {};
    GSErrCode err = ACAPI_Element_GetUserData (&element, &userData);
    if (err == NoError && userData.dataHdl != nullptr && userData.platformSign == GS::Act_Platform_Sign)
        *data = reinterpret_cast<CustomData*>(*userData.dataHdl);
    BMKillHandle (&userData.dataHdl);
    return NoError;
}
```

--------------------------------

### Place Ventilation and Piping Accessories with CreateAccessoryDefault

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_m_e_p_1_1_accessory_default.html

Example from Test / New MEP showing how to create and place Accessory elements for ventilation and piping domains. It uses CreateAccessoryDefault, checks for errors, places the accessory with a position and direction, and writes a report on success. Requires Archicad 27.

```cpp
{
	auto ductAccessoryDefault = CreateAccessoryDefault (Domain::Ventilation);

	if (ductAccessoryDefault.IsErr ())
		return ductAccessoryDefault.UnwrapErr ().kind;

	ACAPI::Result<UniqueID> accessoryId = ductAccessoryDefault->Place ({ 0.0, 13.0, 0.0 }, { { -1.0, 0.0, 0.0 }, { 0.0, 1.0, 0.0 } }, GenerateAPIGuid ());

	if (accessoryId.IsErr ())
		return accessoryId.UnwrapErr ().kind;

	ACAPI_WriteReport ("Ventilation Accessory placed successfully", false);
}

{
	auto pipeAccessoryDefault = CreateAccessoryDefault (Domain::Piping);

	if (pipeAccessoryDefault.IsErr ())
		return pipeAccessoryDefault.UnwrapErr ().kind;

	ACAPI::Result<UniqueID> accessoryId = pipeAccessoryDefault->Place ({ 10.0, 13.0, 0.0 }, { { -1.0, 0.0, 0.0 }, { 0.0, 1.0, 0.0 } }, GenerateAPIGuid ());

	if (accessoryId.IsErr ())
		return accessoryId.UnwrapErr ().kind;

	ACAPI_WriteReport ("Piping Accessory placed successfully", false);
}
```

--------------------------------

### Get element descriptors with ACAPI_Element_GetDescriptors

Source: https://graphisoft.github.io/archicad-api-devkit/group___library_management.html

Example function that retrieves descriptors for a given element GUID. It calls ACAPI_Element_GetDescriptors and iterates over the returned descriptors, handling different statuses (APIDBRef_Normal, APIDBRef_Local).

```cpp
void GetDiscriptors (const API_Guid& guid)
{
	API_Elem_Head elemHead {};
	API_DescriptorRefType **descRefs;
	API_ListData listdata;
	Int32 nDesc, i;
	char s[256];
	GSErrCode err;

	elemHead.guid = guid;

	err = ACAPI_Element_GetDescriptors (&elemHead, &descRefs, &nDesc);
	if (err == NoError) {
		for (i = 0; i < nDesc; i++) {
			listdata.header.typeID = API_Obsolete_ComponentID;
			listdata.header.index = (*descRefs)[i].index;
			listdata.header.setIndex = (*descRefs)[i].setIndex;

			if ((*descRefs)[i].status != APIDBRef_Deleted) {
				listdata = {};
				listdata.header.typeID = API_DescriptorID;
				listdata.header.setIndex = (*descRefs)[i].setIndex;
				listdata.header.index = (*descRefs)[i].index;

				switch ((*descRefs)[i].status) {
					case APIDBRef_Normal:
						err = ACAPI_OldListing_Get (&listdata);
						break;
					case APIDBRef_Local:
```

--------------------------------

### Setup morph element and create body data object

Source: https://graphisoft.github.io/archicad-api-devkit/group___body.html

Initializes a morph element, gets its defaults, creates a memo, and creates a body data object. This is the first part of the example for ACAPI_Body_AddPolyNormal.

```cpp
// setup a new morph element
API_Element element {};
element.header.type = API_MorphID;
GSErrCode err = ACAPI_Element_GetDefaults (&element, nullptr);

// setup a new memo
API_ElementMemo memo {};

// create a new body data object
void* bodyData = nullptr;
err = ACAPI_Body_Create(nullptr, nullptr, &bodyData);

API_Coord3D coord;
UInt32 vertices[8];
Int32 edges[8];
Int32 polyNormals[1];
UInt32 polygons[1];
```

--------------------------------

### Arc input example using ACAPI_UserInput_GetPoint and ACAPI_UserInput_GetLine

Source: https://graphisoft.github.io/archicad-api-devkit/group___user_input.html

C++ example showing how to set up point and line input for defining an arc. It initializes pointInfo, lineInfo, and arcInfo structures, sets cursor sets, and calls ACAPI_UserInput_GetPoint and ACAPI_UserInput_GetLine. The example is incomplete as shown in the source.

```C++
API_GetPointType pointInfo {};
API_GetLineType lineInfo {};
API_GetArcType arcInfo {};
char buffer [256];
GSErrCode err;
CHCopyC ("Click the arc center point", pointInfo.prompt);
pointInfo.changeCursorSet = true;
/* show cross cursors suggesting the center point */
pointInfo.cursorSet.nothingOnCursor = APICursor_XPoint;
pointInfo.cursorSet.pointOnCursor = APICursor_ArrowXPoint;
pointInfo.cursorSet.lineOnCursor = APICursor_PencilXPoint;
pointInfo.cursorSet.refPointOnCursor = APICursor_ArrowXPoint;
pointInfo.cursorSet.refLineOnCursor = APICursor_PencilXPoint;
pointInfo.cursorSet.crossOnCursor = APICursor_ArrowXPoint;
pointInfo.cursorSet.normalOnCursor = APICursor_PencilXPoint;
pointInfo.cursorSet.tangentOnCursor = APICursor_ArrowXPoint;
err = ACAPI_UserInput_GetPoint (&pointInfo, nullptr);
if (!err) {
CHCopyC ("Enter the arc start point", lineInfo.prompt);
lineInfo.startCoord = pointInfo.pos;
lineInfo.changeCursorSet = true;
/* use hand cursors for drawing the radius of the arc */
```

--------------------------------

### CreateEquipmentDefault and Place

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_m_e_p_1_1_equipment_default.html

Example code snippet from Test / New MEP Placement demonstrating how to create an EquipmentDefault and place an Equipment element.

```APIDOC
## CreateEquipmentDefault and Place

### Description
Creates an EquipmentDefault and places an Equipment element at a given position and orientation.

### Method
N/A (C++ API)

### Endpoint
N/A (C++ API)

### Parameters
#### Function: CreateEquipmentDefault
- No parameters.

#### Method: Place
- **position** (Point3D) - Required - The position where the equipment will be placed.
- **orientation** (Orientation) - Required - The orientation of the equipment.
- **guid** (GUID) - Required - The unique identifier for the equipment.

### Request Example
```cpp
auto equipmentDefault = CreateEquipmentDefault();
if (equipmentDefault.IsErr())
    return equipmentDefault.UnwrapErr().kind;

ACAPI::Result<UniqueID> equipmentId = equipmentDefault->Place({ 20.0, 11.5, 0.0 }, { { 1.0, 0.0, 0.0 }, { 0.0, 1.0, 0.0 } }, GenerateAPIGuid());
if (equipmentId.IsErr())
    return equipmentId.UnwrapErr().kind;

ACAPI_WriteReport("Equipment placed successfully", false);
```

### Response
#### Success Response
- **equipmentId** (Result<UniqueID>) - The unique ID of the placed equipment.

#### Response Example
```cpp
// No explicit response example provided.
```
```

--------------------------------

### GetElementsOfDesignOption example

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_design_options_1_1_design_option_manager.html

Example from Test / Design Options that creates a DesignOptionManager, retrieves all design options, and then gets the elements linked to the first design option. It reports each element's GeneralElementID property value and GUID. Requires a valid design option manager and at least one design option.

```cpp
ACAPI::Result<ACAPI::DesignOptions::DesignOptionManager> manager = CreateDesignOptionManager ();

if (manager.IsErr ()) {

WriteReport ("Failed to get Design Option Manager.");

return;

}

const auto options = manager->GetAllDesignOptions ();

if (options.IsErr ()) {

WriteReport ("Failed to get design options.");

return;

}

if (options.Unwrap ().empty ()) {

WriteReport ("There are no design options.");

return;

}

const auto option = options.Unwrap ()[0];

const auto elements = manager->GetElementsOfDesignOption (option);

if (elements.IsErr ()) {

WriteReport ("Failed to get elements linked to the first design option.");

return;

}

WriteReport ("Elements of design option %s:", option.GetName ().ToCStr ().Get ());

for (const auto& elemGuid : elements.Unwrap ()) {

GS::Array<API_Property> properties;

GS::Array<API_Guid> propertyGuids = {APIGuidFromString ("7E221F33-829B-4FBC-A670-E74DABCE6289")}; //guid of Property::GeneralElementIDPropertyId

GSErrCode err = ACAPI_Element_GetPropertyValuesByGuid (elemGuid, propertyGuids, properties);

if (err != NoError) {

WriteReport ("Failed to get value for %s", APIGuidToString (elemGuid).ToCStr ().Get ());

return;

}

GS::UniString valueInString;

ACAPI_Property_GetPropertyValueString (properties.GetFirst (), &valueInString);

WriteReport ("%s (%s)", valueInString.ToCStr ().Get (), APIGuidToString (elemGuid).ToCStr ().Get ());

}
```

--------------------------------

### Get property definition name using ACAPI_Property_GetPropertyDefinition

Source: https://graphisoft.github.io/archicad-api-devkit/group___property.html

Example function that retrieves a property definition by GUID and returns its name. It sets the definition.guid, calls ACAPI_Property_GetPropertyDefinition, and on success copies the definition.name to the output parameter.

```cpp
GSErrCode GetPropertyDefinitionName (const API_Guid& guid, GS::UniString& name)

{

API_PropertyDefinition definition;

definition.guid = guid;

GSErrCode error = ACAPI_Property_GetPropertyDefinition (definition);

if (error == NoError)

name = definition.name;

return error;

}
```

--------------------------------

### Initialize: Install Element Observer

Source: https://graphisoft.github.io/archicad-api-devkit/group___element.html

Called after the Add-On has been loaded into memory. Installs an element observer to catch changes in the selection.

```cpp
// Called after the Add-On has been loaded into memory

// -----------------------------------------------------------------------------

GSErrCode Initialize ()

{

// catch changes in the selection

return ACAPI_Element_InstallElementObserver (ElementEventHandler);

}
```

--------------------------------

### Example: WriteElementDefaultDetails

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_m_e_p_1_1_port_default_base.html

Example code snippet from Test / New MEP demonstrating how to access and configure Ports of MEPElementDefaults using getters for ventilation and piping port defaults.

```APIDOC
## Example: WriteElementDefaultDetails

### Description
Example code snippet showing how to retrieve and report details of ventilation and piping port defaults from an ElementDefault.

### Code
```cpp
void WriteElementDefaultDetails (const ElementDefault& mepElemDefault)
{
    Reporter elementDefaultReporter;
    elementDefaultReporter.Add ("Domain of default", mepElemDefault.GetDomain ());

    uint32_t portCount = mepElemDefault.GetPortCount ();
    for (uint32_t portIdx = 0; portIdx < portCount; portIdx++) {
        elementDefaultReporter.SetTabCount (1);

        ACAPI::Result<VentilationPortDefault> ventilationPortDefault = mepElemDefault.GetVentilationPortDefault (portIdx);
        if (ventilationPortDefault.IsOk ()) {
            elementDefaultReporter.Add ("Port name", ventilationPortDefault->GetName ());
            elementDefaultReporter.SetTabCount (2);
            elementDefaultReporter.Add ("Domain", ventilationPortDefault->GetDomain ());
            elementDefaultReporter.Add ("Width", ventilationPortDefault->GetWidth ());
            elementDefaultReporter.Add ("Height", ventilationPortDefault->GetHeight ());
            elementDefaultReporter.Add ("Shape", ventilationPortDefault->GetShape ());
            elementDefaultReporter.Add ("MEPSystem", ventilationPortDefault->GetMEPSystem ());
            elementDefaultReporter.Add ("WallThickness", ventilationPortDefault->GetWallThickness ());
            elementDefaultReporter.Add ("FlowDirection", ventilationPortDefault->GetFlowDirection ());
            elementDefaultReporter.Add ("ConnectionStyle", ventilationPortDefault->GetConnectionStyle ());
            if (ventilationPortDefault->GetFlangeSize ().has_value ())
                elementDefaultReporter.Add ("FlangeSize", *ventilationPortDefault->GetFlangeSize ());
        } else {
            ACAPI::Result<PipingPortDefault> pipingPortDefault = mepElemDefault.GetPipingPortDefault (portIdx);
            if (pipingPortDefault.IsOk ()) {
                elementDefaultReporter.Add ("Port name", pipingPortDefault->GetName ());
                elementDefaultReporter.SetTabCount (2);
                elementDefaultReporter.Add ("Domain", pipingPortDefault->GetDomain ());
                elementDefaultReporter.Add ("Diameter", pipingPortDefault->GetDiameter ());
                elementDefaultReporter.Add ("Shape", pipingPortDefault->GetShape ());
                elementDefaultReporter.Add ("MEPSystem", pipingPortDefault->GetMEPSystem ());
                elementDefaultReporter.Add ("WallThickness", pipingPortDefault->GetWallThickness ());
                elementDefaultReporter.Add ("FlowDirection", pipingPortDefault->GetFlowDirection ());
                elementDefaultReporter.Add ("ConnectionStyle", pipingPortDefault->GetConnectionStyle ());
                if (pipingPortDefault->GetFlangeSize ().has_value ())
                    elementDefaultReporter.Add ("FlangeSize", *pipingPortDefault->GetFlangeSize ());
            }
        }
    }
}
```
```

--------------------------------

### Retrieve renovation filters and update view filter

Source: https://graphisoft.github.io/archicad-api-devkit/group___renovation.html

Example usage of ACAPI_Renovation_GetRenovationFilters() to get the list of renovation filter GUIDs and update a view's renovationFilterGuid to the next filter in the list, wrapping around to the first if at the end.

```cpp
GS::Array<API_Guid> renFilters;

GSErrCode err = ACAPI_Renovation_GetRenovationFilters(&renFilters);

if (err == NoError) {

GS::USize nRenFilters = renFilters.GetSize();

for (GS::UIndex i = 0; i < nRenFilters; ++i) {

if (oldView.renovationFilterGuid == renFilters[i]) {

newView.renovationFilterGuid = renFilters[i + 1 >= nRenFilters ? 0 : i + 1];

break;

}

}

}
```

--------------------------------

### Initialize

Source: https://graphisoft.github.io/archicad-api-devkit/group___element.html

Called after the Add-On has been loaded into memory. Installs an element observer to catch changes in the selection.

```APIDOC
## Initialize

### Description
Called after the Add-On has been loaded into memory. Installs an element observer to catch changes in the selection.

### Function Signature
GSErrCode Initialize ()

### Returns
- GSErrCode - The result of installing the element observer.

### Example
GSErrCode Initialize ()
{
    // catch changes in the selection
    return ACAPI_Element_InstallElementObserver (ElementEventHandler);
}
```

--------------------------------

### Get Main Group of an Element (C++)

Source: https://graphisoft.github.io/archicad-api-devkit/group___grouping.html

Example function that retrieves the main group of an element using ACAPI_Grouping_GetMainGroupGuid(). It checks if the element is grouped, writes a report with the main group GUID, and optionally retrieves the main group element.

```cpp
bool GetMainGroupOfAnElement (const API_Element& element, API_Element* mainGroup)

{

bool grouped = false;

API_Guid mainGroupGuid = APINULLGuid;

ACAPI_Grouping_GetMainGroupGuid (&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) {

mainGroup->header.guid = mainGroupGuid;

ACAPI_Element_Get (mainGroup);

}

}

return grouped;

}
```

--------------------------------

### ACAPI_Attribute_GetFolder example

Source: https://graphisoft.github.io/archicad-api-devkit/group___attribute.html

Example showing how to retrieve an attribute folder by setting typeID and guid, then iterating over its path. Requires a valid folder GUID and an open project.

```cpp
API_AttributeFolder folder {};

folder.typeID = API_LinetypeID;
folder.guid = GS::Guid ("27075EFF-611F-4B11-9BBB-553AC8BDA922");

DBVERIFY (ACAPI_Attribute_GetFolder (folder) == NoError);

for (const auto& name : folder.path) {
	ACAPI_WriteReport (name, false);
	// ...
}
```

--------------------------------

### CreateAccessoryDefault and Place

Source: https://graphisoft.github.io/archicad-api-devkit/class_a_c_a_p_i_1_1_m_e_p_1_1_accessory_default.html

Example code snippet from Test / New MEP Placement showing how to create an AccessoryDefault and place an Accessory element.

```APIDOC
## CreateAccessoryDefault and Place

### Description
Creates an AccessoryDefault for a given domain and places an Accessory element at a specified location and orientation.

### Method
CreateAccessoryDefault and Place

### Parameters
- **domain** (Domain) - Required - The MEP domain (e.g., Ventilation, Piping).
- **position** (Point3D) - Required - The placement position.
- **orientation** (Orientation) - Required - The orientation of the accessory.
- **guid** (Guid) - Required - The unique identifier for the accessory.

### Request Example
```cpp
auto ductAccessoryDefault = CreateAccessoryDefault(Domain::Ventilation);
if (ductAccessoryDefault.IsErr())
    return ductAccessoryDefault.UnwrapErr().kind;

ACAPI::Result<UniqueID> accessoryId = ductAccessoryDefault->Place({ 0.0, 13.0, 0.0 }, { { -1.0, 0.0, 0.0 }, { 0.0, 1.0, 0.0 } }, GenerateAPIGuid());
if (accessoryId.IsErr())
    return accessoryId.UnwrapErr().kind;

ACAPI_WriteReport("Ventilation Accessory placed successfully", false);
```

### Response
#### Success Response
- **accessoryId** (ACAPI::Result<UniqueID>) - The unique ID of the placed accessory.

#### Response Example
```cpp
// No explicit response example provided.
```
```

--------------------------------

### Export DWG via ExternalCall - Setup and Parameter Initialization

Source: https://graphisoft.github.io/archicad-api-devkit/group___add_on_add_on_communication.html

This snippet shows the setup for calling the DXF/DWG add-on synchronously in an external Archicad. It initializes the module ID, project file location, output location, configuration file, and parameter handle. The code is incomplete as shown in the source; it ends mid-statement.

```C++
API_ModulID mdid = { 1198731108, 1322668197 }; // MDID of the DXF/DWG add-on

IO::Location projectFileLoc;

API_SpecFolderID specFolderID = API_ApplicationFolderID;

ACAPI_ProjectSettings_GetSpecFolder (&specFolderID, &projectFileLoc);

projectFileLoc.AppendToLocal (IO::Name ("Archicad Examples"));

projectFileLoc.AppendToLocal (IO::Name ("Residential House"));

projectFileLoc.AppendToLocal (IO::Name ("Residential House.pla"));

IO::Location outputLoc;

specFolderID = API_UserDocumentsFolderID;

ACAPI_ProjectSettings_GetSpecFolder (&specFolderID, &outputLoc);

outputLoc.AppendToLocal (IO::Name ("Residential House.DWG"));

IO::Location configFile; // translator to be applied for this output

specFolderID = API_DefaultsFolderID;

ACAPI_ProjectSettings_GetSpecFolder (&specFolderID, &configFile);

configFile.AppendToLocal (IO::Name ("DXF-DWG Translators"));

configFile.AppendToLocal (IO::Name ("For as is output.Xml"));

GSHandle parHdl = nullptr; // handle of command call parameters

GSErrCode err = ACAPI_AddOnAddOnCommunication_InitMDCLParameterList (&parHdl);

if (err == NoError) {

API_MDCLParameter par; // parameter describing the output file

char str[512];

IO::URL url;
```
Tokens:
Raw