Getting Started with the API DevKit

[mtron]

Creating custom add-ons for ARCHICAD requires a solid knowledge of C and C++ as well as a willingness to learn through studying sample code, documentation, and header files. Be sure that you have read the "API White Paper" in the documentation to be sure that the API Development Kit is likely to allow the kind of extension to ARCHICAD that you envision. Browse through the other documents and, in particular, browse through some of the example code to be sure that this kind of programming is within your capabilities. (Note, too, that there is a separate Rendering Developer Kit also. While not discussed directly here, that kit allows you to write export add-ons that are invoked from the 3D window.)

Registration

You can register online with your GraphisoftID on the ARCHICAD API Developer Site for free. With this, you can become an ARCHICAD API developer and receive an authorization code that makes Add-Ons compatible with the full version of ARCHICAD.

Support

On the ARCHICAD API Developer Site registered ARCHICAD API developers can download the API and other development kits, read and search the latest API documentation online, scroll through the most frequently asked questions, read regular blog posts on the API. As an ARCHICAD API developer, you can also purchase an ARCHICAD 1 year license (optional), and opt-in for the GRAPHISOFT Developer Support service for an annual fee (optional). User-to-user support is available in the Developer forum of ARCHICAD-talk.

Required Software Environment

Add-ons may be compiled with a variety of resources, however, the task is easiest if the development environments for which the examples were created are used, a little or no work will be required on your part to compile and test the examples since the project files will just open and build. Separate versions must be compiled with separate development tools for Intel Mac and Windows (only the 64-bit architecture is supported and the PPC processor is not supported anymore). For ARCHICAD 20 development, free development tools are available for Windows and MacTel.

On Windows, all examples can be built using the free Microsoft Visual C++ 2010 or 2015 Express Edition (Windows 8.1 and 10 SDK is required). Of course, if you already own Visual Studio 2010 or 2015, it has more features.

On Intel Macs, the free Xcode is all that is required. Please note, though, ARCHICAD 12 was the last version that supported the PPC processor and that OS X Leopard (10.5) is the last version of OS X that will support PPC. It is technically possible to use other languages and development tools, but no others are officially supported. You may find yourself fighting with libraries and interface issues.

Read ARCHICAD system requirements and recommended hardware on this topic.

The MDID Resource and Generating an Add-On ID (AddOnAdmin)

Each add-on, including each example, contains a number of *.grc resource files ("Graphisoft Resource Compiler"). One of these files defines the MDID resource to identify the add-on. This consists of a Developer ID and a Local ID (add-on ID). With the out-of-box IDs, the example add-ons will compile and run only when ARCHICAD is in "Demo" mode. This may be good enough for your purposes.

If you have registered (see above) and obtained a Developer ID from GRAPHISOFT, you can then compile add-ons that function in licensed copies of ARCHICAD. To do that, you must run the AddOnAdmin tool to generate an add-on ID and then enter your personal code and that ID in a resource file for the add-on. You'll find the AddOnAdmin tool for Windows in \Support\Tools\Win\AddOn Management and for Mac in Support > Tools > OSX > AddOnAdmin Remember: you do not need to perform this step to explore the API DevKit examples or to write your own add-ons. They will all run just fine in when ARCHICAD is running in "Demo" mode.

AddOnAdmin has two functions: managing a database of generated add-on identifiers and checking the status of existing add-ons. With the Database function selected, click the "New Database" button and enter your four-character Developer ID that GRAPHISOFT sent to you.

• 

Next, select the Developer ID entry in the database window and click the "New Addon" button. You'll get a dialog asking for your Authorization code, which GRAPHISOFT would also have sent to you with your Developer ID.

• 

A new entry is created in the database. You can give it any name you'd like, but a name that reminds you of the add-on to which the ID will be assigned will help you in the future. Note: a (fairly large) fixed number of Add-On IDs can be generated from each Developer ID, so if you don't use this ID for the intended add-on, you might just rename it and use it for another. You'll see something like this:

• 

Note, too, that if you attempt to assign the same Add-On ID to more than one add-on, then only one of those add-ons will load. The ID must be unique for each loaded add-on. You will need the numeric equivalent of your four-character Developer ID as well as the LocalID in order to define the MDID resource which allows your add-on to run in a licensed copy of ARCHICAD. AddOnAdmin has a 'Save Database As' button which gives the option of saving the database as a C header file. You must select the top line (database name) in the database window for this button to be enabled. You can see the Save dialog in the next screenshot:

• 

Note that there is currently a bug (scheduled to be fixed) which prevents the header file from being saved in the selected location on Mac. At present, the header file is saved at the root of the boot drive, regardless of the folder selected in the Save dialog above, and the name of the file created there consists of the text of the entire path of where the header was supposed to be saved. Simply rename the file and move it to where you want it until the bug is fixed. (Another bug causes AddOnAdmin to generate an exception when you quit it after this step.) An alternative for generating the required numbers for Mac users is to obtain the numbers manually as shown next. Make a note of your LocalID (it cannot be copied to the clipboard). For our purposes here, let's say that this ID is 555999222. You'll also, just once, need to convert your four-character Developer ID into a numeric value, if GRAPHISOFT did not provide that to you. This last part is really easy on OS X. Open a Terminal window and enter:

echo <ID> | hexdump

where <ID> is your quoted four-character Developer ID. For example, suppose "abcd" is your Developer ID. You'll see this:

$ echo "abcd" | hexdump
0000000 61 62 63 64 0a

Which means that your Developer ID in hex is 0x61626364. (If you use the Save Database As button to create a header file, the Developer ID will be shown in decimal there.) Let's suppose we want the Attribute_Test example add-on to run in our licensed ARCHICAD. Open Attribute_TestFix.grc and replace this code:

'MDID' 32500 "Add-On Identifier" {
        MDID_APICD
        MDID_APICD_AttributeTest
}

with this:

'MDID' 32500 "Add-On Identifier" {
        0x61626364
        555999222
}

Alternatively, you can just edit the MDIDs_APICD.h file in the Inc folder. Give MDID_APICD your numeric Developer ID value. Use AddOnAdmin to generate enough LocalIDs for all of the examples, and replace them in that header file. (If you only want to load one example at a time, just give each one the same LocalID.) Note: Keep your Developer ID and authorization code private. The Developer ID uniquely identifies the developer to whom the ID was assigned. You would not want to potentially be liable for any damage caused by a bad add-on created by someone else using your ID.

What to do after Building?

There are two methods for loading an add-on into ARCHICAD. The usual one is to copy the add-on into any folder rooted at the Add-Ons folder within the application folder. Alternatively, you can use the Options > Add-On Manager dialog to locate the add-on (perhaps in the Debug folder for your built example). Note that once ARCHICAD is running and if the add-on is loaded from the build target location, then most of the time you can modify your code, rebuild, and immediately test the results inside ARCHICAD without closing and relaunching ARCHICAD.

Debugging

Debug Monitor application is no longer part of the API DevKit. It's not necessary, because debug messages from ARCHICAD and the Add-Ons are automatically logged by Console.app on macOS and by Visual Studio Output window on Windows. Console.app is an application provided by Apple (in the Applications/Utilities folder). It allows developers to log any important event, database state, exception, etc., by sending information to a text-based formatted output. ARCHICAD uses this output extensively. This means that a lot of information is sent to the Log window from the ARCHICAD source code. GRAPHISOFT publishes debug tools to help debugging the ARCHICAD API environment.

User Interface: Dialogs

To help developers use ARCHICAD's standard features, GRAPHISOFT makes available its cross-platform technology for resource description, compilation, and dialog management. For most of us used to creating dialogs and linking elements to their handlers in a visual environment, textual dialog construction in a grc file will feel a bit painful. The thing to keep in mind both here, and with other libraries provided in the DevKit, is that the result will be completely cross-platform. So, developed once, your dialogs will appear properly on Windows as well as Mac.

Many examples can be found in the example Add-Ons (especially DG_Test) provided by DevKit. Study the documentation, and in particular, locate the document titled “What’s the required format of User Controls in the .grc file?” in the DevKit documentation. This last document is essential to understanding how to get common graphic UI controls such as attribute selection to appear in your own dialogs.

The document “GRC Specification of the Dialog Types” in Dialog Manager documentation explains the syntax for the different dialog resources in a Graphisoft Resource Compiler (grc) file. From API20 the recommended source image formats of icon resources are SVG, this helps to build HiDPI compatible user interface. For a better understanding of the GRAPHISOFT Resource Compiler, see a Windows example and a Macintosh example in the API documentation. These articles show good examples of how to create our own dialogs in ARCHICAD.