Graphisoft®

API Development KitVersion: 15

API White Paper

 

  1. Basic questions
    1. What is API Development Kit?
    2. Why do we need add-ons?
    3. What sort of add-ons are needed?
    4. Is API the only way?
    5. Who can do API development?
  2. Technical description
    1. Database tools
    2. Interface tools
    3. Integration tools
    4. Development tools
  3. Examples
  4. Summary

 


Basic questions

 

What is the API Development Kit?

API means "Application Programming Interface"; a software environment that programmers can use to create tools (or "add-ons") enhancing the functionality of ArchiCAD.

 

Why do we need add-ons?

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").

 

What sort of add-ons are needed?

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.

Customization

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.

 

Is API the only way?

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).

 

Who can do API development?

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.

 


Technical Description

 

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:

Database tools

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).

Interface tools

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.

Integration tools

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.

Development tools

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.

  

Database tools

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:

Starting with API v4.1 developers can also access other information related to the Virtual Building database, e.g.:

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.

 

Interface tools

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:

Dialog boxes

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.).

Palettes

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.

Cursor control

Developers are also allowed to control various cursor attributes (shapes, sensitivity, plane), while the graphical input services are running.

New windows

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.

 

Integration tools

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:

Database changes

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".

Project change

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.

Library change

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.".

Selection change

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).

 

Development tools

The sole purpose of these tools is to make the development easier, faster, less prone to errors.

 


Examples

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

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.

Profiler

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.

 


Summary

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.