Getting Started with the API DevKit

by GRAPHISOFT and KarlOttenstein · updated: 03.01.2009


  • {i} ForWikiEditors : ToDo/ – check and update article


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 downloaded 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

The API DevKit may be freely downloaded. Without a registration code, however, any compiled add-ons will only load and function if ArchiCAD is started in “Demo” mode. To create add-ons that will load in licensed copies of ArchiCAD, you need to obtain a registration code from Graphisoft. The registration code itself is free of charge. I’ll talk about what you do with your code below.

Support

User-to-user support is available in the Developer forum of ArchiCAD-talk. Priority Developer Support is available for a fee from Graphisoft. Details.

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, as 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.

Add-ons for Mac OS X are not universal. Separate versions must be compiled with separate development tools for each of PPC Mac, Intel Mac and Windows.

For ArchiCAD 12 development, free development tools are available for Windows and MacTel. On Windows, all examples can be built using the free Microsoft Visual C++ 2005 Express Edition. Of course, if you already own Visual Studio .NET 2005, it has more features. On Intel Macs, the free Xcode is all that is required.

For PPC Macs, CodeWarrior 9 or above is required, however it is not currently supported or sold at retail; if necessary, you can find copies at auction and download sites. Do note, though, ArchiCAD 12 is the last version that will be supporting the PPC processor and that OS X Leopard (10.5) is the last version of OS X that will support PPC.

For ArchiCAD 9 through 11, Visual Studio .NET 2003 is required.

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.

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 ID’s, 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.

  • 1_new_database.png

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.

  • 2_authorization.png

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 ID’s 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:

  • 3_new_addon.png

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:

  • SaveDatabaseAsH.png

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

[From the help files:] Debug Monitor is a primary development tool [for Windows development], provided to developers to make debugging and problem identification easier. It allows developers to log any important event, database state, exception etc., by sending information to a text based formatted output.

The magic of this service is that it’s available in the final compilation also, not just in the debug version. The Debug Monitor is used by ArchiCAD extensively. This means that a lot of information is sent to the Log window from the ArchiCAD source code. It may happen that a problem is highlighted, because your functions are not perfectly coded or embedded into the environment. Please try to focus on all the information highlighted in the Log window -especially those that report problems- since the ArchiCAD world is very complex. It can happen that your functions may cause unwanted effects on other services.

On Mac OS X this application is no longer necessary, because debug messages are automatically logged by Console.app (an application provided by Apple; in the Applications/Utilities folder).

User Interface: Dialogs

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.

Study the example project DG_Test, the Dialog Manager documentation, and in particular, locate the 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” explains the syntax for the different dialog resources in a Graphisoft Resource Compiler (grc) file.

Please post any comments, errors, or suggestions on this article in the Developer forum of ArchiCAD-talk.

Related content

graphisoftid--login

GRAPHISOFT ID

updated 2013-09-30 What is GRAPHISOFT ID GRAPHISOFT ID (GS ID for short) is a unique identifier, based on users’ email addresses, to allow unified login to various web systems managed by GRAPHISOFT. Each user only needs one GS ID to login to multiple…

Intel Mac platform

"MacTel" refers to the Intel-powered Macintosh platform. Apple abandoned the previously used PowerPC processors in favor of the Intel chips in 2006. This new platform also requires software vendors to release a new version of their products that run…