API White Paper
- Basic questions
- Technical description
API means "Application Programming Interface"; a software environment that programmers can use to create tools (or "add-ons") enhancing the functionality of ArchiCAD.
While ArchiCAD's functionality grows rapidly version by version, it cannot and should not satisfy all the various needs of the A/E/C market in one shrink-wrapped solution. It cannot because the needs of some local or specialized markets are widespread (and sometimes contradictory) and should not because even if we manage to do so, the result would be a confusing and thus mostly unusable software-giant.
Graphisoft's development policy is to keep ArchiCAD relatively "lean and mean"; that is to provide in the core ArchiCAD only what can be regarded as universally (= worldwide) needed. That is the core A/E/C functionality. The API Development Kit provides the possibility to create necessary custom functionality in the form of add-ons. It is important to note that having add-ons does not necessarily mean that users have to "assemble" their solutions from bits and pieces. These add-ons can be a part of the ArchiCAD installer and can be totally indistinguishable for users from the "hard-wired" core functionality. In fact, there are already several functions in ArchiCAD which were created using the API (e.g. the DXF/DWG I/O or the construction grid function) and part of the standard installation (see more at "Examples").
There are three main areas where additional functionality is needed.
Creating local functionality
Besides the obvious universal aspects of the architectural and construction industry, practically every country or region has its own distinct features in design, structure, local regulations, etc. These needs ought to be satisfied, but without burdening users who do not need it. We at Graphisoft want to work closely with our local partners to create this "local" functionality and - if certain conditions are met - localized versions can include this in the ArchiCAD installer.
Creating special functionality
There is an increasing need for "vertical" solutions based on ArchiCAD for special areas such as log house design, 2X4 housing etc. These are not necessarily local, e.g. log house design has very similar requirements in Scandinavia and USA. Typically, such solutions are best received by the market if contained in a shrink-wrapped "special solution" (e.g. ArchiCAD for Log House Design). It is a strategic goal for Graphisoft to develop such ArchiCAD-based vertical solutions. Our developer partners can also initiate and create such solutions independently or in cooperation with us.
As a growing number of large companies use ArchiCAD, the need for customization is increasing. With the help of Graphisoft's API technology now these requests can be satisfied quickly and locally by our developer partners. It also creates an additional, potentially lucrative revenue source for local distributors and resellers.
API development is not the only way to provide extra functionality or to customize ArchiCAD. From the very early days ArchiCAD offered customization possibilities through GDL programming and GDL has still remained a very important tool for customization. GDL objects can naturally be reached by API add-ons and in fact - as explained in the Examples - the combined use of GDL objects and API add-ons is one of the most powerful ways to enhance ArchiCAD's functionality. Besides, since ArchiCAD 6.0, the listing functions can be customized as well. These three programming environments provide a wide range of tools with the help of which one can successfully tackle the various problems in the A/E/C market. GDL and listing programming, however, are not part of the current discussion, to learn about them please refer to the appropriate manual (part of the ArchiCAD package).
API developers have to be experienced in C or C++ programming language. For the procedural aspects please visit the Policy section of the Developer website. Naturally, it is not enough to know how, but what to develop. Therefore, it is a prerequisite to have a thorough knowledge of ArchiCAD's functionality.
The aim of the API Development Kit is to provide our development partners a way to develop add-ons that can access and modify the Virtual Building's database. The API software tools can be divided into four major groups according to their functionality:
These functions allow to access the Virtual Building's database, and perform changes in it. A good example for this is the Modify Wall add-on, which performs various operations on walls (e.g. moves the reference line to the other side of the wall).
These functions allow to create graphical user interface (GUI) to the API add-ons. A good example is the Profiler, which allows the user to create revolved and tubular objects. It relies on both the platform-indepent Dialog Manager, and the input services of API.
These functions provide various possibilities to tightly integrate the API add-ons to the ArchiCAD environment by catching ArchiCAD "events". A simple example is the Selections add-on, which can store and restore favorite selections of the user. It catches all changes of the selection (select, deselect), and modifies the status of its interface elements accordingly.
These are various software tools which make the development easier. A good example for this is the Modify Library Parts add-on for library developers, which allows batch modification of library parts.
In most of the cases the main reason behind creating an add-on is to perform changes in the Virtual Building's database. These functions provide practically unlimited access to the Virtual Building database elements, notably to:
- all elements on the Floor Plan, Section/Elevations and Detail Drawings (including the selection and 3D information),
- relations among these elements (e.g. wall intersections),
- element's attributes,
- library items (in the active libraries but not necessarily placed in the project),
- listing database
Starting with API v4.1 developers can also access other information related to the Virtual Building database, e.g.:
- project preferences,
- project settings,
- 3D window settings
Using these tools, one can receive information, change, create and delete any elements in the ArchiCAD database. That is, using API one can write a tool that e.g. after the user selects a wall and activates the API command, checks the wall's geometric parameters and - by calculating and assigning the necessary parameters to a previously written GDL object - replaces it with a library item containing the detailed geometric data of a curtain wall.
To perform changes in the Virtual Building database the user must first be able to communicate his intentions to the add-on, that is, a graphical user interface is necessary. The API offers a greatly enhanced array of tools to let developers select the most suitable interface solution for a given problem. The following possibilities are at the disposal of developers:
Creating new menu items
Developers using the API can create new menu items within the standard ArchiCAD menu structure (more than 15 possible insertion points). Moreover, creation of completely new menus also became possible from API v2.1. Standard menu-enhancement methods are also possible such as:
- cascading menus (submenus),
- creation of custom menu icons,
- addition and removal of check marks,
- graying out unused menus (depending on the context),
- context-dependent, interactive modification of menu items.
API commands can open dialog boxes (modal dialogs and palettes). Here all the standard ArchiCAD interface elements are at the developers' disposal. This feature allows developers to access the standard ArchiCAD Interface Toolbox (called DG library) and provide an "ArchiCAD look and feel" interface using the standard interface components (pen palettes, layer popup etc.).
API commands can also open palettes which can stay open during the entire length of operation if necessary. Similarly, developers can access and use the DG Library for modal dialog boxes as well.
Note: using this feature, new toolboxes can be created for API tools as well.
Graphical input from ArchiCAD
A rich set of methods support graphical input from an ArchiCAD project during the course of an API command. It is possible to force the user to give geometric information of a point, line, arc or polygon. From API v4.1 you can also create your own pet palette.
Developers are also allowed to control various cursor attributes (shapes, sensitivity, plane), while the graphical input services are running.
Since API v2.1, developers can freely open new text and drawing windows and use ArchiCAD's all 2D drafting engine for creating any sort of drawing or diagram.
Note: It is not possible to alter or hide parts of the standard ArchiCAD interface, only additions can be created to accommodate the new API add-ons.
While some API add-ons are entirely controlled by user actions through the GUI, in some cases developers may wish to start an event automatically, without any user interaction. Naturally, the two methods can be combined. Thus the API add-ons can be tightly integrated into ArchiCAD's working environment by linking standard ArchiCAD events with API add-on actions.
With these functions various user actions can be monitored and used as a "trigger" for other add-on actions. From API v4.x developers are capable to get information about the following events:
A change in the project is the event that triggers an action from the API add-on. E.g. if a roof window is moved, an add-on - catching the event - automatically adjusts the hole on the roof (just like in the case of windows linked to walls).
Creation of a new element
A new element added to the Virtual Building database may start an API add-on action as well. E.g. if a certain type of wall is created, an API add-on automatically creates footing for the wall.
Parameter setting change
While there is no change in the project database, a change in a parameter setting occurs. E.g. if the user selects a certain wall parameter setting in the Wall tool, it may trigger a warning message, saying "Using this width is against the office standards".
Something happens to the whole project that triggers the add-on's action. E.g. activating "Save as " or "Send and receive " may trigger an API add-on that automatically creates a backup or sends a notification about the action.
The state of the loaded libraries may change. E.g. the user unloads a library which contains elements necessary to use the add-on. In this case the add-on may post a warning to the user saying "Please reload the xxx library.".
The element selection changed. E.g. the user selects a different element on the floor plan. Then an add-on may update an information palette (see the Element Information add-on).
The sole purpose of these tools is to make the development easier, faster, less prone to errors.
In the following we would like to present three API add-on
examples that were developed by Graphisoft. These tools are very
different in their functionality (I/O extension, architectural
detailing, general modeling respectively), in their packaging
(universally bundled add-on, mostly bundled with locally different
content and free "goodie" downloadable from Graphisoft's websites)
and naturally in their appearance. They represent the versatility
that ArchiCAD's API offers and we hope it will inspire our developer
partners in their work.
DWG/DXF I/O add-on
This add-on is responsible for ArchiCAD's DWG and DXF read and write functionality. It is a standard part of all ArchiCAD packages. Therefore it may sound illogical to implement it as an add-on. However, DWG and DXF formats often change and usually these changes do not coincide with our usual upgrade cycle. Despite of this, we must be able to keep up with these changes as quickly as possible for the convenience of our users. The DWG/DXF I/O add-on offers us a chance to make adjustments in the DWG or DXF output without changing ArchiCAD's source code (which would be a lot more time-consuming process).
The add-on's interface is fairly simple, but the technology behind it is rather complex.
Similarly, if the necessary information is available, API developers can create I/O add-ons to practically any CAD or CG software.
RoofMaker - as its name suggests - creates roofs for ArchiCAD projects. The architect first designs the roof with ArchiCAD's Roof tool, then, using RoofMaker's parametric features, with a few clicks he or she is able to create a complex roof structure with beams, rafters etc. The new roof objects (placed by the API) are parametric GDL library parts and therefore can be easily modified later.
However, the problem is that roof structures are different in Europe and US (not to speak about complex Japanese roofs !) and it would be very difficult to accommodate all in one tool (and keeping the interface simple ). For this reason we decided that - instead of hard-coding a roof-creation tool into ArchiCAD - RoofMaker should be an add-on, customized to the major local markets. Thus - thanks to the API's plug-in architecture - we could satisfy local demands without compromising the unity of the core application.
It is important to note that besides the API add-on that places the GDL objects, there is a fair amount of GDL programming involved in the development of RoofMaker. Actually, this pattern - an API add-on placing and defining previously loaded GDL objects - is one of the most typical and powerful add-on solutions, combining the strength of GDL and API.
ArchiCAD is often criticized that while GDL is indeed a very versatile tool for complex geometry, the average user has difficulties to learn GDL scripting. Profiler is an add-on tool that combines GDL's flexible geometry with the ease of use of the ArchiCAD interface. With Profiler users can utilize the power of GDL's "Rotate" and "Sweep" commands without even opening the GDL editor. In this case, however, the API does not simply give parameters to previously loaded GDL objects, but creates them on the fly (users have to name them, of course). This way Profiler can maintain higher flexibility in creating free-form elements.
On longer term we feel that it may become necessary for ArchiCAD to accommodate such functionality in the core application as well. However, at the moment we decided not to make Profiler part of the package but keep it as a "goodie"; an add-on tool that can be freely downloaded from Graphisoft's websites.
API v12 is a mature, modern development environment that allows Graphisoft and its partners to create a wide range of add-ons for the benefit of users. We at Graphisoft - being not only the developer but at the same time the user of the API technology - are committed to continuously upgrading the API Development Kit along with the subsequent releases of ArchiCAD.
We welcome any report of possible bugs or suggestions how to improve the functionality of API. Graphisoft will do its best to incorporate these requests to the future releases of the API Development Kit.