API White Paper

[Doreena Deng]

1. 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 only some of 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, largely unusable software giant.

Graphisoft's development policy is to keep Archicad relatively "lean and mean"; that is, to provide only what can be regarded as universally (= worldwide) needed in Archicad — the core A/E/C functionality. The API Development Kit allows the creation of 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 indistinguishable for users from the "hard-wired" core functionality. In fact, there are already several functions in Archicad that 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 the "3. Examples" section below).

What sort of add-ons are needed?

There are three main areas where additional functionality is needed.

• Creating local functionality: Besides the apparent universal aspects of the architectural and construction industry, practically every country or region has its distinct features in design, structure, local regulations, etc. These needs should be satisfied without burdening users who do not need them. 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 particular functionality: There is an increasing need for "vertical" solutions based on Archicad in specific areas such as log house design, 2X4 housing, etc. These are not necessarily local; e.g., log house design has similar requirements in Scandinavia and the USA. Typically, the market best receives such solutions 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 many 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 a 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 remained an essential tool for customization. API add-ons can naturally reach GDL objects, and in fact - as explained in the "3. Examples" section below - the combined use of GDL objects and API add-ons is one of the most potent ways to enhance Archicad's functionality. Besides, 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 are not part of the current discussion. Please refer to the appropriate manual (part of the Archicad package) to learn about them.

Who can do API development?

API developers have to be experienced in C or C++ programming languages. Of course, knowing how but not what to develop is not enough. Therefore, having a thorough knowledge of Archicad's functionality is a prerequisite.

 

2. Technical Description

The API Development Kit aims to provide our development partners with 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 access to the Virtual Building's database and perform changes. You can find an excellent example in the Element Test example add-on.
• Interface tools: These functions allow the creation of a graphical user interface (GUI) for the API add-ons. A good example is the Profiler, enabling users to create revolved and tubular objects. It relies on both the platform-independent 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 the favorite selections of the user. It captures all changes in the selection (select, deselect) and modifies the status of its interface elements accordingly.
• Development tools: These are various software tools that make development easier. You can find an excellent example in the LibPart Test example add-on.

Database tools

In most 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

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

API developers can create new menu items within the standard Archicad menu structure (more than 15 possible insertion points). Moreover, developers can create entirely new menus also. 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.

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 popups, etc.).

Palettes

API commands can also open palettes that can stay open during the entire operation if necessary. Similarly, developers can also access and use the DG Library for modal dialog boxes.

‍Note: using this feature, new toolboxes can also be created for API tools.

Graphical input from Archicad

A rich set of methods support graphical input from an Archicad project during an API command. It is possible to force the user to give geometric input of a point, line, arc, or polygon. You can also create your pet palette.

Cursor control

Developers can also control cursor attributes (shapes, sensitivity, plane) while the graphical input services run.

New windows

Developers can freely open new text and drawing windows and use Archicad's all-2D drafting engine for creating any drawing or diagram.

‍Note: It is impossible 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 user actions entirely control some API add-ons through the GUI, 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.

These functions allow various user actions to be monitored and used as a "trigger" for other add-on actions. Developers are capable of getting 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 also start an API add-on action. E.g., if a specific 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 particular 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 that contains elements necessary to use the add-on. In this case, the add-on may warn the user, "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 development easier, faster, and less prone to errors.

 

3. Examples

In the following, we would like to present three API add-on examples that Graphisoft developed. 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 Archicad's API's versatility, 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 do not coincide with our usual upgrade cycle. Despite 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 allows us to adjust 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 relatively simple, but the technology behind it is rather complex.

Similarly, API developers can create I/O add-ons to practically any CAD or CG software if the necessary information is available.

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, they can 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 the US (not to speak about complex Japanese roofs !), and it would not be easy to accommodate all in one tool (and keep 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 essential to note that besides the API add-on that places the GDL objects, a fair amount of GDL programming is involved in the development of RoofMaker. This pattern - an API add-on placing and defining previously loaded GDL objects - is one of the most typical and robust add-on solutions, combining the strength of GDL and API.

Profiler

Archicad is often criticized that while GDL is a very versatile tool for complex geometry, the average user needs help learning 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 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 must name them, of course). This way, Profiler can maintain higher flexibility in creating free-form elements.

In the longer term, it may become necessary for Archicad to accommodate such functionality in the core application. However, we decided not to make Profiler part of the package but keep it a "goodie," an add-on tool that can be freely downloaded from Graphisoft's websites.

 

4. Summary

The Archicad API 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 - 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 on improving API functionality. Graphisoft will do its best to incorporate these requests into future releases of the API Development Kit.