[分享]：API-WHITE PAPER

xiaogengxu

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 ArchiCAD.exe 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 by API (e.g. the DXF/DWG I/O or the construction grid function in the Japanese version) 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?
Anybody, who a) experienced in C or C++ programming language b) becomes Graphisoft Developer Partner. 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.


--------------------------------------------------------------------------------

Version history / New functionality
Graphisoft first released the API Development Kit in 1998 (version 1.3), simultaneously with ArchiCAD 6.0. The second release (version 2.1) was shipped with ArchiCAD 6.5. Now, with the release of ArchiCAD 7.0 we are proud to present API Development Kit 3.1, an upgraded and greatly enhanced version. The new release addresses most of the discovered shortcomings, and we are convinced that it will allow greater functional and interface flexibility, greater reliability and easier development environment than the previous version.

The most important enhancements in API v3.1 are:

Inter-Add-On communication,
Possibility to place custom data into the ArchiCAD project files
Interface enhancements: richer support of getting user input
Access to element information on the Section/Elevation and 3D windows

--------------------------------------------------------------------------------

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,
Interface tools

These functions allow to create graphical user interface (GUI) to the API add-ons.
Integration tools

These functions provide various possibilities to tightly integrate the API add-ons to the ArchiCAD environment by catching ArchiCAD "events".
Development tools

These are various software tools which make the development easier.
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 VB's database elements, notably to:

all elements on the Floor Plan and Section/Elevations (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
Besides, API v3.1 also capable to access other information related to the VB database, e.g.:

projects preferences,
projects 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.

Interface tools
To perform changes in the VB's 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 (16 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,
creation 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). 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 (modeless dialog windows) which can stay open during the entire length of operation if necessary. Similarly to dialog boxes, developers can access and use the DG Library 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.
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 the event automatically, with no user action required. 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. In API v3,1 developers are capable to get information about the following events:

Database change

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 VB 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.
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, than, 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 tool 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 have 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 as a 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 v3.1 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. At the same time we intend to do our utmost to maintain backward compatibility in order to protect the investment of our developer partners.

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.


Built on January 11, 2001.

wolfkingforever

没有开发包，一切都是空谈。