API Development KitVersion: 10

Frequently Asked Questions

This collection answers to the most frequently asked API related questions.

I receive this error message: "This add-on cannot be validated. Please contact the distributor." What is the problem?
How do I create a template library part to be used in my add-on?
How do I create an associative dimension in ArchiCAD 8?
(Win only) My add-on runs perfectly on my development machine, but when I install it on a demo machine it refuses to load.
Can I compile a GDL add-on, which uses the services of the General API DevKit?
How can I catch notifications immediately?
We defined an icon in the GRC file in the 3.1 DevKit, but they doesn't seem to appear with 6.1, and I also receive a resource conversion error. Also, what do those three numbers mean in the resource?
I'm creating a library part from my add-on, and I also put in a preview picture, but it doesn't appear.
Is there a default callback for the simple popup menu-like custom control?
(Win only) When I link my add-on, I receive the following warning: "LINK : warning LNK4098: defaultlib "MSVCRT" conflicts with use of other libs; use /NODEFAULTLIB:library"
How can I open a progress window when I have a long process running?
I have a function which adjusts the additional parameter values of a placed object/window/door. It works fine in ArchiCAD 7, but not in ArchiCAD 8 or 9.
When I read 3D data for an element I don't get the correct 3D-vertex world-coordinates. They are local coordinates for that element. So how can I retrieve the correct vertex information in world coordinates of an element?
How can I make the standard DXF/DWG add-on export elements into DWG file?
What's the required format of User Controls in the .grc file?

I receive this error message: "This add-on cannot be validated. Please contact the distributor." What is the problem?

Several problems may lead to this message:

The add-on cannot be loaded, because the dll / shared library cannot be loaded. This usually indicates a missing library, or some initialization failure. The first problem can be detected by the Depends.exe application on Windows (it's part of the MS tool suite), or the PEFViewer application on the Mac (part of Apple's Developer Tools). The second problem is usually in the add-on's code :))
The add-on was not compiled with the DevKit required by the server application.
The add-on doesn't have an 'MDID' resource, or the 'MDID' resource doesn't contain valid information. This may be caused by:
- Mac: the add-on doesn't have a resource fork, because of an invalid transfer through internet or file system.
- the MDID resource was not compiled into the add-on.
- the MDID resource contains demo IDs (e.g. developer ID is 1 and the local ID is 1)
- the MDID clashes with another add-on's MDID; in this case ArchiCAD refuses to load any of these add-ons.
- there's a typo in the developer ID, or in the authorization code. In this case the generated local ID looks valid, but ArchiCAD still rejects to load the add-on. Try to double-check the ID and the code with Graphisoft.

How do I create a template library part to be used in my add-on?

You can find the answer here.

How do I create an associative dimension in ArchiCAD 8?

An example from the Automatic Dimensioning add-on shows how you can convert the old neig IDs to the new bool fields in API_Base:

bool    NeigID2Line (API_NeigID neigID)
{
    return (neigID == APINeig_WallOn          ||
            neigID == APINeig_WallPlOn        ||
            neigID == APINeig_WallPlOnClOff   ||
            neigID == APINeig_BeamOn          ||
            neigID == APINeig_CeilOn          ||
            neigID == APINeig_RoofOn          ||
            neigID == APINeig_MeshOn          ||
            neigID == APINeig_HatchOn         ||
            neigID == APINeig_LineOn          ||
            neigID == APINeig_ArcOn           ||
            neigID == APINeig_SplineOn);
}

bool    NeigID2Special (API_NeigID neigID)
{
    return   (neigID == APINeig_WallPl    || neigID == APINeig_WallPlOn ||
              neigID == APINeig_WallPlClOff || neigID == APINeig_WallPlOnClOff ||
              neigID == APINeig_BeamHole  ||
              neigID == APINeig_WindHole  ||
              neigID == APINeig_DoorHole  ||
              neigID == APINeig_MeshRidge || neigID == APINeig_MeshRidgeOn);
}

static void MakeDimelemForWD (API_DimElem* dimelem, const MyCoord& mc)
{
    WallRef     wr;
    long        i;

    for (i = 1; i <= mc.wrs.Count (); i++) {
        wr = mc.wrs[i];

        if (wr.openingpt != NOOPENINGPT) {
            dimelem->base.base.typeID  = (wr.iswindow ? API_WindowID : API_DoorID);
            dimelem->base.base.special = true;
            dimelem->base.base.line    = false;
            dimelem->base.base.index   = wr.wdindex;
            dimelem->base.base.unId    = wr.unId;
            switch (wr.openingpt) {
                case OPENINGPT0:
                    dimelem->base.base.inIndex = wr.inIndex;
                    break;
                case OPENINGPT1:
                    dimelem->base.base.inIndex = wr.inIndex;
                    break;
                default:
                    dimelem->base.base.inIndex = 4;   // center
                    break;
            }
            return;
        }
    }

    // Error if it comes here...
    return;
}

(Win only) My add-on runs perfectly on my development machine, but when I install it on a demo machine it refuses to load.

This usually happens from one of the following reasons:

Visual Studio installs its own runtime libraries (MSVCxx.DLL and MSVCPxx.DLL) in the WINNT\System32 folder, and the APX is usually dynamically linked to those, i.e. it expects the DLLs to be there. On the systems you didn't install Visual Studio, the DLLs are simply not there. You can try to solve this by copying those files over to the appropriate place from the machines where you have Visual Studio installed.
Note: ArchiCAD installs the necessary runtime libraries if they are not there.
You are trying to install a debug version of your add-on onto the demo machine. This won't work, because it is linked to the debug libraries of Visual Studio, which are not present on the demo machine. Compile a release version instead.

Can I compile a GDL add-on, which uses the services of the General API DevKit?

No. GDL add-ons use their own API environment, and that mixes quite badly with the General API running environment.

How can I catch notifications immediately?

Return APIAddon_Preload from your CheckEnvironment () function. This will ensure that your Initialize () function will be called immediately after the call to Registerface (), without requiring the user to perform any action. You can then safely install the notification callback function(s) from Initialize ().

We defined an icon in the GRC file in the 3.1 DevKit, but they doesn't seem to appear with 6.1, and I also receive a resource conversion error. Also, what do those three numbers mean in the resource?

'GICN' 32501 "General Settings" {
   0  128  128
}

The '0 128 128' is the RGB color of the transparent area in the icon; in the range 0-255. The reason why is doesn't compile with DevKit 6.1 is because some of the colors (black and white) should be in fixed places within the icon's color table: black should be the first color, and white should be the last. Note that the icons are converted to 32-bit depth, so you cannot use arbitrary big sizes.

I'm creating a library part from my add-on, and I also put in a preview picture, but it doesn't appear.

From ArchiCAD 8 you should add the MIME type of the preview picture as a C string (with the terminating 0) to the beginning of the data handle containing the preview picture. (e.g. "image/png\0" for a PNG image)

Is there a default callback for the simple popup menu-like custom control?

No. You'll have to write your own callback to load the data from your resource file, and pass it to the user control with UC257SetData. You'll also have to call UC257SetType, and possibly UC257SetStyle. The DG_Test example now shows how you can work with these functions.

(Win only) When I link my add-on, I receive the following warning:
LINK : warning LNK4098: defaultlib "MSVCRT" conflicts with use of other libs; use /NODEFAULTLIB:library

This only means that you are compiling the debug version of your add-on (thus linking to the debug version of the runtime DLLs), whereas the libraries shipped with the DevKit are release versions (which are linked to the release version of the runtime DLLs). This doesn't cause any problem.

How can I open a progress window when I have a long process running?

In several ways:

use the set of ACAPI_Interface functions (APIIo_InitProcessWindowID, etc.) provided by the API. This has a small problem: other processes within ArchiCAD are using the same progress window, and they can interfere with the information displayed by your add-on.
use your own modeless palette as a process window.
open a modal dialog, and drive the process from there. Since DevKit v4.1 you can switch databases even if a modal dialog is visible on the screen. See the Do_ProgressWindow function in the DG_Test example. This is the recommended solution at the moment.

I have a function which adjusts the additional parameter values of a placed object/window/door. It works fine in ArchiCAD 7, but not in ArchiCAD 8 or 9.

This problem usually occurs when you refer to the additional parameters by indices:

(*memo.params)[27].value.real = 7.25;

The problem is coming from the subtype hierarchy: an object/window/door in the hierarchy inherits the parameters of all of its ancestors. So, you should refer to a parameter by name instead of its index. This also means you'll have to look up the parameter by name before modify its value:

static void SetParValue (API_AddParType *** addPars, const char * name, const double &val)

{
    if (addPars == NULL || *addPars == NULL)
        return;

    long ii, addParNum = BMGetHandleSize (reinterpret_cast<GSHandle> (*addPars)) / sizeof (API_AddParType);
    for (ii = 0; ii < addParNum; ii++) {
        if (CHCompareCStrings ((**addPars)[ii].name, name, CS_CaseInsensitive) == 0) {
            (**addPars)[ii].value.real = val;
            break;
        }
    }

    return;
}   // SetParValue

When I read 3D data for an element I don't get the correct 3D-vertex world-coordinates. They are local coordinates for that element. So how can I retrieve the correct vertex information in world coordinates of an element?

Each 3D body contains a transformation matrix (see API_BodyType), which should be applied to the coordinates of the vertices. This allows us to store a body which has several instances very compactly (i.e. store the vertices just once, and have a different transformation matrix for every instance).

How can I make the standard DXF/DWG add-on export elements into DWG file?

You can find a simple example at the description of the ACAPI_Command_Call function.

What's the required format of User Controls in the .grc file?

The detailed description is here.