Archicad 28 C++ API
•All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Modules Pages
Archicad 28 C++ API

Getting started with Archicad Add-Ons

The goal of this tutorial is to show you how to write an Archicad Add-On from scratch.

Archicad Add-On Basics

The programming language of Archicad Add-Ons is C++, so you have to be familiar with this language to start. Archicad is extensible in several ways: creating new menu commands and dialogs, import-export functionalities, etc. The API itself is general purpose, so you can write various Add-Ons with the same Development Kit.

What will You Need?

First, you will have to set up your development environment:

  • Archicad - The demo version is perfectly fine for experimenting with the API, but it has some restrictions that you may experience during the development process.
  • API Development Kit - This will allow you to build Archicad Add-Ons on your computer.
  • CMake - To generate IDE projects (3.16 minimum version is needed).
  • Python - For some build tools (version 2.7+ or 3.8+).
  • Depending on your platform you will need a development environment. On Windows this is Microsoft Visual Studio, on MacOS this is Xcode.

For different Archicad versions you will have to use different versions of developer environments. You can see the details in the table below.

Windows MacOS
Archicad 23 Visual Studio 2017 (v141 toolset) Latest Xcode (deployment target macOS 10.12)
Archicad 24 Visual Studio 2017 (v141 toolset) Latest Xcode (deployment target macOS 10.13)
Archicad 25 Visual Studio 2019 (v142 toolset) Latest Xcode (deployment target macOS 10.15)
Archicad 26 Visual Studio 2019 (v142 toolset) Latest Xcode (deployment target macOS 10.15)
Archicad 27 Visual Studio 2019 (v142 toolset) Latest Xcode (deployment target macOS 10.15)
Archicad 28 Visual Studio 2019 (v142 toolset) Latest Xcode (deployment target macOS 11.0)

Structure of the API Development Kit

After you installed the Development Kit you will find three folders at the install location.

  • Documentation: This is the folder for API documentation. You can find here a reference for all of the API functions. The documentation is available online, too.
  • Examples: Here you can find a lot of example Add-Ons. These can be a good starting point to understand how the API works. Feel free to open the IDE projects, and investigate the possibilities.
  • Support: This is the most important folder. It contains all the header and library files for Add-On development, and the tools for resource compilation. This is the folder you will need to build your Add-On.

Let's Build Your First Add-On

You can start with one of the example Add-Ons, but it's much easier to start with the template available on GitHub. Download the Archicad Add-On template from here.

Generate IDE Project for the Add-On

After you downloaded the template Add-On, you have to use CMake to generate the project for your favourite Development Environment. Starting from the root folder you can generate the projects with the commands below. Make sure to replace the value of AC_API_DEVKIT_DIR variable with your DevKit installation folder.

On Windows: 

mkdir Build
cd Build
cmake -G "Visual Studio 16 2019" -A "x64" -DAC\_API\_DEVKIT\_DIR="C:\\API Development Kit 28.3000" ..
cd ..

On MacOS 

mkdir Build
cd Build
cmake -G "Xcode" -DAC\_API\_DEVKIT\_DIR=/Applications/GRAPHISOFT\\ ARCHICAD\\ API\\ DevKit\\ 28.3000 ..
cd ..

Please note the ".." at the end of the commands. It means that CMake will search for the CMakeLists.txt file in the parent folder.

Build the Add-On

After you generated the IDE project, open it, and press Build. If everything goes fine, you will see no errors or warnings, and an .apx file (Windows) / .bundle (macOS) is created in your result folder.

Try the Add-On in Archicad

You have several ways to load the Add-On in Archicad. For development purposes the best if you browse it directly from your build folder, so every modification will appear in Archicad immediately.

1. Open the Add-On Manager Dialog by selecting Options / Add-On Manager.

2. Click the Add button under the EDIT LIST OF AVAILABLE ADD-ONS tabpage.

3. Browse your Add-On's .apx/.bundle file, and if everything went well your Add-On will appear in the list of Add-Ons.

4. After closing the Add-On Manager you will see a new command registered by the Add-On: Options / Example AddOn Command.

5. Click on the command, and you will see a very simple dialog created by the Add-On.

Congratulations! You just built your first Archicad Add-On.

Something doesn't work?

Sometimes you may meet the error messages below. It means that an error happened during the Add-On loading process. There could be several reasons for this issue, see below.

Invalid Development Kit Version

Archicad can't load an Add-On if it was created with a different version of the Development Kit. Double check the version of your Archicad and the used Development Kit, they should match.

Invalid MDID

Please note, that the example Add-On works only with the DEMO version of Archicad. To release your Add-On you have to register for an MDID (see the details in the Releasing Add-Ons chapter). To work around this issue you can start Archicad in DEMO mode by passing a command line parameter to the executable.

On Windows

Archicad.exe -DEMO

On Mac

"Archicad 28.app/Contents/MacOS/Archicad" -demo

Anatomy of an Add-On

You can find several subfolders in the Sources folder.

Add-On Sources

The source code for the Add-On is in the AddOn folder.

There are four important entry points for Add-Ons.

  • CheckEnvironment: This function is called before any other functions. You can check if your Add-On can or allowed to run in the current environment. You also have to provide the Add-On's name and description. This information will appear in the Add-On Manager.
  • RegisterInterface: This function is responsible to register interface elements in Archicad (like menu commands, tool box items, etc.).
  • Initialize: This function is called when the Add-On is loaded into the memory, before performing any of the Add-On's functions.
  • FreeData: This function is called when the Add-On is unloaded from the memory.

You can find a more detailed explanation of these functions here.

API_AddonType CheckEnvironment (API_EnvirParams* envir)
{
RSGetIndString (&envir->addOnInfo.name, ID_ADDON_INFO, 1, ACAPI_GetOwnResModule ());
RSGetIndString (&envir->addOnInfo.description, ID_ADDON_INFO, 2, ACAPI_GetOwnResModule ());
return APIAddon_Normal;
}
GSErrCode RegisterInterface (void)
{
return ACAPI_MenuItem_RegisterMenu (ID_ADDON_MENU, 0, MenuCode_Tools, MenuFlag_Default);
}
GSErrCode Initialize (void)
{
return ACAPI_MenuItem_InstallMenuHandler (ID_ADDON_MENU, MenuCommandHandler);
}
GSErrCode FreeData (void)
{
return NoError;
}
FreeData
GSErrCode FreeData(void)
RegisterInterface
GSErrCode RegisterInterface(void)
In this function the add-on can register its services, and menu commands.
API_AddonType
API_AddonType
Describes the different types of add-ons.
Definition: APIdefs_Registration.h:253
Initialize
GSErrCode Initialize(void)
The main entry point of the add-on.
CheckEnvironment
API_AddonType CheckEnvironment(API_EnvirParams *envirParams)
Defines the behavior of the add-on based on the current running environment.
ACAPI_MenuItem_RegisterMenu
GSErrCode ACAPI_MenuItem_RegisterMenu(short menuStrResID, short promptStrResID, APIMenuCodeID menuPosCode, GSFlags menuFlags)
Registers the menu items of the add-on.
ACAPI_MenuItem_InstallMenuHandler
GSErrCode ACAPI_MenuItem_InstallMenuHandler(short menuStrResID, APIMenuCommandProc *handlerProc)
Installs a callback procedure for handling the add-on's menu commands.
ACAPI_GetOwnResModule
GSResModule ACAPI_GetOwnResModule(void)
Returns the add-on's own resource module identifier for loading resources.
API_AddOnInfo::description
GS::UniString description
The description of the functionality of the add-on, in Unicode.
Definition: APIdefs_Registration.h:117
API_AddOnInfo::name
GS::UniString name
The name of the add-on, in Unicode.
Definition: APIdefs_Registration.h:111
API_EnvirParams
Describes the different parameters of the running environment.
Definition: APIdefs_Registration.h:195
API_EnvirParams::addOnInfo
API_AddOnInfo addOnInfo
Textual description of the add-on; the add-on should fill this in.
Definition: APIdefs_Registration.h:207

Add-On Resources

The source code for resources is in the AddOnResources folder.

  • RFIX: Fix, non-localized resources, like images.
  • RFIX.mac, RFIX.win: Platform dependent utility codes.
  • RINT: Resources to be localized.
  • Tools: Resource builder tool.

Archicad Add-Ons can work on both Windows and macOS platforms, so you can't use native resource files for localized strings and dialogs. This is why we invented the .grc format, which is a platform independent resource description format working on both platforms. It means that you have to define your resources only once, and then the code will work on both platforms without any modifications.

Debugging

Debugging is pretty straightforward. You just have to attach your debugger to the running Archicad process, and then you can debug your Add-On like any other applications. To make the process more smooth, you can set Archicad as the executable for the Add-On project, and just hit debug to start Archicad.

Visual Studio Tips

Make sure that when you attach to the Archicad process, "Native code" is selected in the "Attach to" item in the dialog. Also note, that the breakpoints doesn't seem to be active until your Add-On is loaded into the memory. Just place your breakpoints, call one of the Add-On's functionalities, and it should work.

Call an API Function

Let's write an example Add-On that counts the number of walls in the current plan.

First of all, you have to include a new header file, because some of it's functionalities will be needed. 

#include "StringConversion.hpp"

As you see in the example Add-On you can register a menu command, and then handle it like in the example below. When the user clicks on the command, the code will call the CountNumberOfWalls function to do the job for us.

static GSErrCode MenuCommandHandler (const API_MenuParams *menuParams)
{
switch (menuParams->menuItemRef.menuResID) {
case ID_ADDON_MENU:
switch (menuParams->menuItemRef.itemIndex) {
case 1:
CountNumberOfWalls ();
break;
}
break;
}
return NoError;
}
API_MenuItemRef::menuResID
short menuResID
The resource ID which the tool command belongs to.
Definition: APIdefs_Interface.h:129
API_MenuItemRef::itemIndex
Int32 itemIndex
The index of the command within the specified menu.
Definition: APIdefs_Interface.h:141
API_MenuParams
Describes the menu item that was chosen.
Definition: APIdefs_Callback.h:54
API_MenuParams::menuItemRef
API_MenuItemRef menuItemRef
The menu item chosen by the user. The menuItemRef.menuResID is the same what you called ACAPI_MenuIte...
Definition: APIdefs_Callback.h:60

The CountNumberOfWalls function can be implemented like in the example below.

static void CountNumberOfWalls ()
{
GS::Array<API_Guid> wallGuids;
GSErrCode err = ACAPI_Element_GetElemList (API_WallID, &wallGuids);
if (err != NoError) {
return;
}
USize wallCount = wallGuids.GetSize ();
DG::InformationAlert (GS::ValueToUniString (wallCount), "", "OK");
}
ACAPI_Element_GetElemList
GSErrCode ACAPI_Element_GetElemList(const API_ElemType &type, GS::Array< API_Guid > *elemList, API_ElemFilterFlags filterBits=APIFilt_None, const API_Guid &renovationFilterGuid=APINULLGuid)
Returns an array of guids of the elements of the given type.

It accesses the list of walls from the current plan, and shows the length of the array in a dialog.

If everything is OK, you should see something like this:

Releasing Add-Ons

To release your Add-On and make it work with all Archicad versions, you have to register as an Archicad developer, and get an MDID for your Add-On. MDID is a unique identifier which identifies the Add-On. Please note that Archicad can't load two different Add-Ons with the same MDID, so you have to set up different MDIDs for each of your Add-Ons.

Here you can find detailed instructions on registering an MDID.

Resources

This tutorial covered only the basics, but there are much more.